Übertragen einer Slack Bolt für JavaScript-App in Teams

Dieser Leitfaden hilft Ihnen beim Portieren einer vorhandenen Slack Bolt für JavaScript-Anwendung in Teams.

Einführung

Ähnlich wie Slack Bolt ist das Teams-SDK so konzipiert, dass es eine Schnittstelle mit den Teams-Backend-APIs zum Erstellen von Unterhaltungsanwendungen bietet. Beide SDKs bieten Abstraktionen für die Verarbeitung eingehender Ereignisse, Nachrichten und Interaktionen sowie für das Zurücksenden von Antworten an Benutzer. Wenn Sie bereits einen Slack-Bot haben, sollten sich die Konzepte vertraut anfühlen.

Es gibt jedoch einige wichtige Unterschiede, wie z. B. die App-Installation. In Slack werden Apps über OAuth in Arbeitsbereichen installiert, während sie in Teams über den Teams App Store installiert werden. Darüber hinaus können Teams-Apps von einzelnen Benutzern persönlich oder in Bereichen der Zusammenarbeit wie Gruppenchats, Kanäle und Besprechungen installiert werden.

Werfen wir einen Blick auf einige Ähnlichkeiten und Unterschiede zwischen Slack- und Teams-Konzepten:

Registrieren eines Teams-Agents

Führen Sie zunächst die Schnellstartanleitung zum Registrieren eines neuen Teams-Agents aus, damit Sie ihn über Teams verwenden können, sobald Sie die Teams-SDK-Implementierung zu Ihrer vorhandenen App hinzugefügt haben.

Teams-SDK installieren

Installieren Sie das Teams SDK in Ihrem Slack Bolt-Projekt:

npm install @microsoft/teams.apps

Kopieren der Authentifizierungskonfiguration

Kopieren Sie die Einstellungen aus der Datei, die .env die Teams-Entwickler-CLI in der Schnellstartanwendung erstellt hat, in Ihre Slack Bolt-Implementierung. Diese Einstellungen sind Anmeldeinformationen für die Authentifizierung einer Teams SDK-App, damit diese mit Teams kommunizieren kann.

Initialisieren der Laufzeit

Fügen Sie Code in Ihrer Implementierung hinzu oder ersetzen Sie ihn, um die Teams SDK-Anwendungslaufzeit mithilfe der App Klasse zu starten. Dies entspricht der Klasse von 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();
})();

Nachrichtenhandler hinzufügen

In Slack gibt es Nachrichtenhandler für Ereignisse mit verschiedenen Untertypen (z. B. ist ein nicht definierter Untertyp eine normale Nachricht, event.subtype == 'file_share' ist eine Dateifreigabenachricht usw.). In Teams gibt es verschiedene Activity Handler für verschiedene Arten von Ereignissen, die über die ActivityTypes Aufzählung aufgelistet werden (z. B app.activity(ActivityTypes.Message). ), wobei einige Activity Typen maßgeschneiderte APIs innerhalb des SDK haben (z. B app.message. ). Diese Konzepte sind ungefähr ähnlich, obwohl sich die Namenskonventionen und die Syntax unterscheiden.

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

Blockkit-Nutzung in adaptive Karten umwandeln

Um die Rich-UI in Nachrichten einzubinden, die von Ihrem Agent gesendet werden, entsprechen die adaptiven Karten von Teams dem Block Kit von 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!',
                },
            },
        ],
    });
});

Implementieren der Benutzerauthentifizierung

Es gibt zwei primäre Arten der Benutzerauthentifizierung für Teams und Slack: Authentifizierung für Slack- & Graph-REST-APIs und Authentifizierung für externe Dienste. Sehen wir uns diese Bereiche der Reihe nach an.

Vom Benutzer delegierte REST-APIs

Wenn Sie in Slack Slack-REST-APIs verwenden möchten, die vom Benutzer delegierte Bereiche erfordern, müssen Sie einen OAuth 2.0-Installationsablauf in Ihrer Anwendung implementieren, um Slack-Benutzertoken abzurufen und zu speichern, auch wenn die App bereits von einem anderen Benutzer installiert wurde. In Teams können Sie Teams SSO nutzen, um Benutzer-Entra-Token zum Aufrufen von Graph-REST-APIs abzurufen. Das Teams SDK ist in Teams SSO und Azure Bot Token Service integriert, um den Tokenerwerb, die Speicherung und die Aktualisierung automatisch für Sie zu übernehmen.

Befolgen Sie zunächst die Anweisungen im Teams SSO-Handbuch. Konfigurieren Sie dann die Authentifizierung in Ihrem 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));
});

Benutzerauthentifizierung für externe Dienste

In Slack können Sie auf externe Dienste zugreifen, indem Sie einen Kontobindungsfluss mit OAuth 2.0 implementieren, wie hier dokumentiert. In Teams können Sie auf externe Dienste zugreifen, indem Sie einen OAuth 2.0-Flow implementieren, wobei der Azure Bot Token Service die Tokenbeschaffung, -speicherung und -aktualisierung für Sie übernimmt.

Richten Sie zunächst Ihre OAuth 2.0-Verbindungseinstellungen im Azure-Portal für Ihre Azure Bot-Ressource ein.

Fügen Sie dann den Authentifizierungscode zu Ihrer Anwendung hinzu, um das entsprechende Benutzertoken abzurufen, und rufen Sie Ihren externen Dienst auf.

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