Porter un Slack Bolt pour l’application JavaScript vers Teams

Ce guide vous aidera à porter sur Teams un boulon de mou existant pour une application JavaScript.

Introduction

Semblable à Slack Bolt, le SDK Teams est conçu pour s’interfacer avec les API principales de Teams pour la création d’applications conversationnelles. Les deux SDK fournissent des abstractions pour gérer les événements entrants, les messages et les interactions, ainsi que pour renvoyer des réponses aux utilisateurs. Si vous disposez déjà d’un bot Slack, les concepts doivent vous sembler familiers.

Il existe toutefois quelques différences essentielles, telles que l’installation d’applications. Dans Slack, les applications sont installées dans les espaces de travail via OAuth, tandis que dans Teams, elles sont installées via l’App Store Teams. En outre, les applications Teams peuvent être installées personnellement par des utilisateurs individuels ou dans des étendues collaboratives telles que des conversations de groupe, des canaux et des réunions.

Examinons quelques similitudes et différences entre les concepts de Slack et de Teams :

Inscrire un agent Teams

Tout d’abord, suivez le guide de démarrage rapide pour inscrire un nouvel agent Teams, afin de pouvoir l’utiliser à partir de Teams dès que vous avez ajouté l’implémentation du Kit de développement logiciel (SDK) Teams à votre application existante.

Installer le SDK Teams

Installez le Kit de développement logiciel (SDK) Teams dans votre projet Slack Bolt :

npm install @microsoft/teams.apps

Copier la configuration de l’authentification

Copiez les paramètres du fichier créé par l’interface de ligne de .env commande du développeur Teams dans l’application de démarrage rapide vers votre implémentation Slack Bolt. Ces paramètres sont des informations d’identification permettant d’authentifier une application SDK Teams afin qu’elle puisse communiquer avec Teams.

Initialiser le runtime

Ajoutez ou remplacez du code dans votre implémentation pour démarrer le runtime d’application du kit de développement logiciel (SDK) Teams à l’aide de la App classe. C’est l’équivalent de la classe 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();
})();

Ajouter des gestionnaires de messages

Dans Slack, il existe des gestionnaires de messages pour les événements avec différents sous-types (par exemple, un sous-type non défini est un message normal, event.subtype == 'file_share' est un message de partage de fichiers, etc.). Dans Teams, il existe différents Activity gestionnaires pour différents types d’événements qui sont énumérés via l’énumération ActivityTypes (par exemple, app.activity(ActivityTypes.Message)), certains Activity types ayant des API adaptées dans le SDK (par exemple, app.message). Ces concepts sont à peu près similaires, bien que les conventions de nommage et la syntaxe diffèrent.

// 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 l’utilisation du kit de blocs en cartes adaptatives

Pour inclure une interface utilisateur enrichie dans les messages envoyés par votre agent, les cartes adaptatives de Teams sont équivalentes au kit de blocage 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!',
                },
            },
        ],
    });
});

Implémenter l’authentification utilisateur

Il existe deux principaux types d’authentification utilisateur pour Teams et Slack : l’authentification pour les API REST Slack & Graph et l’authentification pour les services externes. Jetons un coup d’œil à chacun d’entre eux tour à tour.

API REST déléguées par l’utilisateur

Dans Slack, si vous souhaitez utiliser des API REST de Slack qui nécessitent des étendues déléguées par l’utilisateur, vous devez implémenter un flux d’installation OAuth 2.0 dans votre application pour obtenir et stocker des jetons utilisateur Slack, même si l’application a déjà été installée par un autre utilisateur. Dans Teams, vous pouvez tirer parti de l’authentification unique Teams pour obtenir des jetons utilisateur Entra pour appeler des API REST Graph. Le SDK Teams s’intègre à Teams SSO et à Azure Bot Token Service pour gérer automatiquement l’acquisition, le stockage et l’actualisation des jetons.

Tout d’abord, suivez les instructions du guide Authentification unique Teams. Ensuite, configurez l’authentification dans votre code.

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));
});

Authentification utilisateur pour les services externes

Dans Slack, vous pouvez accéder à des services externes en implémentant un flux de liaison de compte à l’aide d’OAuth 2.0, comme indiqué ici. Dans Teams, vous pouvez accéder à des services externes en implémentant un flux OAuth 2.0, avec le service de jeton Bot Azure qui gère l’acquisition, le stockage et l’actualisation des jetons.

Tout d’abord, configurez vos paramètres de connexion OAuth 2.0 dans le portail Azure pour votre ressource Azure Bot.

Ensuite, ajoutez le code d’authentification à votre application pour obtenir le jeton utilisateur approprié et appeler votre service externe.

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));
});