Portabilidad de una aplicación Slack Bolt para JavaScript a Teams

Esta guía le ayudará a migrar una aplicación existente de Slack Bolt para JavaScript a Teams.

Introducción

Al igual que Slack Bolt, el SDK de Teams está diseñado para interactuar con las API de back-end de Teams para crear aplicaciones conversacionales. Ambos SDK proporcionan abstracciones para controlar los eventos, mensajes e interacciones entrantes, así como para enviar respuestas a los usuarios. Si ya tiene un bot de Slack, los conceptos deberían resultarle familiares.

Sin embargo, hay algunas diferencias clave, como la instalación de aplicaciones. En Slack, las aplicaciones se instalan en áreas de trabajo a través de OAuth, mientras que en Teams se instalan a través de la App Store de Teams. Además, las aplicaciones de Teams pueden ser instaladas personalmente por usuarios individuales o en ámbitos de colaboración como chats grupales, canales y reuniones.

Echemos un vistazo a algunas similitudes y diferencias entre los conceptos de Slack y Teams:

Registrar un agente de Teams

En primer lugar, complete el inicio rápido para registrar un nuevo agente de Teams, de modo que pueda usarlo desde Teams tan pronto como haya agregado la implementación del SDK de Teams a su aplicación existente.

Instalar el SDK de Teams

Instale el SDK de Teams en su proyecto de Slack Bolt:

npm install @microsoft/teams.apps

Copiar configuración de autenticación

Copie la configuración del .env archivo que la CLI para desarrolladores de Teams creó en la aplicación de inicio rápido en la implementación de Slack Bolt. Estas configuraciones son credenciales para autenticar una aplicación SDK de Teams para que pueda comunicarse con Teams.

Inicializar el tiempo de ejecución

Agregue o reemplace código en la implementación para iniciar el tiempo de ejecución de la aplicación del SDK de Teams con la App clase. Esto es equivalente a la clase de App Slack Bolt.

import { App } from '@microsoft/teams.apps';

const app = new App();

app.start(process.env.PORT || 3978).catch(console.error);

const app = new App({
    signingSecret: process.env.SLACK_SIGNING_SECRET,
    clientId: process.env.SLACK_CLIENT_ID,
    clientSecret: process.env.SLACK_CLIENT_SECRET,
    scopes: [
        "channels:manage",
        "channels:read",
        "chat:write",
        "groups:read",
        "incoming-webhook",
    ],
    installerOptions: {
        authVersion: "v2",
        directInstall: false,
        installPath: "/slack/install",
        metadata: "",
        redirectUriPath: "/slack/oauth_redirect",
        stateVerification: "true",
        /**
        * Example pages to navigate to on certain callbacks.
        */
        callbackOptions: {
            success: (installation, installUrlOptions, req, res) => {
                res.send("The installation succeeded!");
            },
            failure: (error, installUrlOptions, req, res) => {
                res.send("Something strange happened...");
            },
        },
        /**
        * Example validation of installation options using a random state and an
        * expiration time between requests.
        */
        stateStore: {
            generateStateParam: async (installUrlOptions, now) => {
                const state = randomStringGenerator();
                const value = { options: installUrlOptions, now: now.toJSON() };
                await database.set(state, value);
                return state;
            },
            verifyStateParam: async (now, state) => {
                const value = await database.get(state);
                const generated = new Date(value.now);
                const seconds = Math.floor(
                    (now.getTime() - generated.getTime()) / 1000,
                );
                if (seconds > 600) {
                    throw new Error("The state expired after 10 minutes!");
                }
                return value.options;
            },
        },
    },
});

// App starts local server with route for /slack/events
(async () => {
    await app.start();
})();

Agregar controladores de mensajes

En Slack, hay controladores de mensajes para eventos con diferentes subtipos (por ejemplo, subtipo no definido es un mensaje normal, event.subtype == 'file_share' es un mensaje de recurso compartido de archivos, etc.). En Teams, hay diferentes Activity controladores para diferentes tipos de eventos que se enumeran a través de la ActivityTypes enumeración (por ejemplo, app.activity(ActivityTypes.Message)), y algunos Activity tipos tienen API adaptadas dentro del SDK (por ejemplo, app.message). Estos conceptos son más o menos similares, aunque las convenciones de nomenclatura y la sintaxis difieren.

// triggers when user sends "hi" or "@bot hi"
app.message("hi", async ({ send, activity }) => {
    await send(`Hello, ${activity.from.name}!`);
});
// listen for ANY message to be received
app.on('message', async ({ send, activity }) => {
    // echo back users request
    await send(`you said: ${activity.text}`);
});

// triggers when user sends a message containing "hi"
app.message("hi", async ({ message, say }) => {
    // Handle only newly posted messages here
    if (message.subtype) return;
    await say(`Hello, <@${message.user}>`);
});
// listen for ANY message
app.message(async ({ message, say }) => {
    // Handle only newly posted messages here
    if (message.subtype) return;
    // echo back users request
    await say(`you said: ${message.text}`);
});

Convertir el uso de Block Kit en tarjetas adaptables

Para incluir una interfaz de usuario enriquecida en los mensajes enviados por el agente, las tarjetas adaptables de Teams son equivalentes al kit de bloques de Slack.

import { Card, TextBlock } from '@microsoft/teams.cards';

app.message('/card', async ({ send }) => {
    await send(
        new Card(new TextBlock('Hello, world!', { wrap: true, isSubtle: false }))
            .withOptions({
                width: 'Full',
            })
    );
});

app.message('card', async (client) => {
    await say({
        blocks: [
            {
                type: 'section',
                text: {
                    type: 'plain_text',
                    text: 'Hello, world!',
                },
            },
        ],
    });
});

Implementar la autenticación de usuario

Hay dos tipos principales de autenticación de usuario para Teams y Slack: autenticación para las API REST de Slack & Graph y autenticación para servicios externos. Echemos un vistazo a cada uno de estos a su vez.

API de REST delegadas por el usuario

En Slack, si desea usar las API de REST de Slack que requieren ámbitos delegados por el usuario, debe implementar un flujo de instalación de OAuth 2.0 en la aplicación para obtener y almacenar tokens de usuario de Slack, incluso si la aplicación ya la ha instalado otro usuario. En Teams, puede aprovechar el SSO de Teams para obtener tokens de Entra de usuario para llamar a las API REST de Graph. El SDK de Teams se integra con el SSO de Teams y el servicio de tokens de bot de Azure para administrar la adquisición de tokens, el almacenamiento y la actualización automáticamente.

Primero, siga las instrucciones de la guía de SSO de Teams. A continuación, configure la autenticación en el código.

const app = new App({
    // ... rest of App config
    oauth: {
        // The key here should match the OAuth Connection setting
        // defined in your Azure Bot resource.
        defaultConnectionName: 'graph',
    },
});

app.message('me', async ({ signin, userGraph, send }) => {
    if (!await signin()) {
        return;
    }
    const me = await userGraph.call(endpoints.me.get);
    await send(JSON.stringify(me));
});

// TODO: Configure App class with user OAuth permissions and install app for user

app.message('me', async ({ client, message }) => {
    const me = await client.users.info({ user: message.user });
    await client.send(JSON.stringify(me));
});

Autenticación de usuario para servicios externos

En Slack, puede acceder a servicios externos implementando un flujo de enlace de cuenta mediante OAuth 2.0 como se documenta aquí. En Teams, puede acceder a servicios externos implementando un flujo de OAuth 2.0 con el servicio de token de bot de Azure que gestiona automáticamente la adquisición, el almacenamiento y la actualización de tokens.

En primer lugar, configure la configuración de la conexión de OAuth 2.0 en Azure Portal para el recurso de Azure Bot.

A continuación, agregue el código de autenticación a la aplicación para obtener el token de usuario pertinente y llamar al servicio externo.

import
{ App } from '@microsoft/teams.apps';

const app = new App({
    // ... rest of App config
    oauth: {
        // The key here should match the OAuth Connection setting
        // defined in your Azure Bot resource.
        defaultConnectionName: 'custom',
    },
});

app.message('me', async ({ activity, signin, token, send }) => {
    // In production, it is probably better to implement a local cache.
    // (e.g. \`activity.from.id\` <-> token).
    // Otherwise this triggers an API call to Azure Token Service on every inbound message.
    if (!await signin()) {
        return;
    }

    // Call external API
    const response = await fetch('https://example.com/api/helloworld', {
        method: 'POST',
        headers: {
            "Authorization": token,
        },
    });
    const result = await response.json();
    await send(JSON.stringify(result));
});