Teilen über


TeamsFx SDK

TeamsFx hilft ihnen, Ihre Aufgaben zu reduzieren, indem Microsoft Teams das einmalige Anmelden (Single Sign-On, SSO) verwendet und auf Cloudressourcen bis hin zu einzeiligen Anweisungen ohne Konfiguration zugegriffen wird. Sie können das TeamsFx SDK im Browser und in Node.js Umgebungen verwenden. Auf die Kernfunktionen von TeamsFx kann in Client- und Serverumgebungen zugegriffen werden. Sie können Benutzerauthentifizierungscode für Folgendes schreiben:

  • Registerkarte "Teams"
  • Teams-Bot
  • Azure Function

Voraussetzungen

Sie müssen die folgenden Tools installieren und Ihre Entwicklungsumgebung einrichten:

  Installieren Zum Benutzen...
  Visual Studio Code Build-Umgebungen für JavaScript, TypeScript oder SharePoint Framework (SPFx). Verwenden Sie Version 1.55 oder höher.
  Teams Toolkit Eine Microsoft Visual Studio Code-Erweiterung, die ein Projektgerüst für Ihre App erstellt. Verwenden Sie Version 4.0.0.
  Node.js Back-End-JavaScript-Laufzeitumgebung. Weitere Informationen finden Sie unter Node.js Versionskompatibilitätstabelle für den Projekttyp.
  Microsoft Teams Microsoft Teams für die Zusammenarbeit mit allen, mit denen Sie zusammenarbeiten, über Apps für Chats, Besprechungen, Anrufe und alles an einem Ort.
  Microsoft Edge (empfohlen) oder Google Chrome Ein Browser mit Entwicklertools.

Weitere Informationen zu Node.js Versionskompatibilität finden Sie unter Voraussetzungen für die Erstellung Ihrer Teams-App mit Visual Studio Code.

Hinweis

Wenn ihr Projekt verwandte Pakete als Abhängigkeiten installiert botbuilderhat, stellen Sie sicher, dass sie die gleiche Version aufweisen.

Sie müssen über folgende Kenntnisse verfügen:

Erste Schritte

TeamsFx SDK ist im Gerüstprojekt mit TeamsFx Toolkit oder CLI vorkonfiguriert. Weitere Informationen finden Sie unter Teams-App-Projekt.

Tipp

Die Codeausschnitte werden für die neueste TeamsFx SDK-Version 2 aktualisiert.

Installieren Sie das @microsoft/teamsfx Paket

Installieren Sie das TeamsFx SDK für TypeScript oder JavaScript mit npm:

npm install @microsoft/teamsfx

TeamsFx-Kernfunktionen

TeamsFx-Klasse

Die TeamsFx-Klasseninstanz greift standardmäßig über die Umgebungsvariablen auf alle TeamsFx-Einstellungen zu. Sie können benutzerdefinierte Konfigurationswerte festlegen, um die Standardwerte außer Kraft zu setzen. Weitere Informationen finden Sie unter Außerkraftsetzungskonfiguration . Beim Erstellen einer TeamsFx-Instanz müssen Sie den Identitätstyp angeben.

Die folgende Liste enthält die beiden verschiedenen Identitätstypen:

  • Benutzeridentität: Stellt den aktuellen Benutzer von Teams dar.

  • Anwendungsidentität: Stellt die Anwendung selbst dar.

    Hinweis

    Die TeamsFx-Konstruktoren und -Methoden sind für diese beiden Identitätstypen nicht identisch.

Weitere Informationen zur Benutzeridentität und Anwendungsidentität finden Sie im folgenden Abschnitt:

Benutzeridentität
Befehl Beschreibung
new TeamsFx(IdentityType.User) Die Anwendung wird als aktueller Teams-Benutzer authentifiziert.
TeamsFx:setSsoToken() Benutzeridentität in der Node.js-Umgebung (ohne Browser).
TeamsFx:getUserInfo() Um Basisinformationen des Benutzers zu erhalten.
TeamsFx:login() Wird verwendet, damit Benutzer den Zustimmungsprozess durchführen können, wenn Sie SSO verwenden möchten, um Zugriffstoken für bestimmte OAuth-Bereiche zu erhalten.

Hinweis

Sie können im Namen des aktuellen Teams-Benutzers auf Ressourcen zugreifen.

Anwendungsidentität
Befehl Beschreibung
new TeamsFx(IdentityType.App) Die Anwendung wird als Anwendung authentifiziert. Die Berechtigung muss in der Regel vom Administrator genehmigt werden.
TeamsFx:getCredential() Es stellt Anmeldeinformationsinstanzen bereit, die automatisch dem Identitätstyp entsprechen.

Hinweis

Sie benötigen die Zustimmung des Administrators für Ressourcen.

Credential

Anmeldeinformationsklassen implementieren die Schnittstelle, die TokenCredential allgemein in Azure-Bibliotheks-APIs zum Bereitstellen von Zugriffstoken für bestimmte Bereiche verwendet wird. Weitere Informationen zu Klassen im Zusammenhang mit Anmeldeinformationen und Authentifizierungsflüssen finden Sie unter Anmeldeinformationsordner.

Es gibt drei Anmeldeinformationsklassen, um die Authentifizierung zu vereinfachen. Dies sind die entsprechenden Szenarien für jedes Ziel der Anmeldeinformationsklasse:

Benutzeridentität in Browserumgebung

TeamsUserCredential stellt die Identität des aktuellen Benutzers von Teams dar. Wenn die Anmeldeinformationen des Benutzers zum ersten Mal authentifiziert werden, führt Teams SSO den On-Behalf-Of-Flow für den Tokenaustausch durch. Das SDK verwendet diese Anmeldeinformationen, wenn Sie die Benutzeridentität in der Browserumgebung auswählen.

Der folgende Code ist ein Beispiel zum Erstellen TeamsUserCredentialvon :

const authConfig: TeamsUserCredentialAuthConfig = {
  clientId: process.env.REACT_APP_CLIENT_ID,
  initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
};

const credential = new TeamsUserCredential(authConfig);

Erforderliche Konfigurationen sind initiateLoginEndpoint und clientId befinden sich im Typ TeamsUserCredentialAuthConfig.

Benutzeridentität in Node.js Umgebung

OnBehalfOfUserCredential verwendet den On-Behalf-Of-Flow und erfordert teams-SSO-Token in Azure-Funktions- oder Botszenarien. Das TeamsFx SDK verwendet die folgenden Anmeldeinformationen, wenn Sie die Benutzeridentität in Node.js Umgebung auswählen.

Der folgende Code ist ein Beispiel zum Erstellen OnBehalfOfUserCredentialvon :

const oboAuthConfig: OnBehalfOfCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};

const oboCredential = new OnBehalfOfUserCredential(ssoToken, oboAuthConfig);

Erforderliche Konfigurationen sind authorityHost, tenantId, clientId, clientSecretoder certificateContent , die sich im Typ OnBehalfOfCredentialAuthConfigbefinden.

App-Identität in Node.js Umgebung

AppCredential stellt die App-Identität dar. Sie können die App-Identität verwenden, wenn der Benutzer nicht an einem zeitgesteuerten Automatisierungsauftrag beteiligt ist. Das TeamsFx SDK verwendet die folgenden Anmeldeinformationen, wenn Sie die App-Identität in Node.js Umgebung auswählen.

Der folgende Code ist ein Beispiel zum Erstellen AppCredentialvon :

const appAuthConfig: AppCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};
const appCredential = new AppCredential(appAuthConfig);

Erforderliche Konfigurationen sind authorityHost, tenantId, clientId, clientSecretoder certificateContent innerhalb des Typs AppCredentialAuthConfig

Bot-SSO

Bot-bezogene Klassen werden im bot-Ordner gespeichert.

TeamsBotSsoPrompt kann in das Bot-Framework integriert werden. Es vereinfacht den Authentifizierungsprozess, wenn Sie eine Botanwendung entwickeln und das einmalige Anmelden des Bots verwenden möchten.

Der folgende Code ist ein Beispiel zum Erstellen TeamsBotSsoPromptvon :

const TeamsBotSsoPromptId = "TEAMS_BOT_SSO_PROMPT";

const settings: TeamsBotSsoPromptSettings = {
  scopes: ["User.Read"],
  timeout: 900000,
  endOnInvalidMessage: true,
};

const authConfig: OnBehalfOfCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};
const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
const ssoPrompt = new TeamsBotSsoPrompt(authConfig, loginUrl, TeamsBotSsoPromptId, settings);

Unterstützte Funktionen

TeamsFx SDK bietet mehrere Funktionen, um die Konfiguration für Bibliotheken von Drittanbietern zu vereinfachen. Sie befinden sich unter dem Kernordner.

  • Microsoft Graph-Dienst:createMicrosoftGraphClientcreateMicrosoftGraphClientWithCredential und MsGraphAuthProvider hilft beim Erstellen einer authentifizierten Graph-Instanz.

    Hinweis

    createMicrosoftGraphClient -Funktion ist veraltet. Es wird empfohlen, stattdessen zu verwenden createMicrosoftGraphClientWithCredential , um die Codierung zu verbessern.

  • SQL: Gibt getTediousConnectionConfig eine mühsame Verbindungskonfiguration zurück.

    Erforderliche Konfiguration:

    • Wenn Sie die Benutzeridentität verwenden möchten, sqlServerEndpointsind , sqlUsernameund sqlPassword erforderlich.
    • Wenn Sie die MSI-Identität verwenden möchten, sqlServerEndpointsind und sqlIdentityId erforderlich.

    Hinweis

    Die getTediousConnectionConfig Funktion ist veraltet. Es wird empfohlen, dass Sie Ihre eigene Tedious-Konfiguration erstellen, um eine bessere Flexibilität zu erzielen.

Überschreiben der Konfiguration für die TeamsFx-Klasse

Hinweis

Die TeamsFx-Klasse ist veraltet. Verwenden Sie TeamsUserCredentialstattdessen , OnBehalfOfUserCredentialund AppCredential .

Sie können beim Erstellen einer neuen TeamsFx Instanz eine benutzerdefinierte Konfiguration übergeben, um die Standardkonfiguration zu überschreiben oder erforderliche Felder festzulegen, wenn environment variables sie fehlen.

Für Registerkartenprojekt

Wenn Sie ein Registerkartenprojekt mit dem Microsoft Visual Studio Code Toolkit erstellt haben, werden die folgenden Konfigurationswerte aus vorkonfigurierten Umgebungsvariablen verwendet:

  • authorityHost (REACT_APP_AUTHORITY_HOST)
  • tenantId (REACT_APP_TENANT_ID)
  • clientId (REACT_APP_CLIENT_ID)
  • initiateLoginEndpoint (REACT_APP_START_LOGIN_PAGE_URL)
  • applicationIdUri (REACT_APP_START_LOGIN_PAGE_URL)
  • apiEndpoint (REACT_APP_FUNC_ENDPOINT) // wird nur verwendet, wenn eine Back-End-Funktion vorhanden ist
  • apiName (REACT_APP_FUNC_NAME) // wird nur verwendet, wenn eine Back-End-Funktion vorhanden ist
Für Ein Azure-Funktions- oder Botprojekt

Wenn Sie ein Azure-Funktions- oder Botprojekt mit dem Visual Studio Code Toolkit erstellt haben, werden die folgenden Konfigurationswerte aus vorkonfigurierten Umgebungsvariablen verwendet:

  • initiateLoginEndpoint (INITIATE_LOGIN_ENDPOINT)

  • authorityHost (M365_AUTHORITY_HOST)

  • tenantId (M365_TENANT_ID)

  • clientId (M365_CLIENT_ID)

  • clientSecret (M365_CLIENT_SECRET)

  • applicationIdUri (M365_APPLICATION_ID_URI)

  • apiEndpoint (API_ENDPOINT)

  • sqlServerEndpoint (SQL_ENDPOINT) // wird nur verwendet, wenn eine SQL-Instanz vorhanden ist

  • sqlUsername (SQL_USER_NAME) // wird nur verwendet, wenn eine SQL-Instanz vorhanden ist

  • sqlPassword (SQL_PASSWORD) // wird nur verwendet, wenn eine SQL-Instanz vorhanden ist

  • sqlDatabaseName (SQL_DATABASE_NAME) // wird nur verwendet, wenn eine SQL-Instanz vorhanden ist

  • sqlIdentityId (IDENTITY_ID) // wird nur verwendet, wenn eine SQL-Instanz vorhanden ist

Fehlerbehandlung

Der grundlegende Typ der API-Fehlerantwort ist ErrorWithCode, der Fehlercode und Fehlermeldung enthält. Um beispielsweise bestimmte Fehler herauszufiltern, können Sie das folgende Snippet verwenden:

try {
  const teamsfx = new TeamsFx();
  await teamsfx.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

Hinweis

Die TeamsFx-Klasse ist veraltet und ErrorWithCode wird nicht empfohlen. Sie können stattdessen verwenden TeamsUserCredential .

try {
  const authConfig: TeamsUserCredentialAuthConfig = {
    clientId: process.env.REACT_APP_CLIENT_ID,
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
  };

  const credential = new TeamsUserCredential(authConfig);  
  await credential.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

Wenn eine Anmeldeinformationsinstanz in einer anderen Bibliothek wie Microsoft Graph verwendet wird, ist es möglich, dass ein Fehler abgefangen und transformiert wird.

Microsoft Graph-Szenarien

Dieser Abschnitt enthält mehrere Codeausschnitte für gängige Szenarien im Zusammenhang mit Microsoft Graph. In solchen Szenarien können Benutzer APIs mit unterschiedlichen Berechtigungen im Front-End oder Back-End aufrufen.

  • Benutzerdelegatberechtigung im Front-End (Verwenden )TeamsUserCredential

    Verwenden der Graph-API in der Registerkarten-App

    Dieser Codeausschnitt zeigt, wie TeamsUserCredential Sie und createMicrosoftGraphClientWithCredential verwenden, um Benutzerprofile aus Microsoft Graph in der Registerkarten-App abzurufen. Außerdem wird gezeigt, wie Sie eine GraphErrorabfangen und auflösen.

    1. Importieren Sie die erforderlichen Klassen.

      import {
       createMicrosoftGraphClientWithCredential,
       TeamsUserCredential,
      } from "@microsoft/teamsfx";
      
    2. Erstellen einer TeamsUserCredential Instanz.

      const authConfig: TeamsUserCredentialAuthConfig = {
      clientId: process.env.REACT_APP_CLIENT_ID!,
      initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL!,
      };
      
      const teamsUserCredential = new TeamsUserCredential(authConfig);
      
    3. Verwenden Sie teamsUserCredential.login() , um die Benutzerzustimmung einzuholen.

      // Put these code in a call-to-action callback function to avoid browser blocking automatically showing up pop-ups.
      await teamsUserCredential.login(["User.Read"]); // Login with scope
      
    4. Sie können eine TeamsFx-Instanz und einen Graphclient initialisieren und von diesem Client Informationen von Microsoft Graph abrufen.

      try {
       const graphClient = createMicrosoftGraphClientWithCredential(teamsUserCredential, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
       const profile = await graphClient.api("/me").get();
      } catch (err: unknown) {
       // ErrorWithCode is handled by Graph client
       if (err instanceof GraphError && err.code?.includes(ErrorCode.UiRequiredError)) {
         // Need to show login button to ask for user consent.
       }
      }
      

    Weitere Informationen zum Beispiel für die Verwendung der Graph-API in der Registerkarten-App finden Sie unter Beispiel für Graph Conector-App.

    Integration in das Microsoft Graph-Toolkit

    Die Microsoft Graph-Toolkit-Bibliothek ist eine Sammlung verschiedener Authentifizierungsanbieter und Benutzeroberflächenkomponenten, die von Microsoft Graph unterstützt werden.

    Das @microsoft/mgt-teamsfx-provider Paket macht die Klasse verfügbar, die die TeamsFxProvider -Klasse verwendet TeamsFx , um Benutzer anzumelden und Token für die Verwendung mit Microsoft Graph abzurufen.

    1. Sie können die folgenden erforderlichen Pakete installieren:

         npm install @microsoft/mgt-element @microsoft/mgt-teamsfx-provider @microsoft/teamsfx
      
    2. Initialisieren Sie den Anbieter in Ihrer Komponente.

      // Import the providers and credential at the top of the page
      import {Providers} from '@microsoft/mgt-element';
      import {TeamsFxProvider} from '@microsoft/mgt-teamsfx-provider';
      import {TeamsUserCredential} from "@microsoft/teamsfx";
      
      const scope = ["User.Read"];
      const teamsfx = new TeamsFx();
      const provider = new TeamsFxProvider(teamsfx, scope);
      Providers.globalProvider = provider;   
      
    3. Sie können die -Methode verwenden, um das teamsfx.login(scopes) erforderliche Zugriffstoken abzurufen.

      // Put these code in a call-to-action callback function to avoid browser blocking automatically showing up pop-ups. 
      await teamsfx.login(this.scope);
      Providers.globalProvider.setState(ProviderState.SignedIn);
      
    4. Sie können eine beliebige Komponente auf Ihrer HTML-Seite oder in Ihrer render() Methode mit React hinzufügen, um den Kontext für den TeamsFx Zugriff auf Microsoft Graph zu verwenden.

      <mgt-person query="me" view="threeLines"></mgt-person>
      
      public render(): void {
      return (
       <div>
           <Person personQuery="me" view={PersonViewType.threelines}></Person>
       </div>
      );
      }    
      

    Weitere Informationen zum Beispiel zum Initialisieren des TeamsFx-Anbieters finden Sie im Beispiel für den Kontaktexport.

  • Benutzerdelegatberechtigung im Back-End (Verwenden )OnBehalfOfUserCredential

    Verwenden der Graph-API in einer Botanwendung

    Dieser Codeausschnitt zeigt, wie Sie verwenden TeamsBotSsoPrompt , um ein Dialogfeld festzulegen und sich dann anzumelden, um ein Zugriffstoken abzurufen.

    1. Initialisieren sie, und fügen Sie es dem Dialogsatz hinzu TeamsBotSsoPrompt .

      const { ConversationState, MemoryStorage } = require("botbuilder");
      const { DialogSet, WaterfallDialog } = require("botbuilder-dialogs");
      const { TeamsBotSsoPrompt, OnBehalfOfCredentialAuthConfig, TeamsBotSsoPromptSettings } = require("@microsoft/teamsfx");
      
      const convoState = new ConversationState(new MemoryStorage());
      const dialogState = convoState.createProperty("dialogState");
      const dialogs = new DialogSet(dialogState);
      
      const TeamsBotSsoPromptId = "TEAMS_BOT_SSO_PROMPT";
      
      const settings: TeamsBotSsoPromptSettings = {
      scopes: ["User.Read"],
      timeout: 900000,
      endOnInvalidMessage: true,
      };
      
      const authConfig: OnBehalfOfCredentialAuthConfig = {
       authorityHost: process.env.M365_AUTHORITY_HOST,
       clientId: process.env.M365_CLIENT_ID,
       tenantId: process.env.M365_TENANT_ID,
       clientSecret: process.env.M365_CLIENT_SECRET,
      };
      const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
      const ssoPrompt = new TeamsBotSsoPrompt(authConfig, loginUrl, TeamsBotSsoPromptId, settings);
      
      dialogs.add(ssoPrompt);    
      
    2. Starten Sie das Dialogfeld, und melden Sie sich an.

      dialogs.add(
        new WaterfallDialog("taskNeedingLogin", [
         async (step) => {
           return await step.beginDialog("TeamsBotSsoPrompt");
         },
         async (step) => {
          const token = step.result;
          if (token) {
            // ... continue with task needing access token ...
          } else {
           await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
           return await step.endDialog();
          }
        },
       ])
      );    
      

    Weitere Informationen zum Beispiel für die Verwendung der Graph-API in bot-Anwendungen finden Sie unter bot-sso-Beispiel.

    Verwenden der Graph-API in der Nachrichtenerweiterung

    Der folgende Codeausschnitt zeigt, wie Sie außer Kraft setzen handleTeamsMessagingExtensionQuery , die von TeamsActivityHandleraus erweitert wird, und wie Sie vom TeamsFx SDK bereitgestellt werden, handleMessageExtensionQueryWithSSO um sich anzumelden, um ein Zugriffstoken abzurufen:

    
     const authConfig: OnBehalfOfCredentialAuthConfig = {
      authorityHost: process.env.M365_AUTHORITY_HOST,
      clientId: process.env.M365_CLIENT_ID,
      tenantId: process.env.M365_TENANT_ID,
      clientSecret: process.env.M365_CLIENT_SECRET,
     };
     const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
     public async handleTeamsMessagingExtensionQuery(context: TurnContext, query: any): Promise<any> {
      return await handleMessageExtensionQueryWithSSO(context, authConfig, loginUrl, 'User.Read', 
        async (token: MessageExtensionTokenResponse) => {
          // ... continue to query with access token ...
        });
     }    
    

    Weitere Informationen zum Beispiel für die Verwendung der Graph-API in der Nachrichtenerweiterung finden Sie unter message-extension-sso-sample.

    Verwenden der Graph-API im Befehlsbot

    Dieser Codeausschnitt zeigt, wie TeamsFxBotSsoCommandHandler Sie für den Befehlsbot implementieren, um die Microsoft-API aufzurufen.

     import { Activity, TurnContext } from "botbuilder";
     import {
      CommandMessage,
      TriggerPatterns,
      createMicrosoftGraphClientWithCredential,
      TeamsFxBotSsoCommandHandler,
      TeamsBotSsoPromptTokenResponse,
     } from "@microsoft/teamsfx";
    
     const authConfig: OnBehalfOfCredentialAuthConfig = {
      authorityHost: process.env.M365_AUTHORITY_HOST,
      clientId: process.env.M365_CLIENT_ID,
      tenantId: process.env.M365_TENANT_ID,
      clientSecret: process.env.M365_CLIENT_SECRET,
     };
     const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
    
     export class ProfileSsoCommandHandler implements TeamsFxBotSsoCommandHandler {
      triggerPatterns: TriggerPatterns = "profile";
    
      async handleCommandReceived(
        context: TurnContext,
        message: CommandMessage,
        tokenResponse: TeamsBotSsoPromptTokenResponse,
      ): Promise<string | Partial<Activity> | void> {
    
        const oboCredential = new OnBehalfOfUserCredential(tokenResponse.ssoToken, oboAuthConfig);
    
        // Add scope for your Azure AD app. For example: Mail.Read, etc.
        const graphClient = createMicrosoftGraphClientWithCredential(oboCredential, ["User.Read"]);
    
        // Call graph api use `graph` instance to get user profile information
        const me = await graphClient.api("/me").get();
    
        if (me) {
          // Bot will send the user profile info to user
          return `Your command is '${message.text}' and you're logged in as ${me.displayName}`;
        } else {
          return "Could not retrieve profile information from Microsoft Graph.";
        }
      }
     }    
    
    

    Weitere Informationen zum Implementieren des SSO-Befehlshandlers im Befehlsbot finden Sie unter Hinzufügen des einmaligen Anmeldens zur Teams-App. Außerdem gibt es ein Beispielprojekt command-bot-with-sso , in dem Sie den SSO-Befehlsbot ausprobieren können.

    Aufrufen der Azure-Funktion in der Registerkarten-App: On-Behalf-Of-Flow

    In diesem Codeausschnitt wird gezeigt, wie Sie die Azure-Funktion oder axios -Bibliothek verwenden CreateApiClient und wie Sie die Graph-API in Azure Function aufrufen, um Benutzerprofile abzurufen.

    1. Sie können das CreateApiClient vom TeamsFx SDK bereitgestellte verwenden, um Azure Function aufzurufen:

      async function callFunction() {
        const authConfig: TeamsUserCredentialAuthConfig = {
       clientId: process.env.REACT_APP_CLIENT_ID,
       initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
        };
       const teamsUserCredential = new TeamsUserCredential(authConfig);
       // Create an API client by providing the token and endpoint.
       const apiClient = CreateApiClient(
         "https://YOUR_API_ENDPOINT", // Create an API Client that uses SSO token to authenticate requests
         new BearerTokenAuthProvider(async () =>  (await teamsUserCredential.getToken(""))!.token) // Call API hosted in Azure Functions on behalf of user to inject token to request header
       );
       // Send a GET request to "RELATIVE_API_PATH", "/api/functionName" for example.
        const response = await apiClient.get("RELATIVE_API_PATH");
        return response.data;
      }    
      

      Sie können die Bibliothek auch zum Aufrufen der Azure-Funktion verwenden axios .

      async function callFunction() {
        const authConfig: TeamsUserCredentialAuthConfig = {
          clientId: process.env.REACT_APP_CLIENT_ID,
          initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
        };
        const teamsUserCredential = new TeamsUserCredential(authConfig);
        const accessToken = await teamsUserCredential.getToken(""); // Get SSO token 
        const endpoint = "https://YOUR_API_ENDPOINT";
        const response = await axios.default.get(endpoint + "/api/" + functionName, {
          headers: {
            authorization: "Bearer " + accessToken.token,
          },
        });
        return response.data;
      }    
      
      
    2. Rufen Sie als Antwort die Graph-API in Azure Function im Namen des Benutzers auf.

      
      export default async function run(
      context: Context,
      req: HttpRequest,
      teamsfxContext: TeamsfxContext
      ): Promise<Response> {
       const res: Response = { status: 200, body: {},};
      
       const authConfig: OnBehalfOfCredentialAuthConfig = {
         authorityHost: process.env.M365_AUTHORITY_HOST,
         clientId: process.env.M365_CLIENT_ID,
         tenantId: process.env.M365_TENANT_ID,
         clientSecret: process.env.M365_CLIENT_SECRET,
       };
       const oboCredential = new OnBehalfOfUserCredential(tokenResponse.ssoToken, oboAuthConfig);
      
       // Query user's information from the access token.
       try {
        const currentUser: UserInfo = await oboCredential.getUserInfo();
        if (currentUser && currentUser.displayName) {
          res.body.userInfoMessage = `User display name is ${currentUser.displayName}.`;
        } else {
          res.body.userInfoMessage = "No user information was found in access token.";
        }
       } catch (e) {
       }
       // Create a graph client to access user's Microsoft 365 data after user has consented.
       try {
        const graphClient: Client = createMicrosoftGraphClientWithCredential(oboCredential, [".default"]);
        const profile: any = await graphClient.api("/me").get();
        res.body.graphClientMessage = profile;
       } catch (e) {
       }
       return res;
       }
      
      

    Weitere Informationen zum Beispiel für die Verwendung der Graph-API in einer Botanwendung finden Sie unter hello-world-tab-with-backend sample.

  • Anwendungsberechtigung im Back-End

    Verwenden der zertifikatbasierten Authentifizierung in Azure Function

    Dieser Codeausschnitt zeigt, wie Sie die zertifikatbasierte Anwendungsberechtigung verwenden, um das Token abzurufen, das zum Aufrufen der Graph-API verwendet werden kann.

    1. Sie können die appAuthConfig initialisieren, indem Sie eine PEM-encoded key certificateangeben.

       const appAuthConfig: AppCredentialAuthConfig = {
         authorityHost: process.env.M365_AUTHORITY_HOST,
         clientId: process.env.M365_CLIENT_ID,
         tenantId: process.env.M365_TENANT_ID,
         certificateContent: 'PEM-encoded key certificate',
        };
      
      
    2. Sie können verwenden AppCredential , um das Token abzurufen.

      const appCredential = new AppCredential(appAuthConfig);
      const token = appCredential.getToken();    
      
    Verwenden der Authentifizierung mit geheimen Clientschlüsseln in Azure Function

    In diesem Codeausschnitt wird gezeigt, wie Sie die Anwendungsberechtigung für geheime Clientschlüssel verwenden, um das Token abzurufen, das zum Aufrufen der Graph-API verwendet wird.

    1. Sie können die authConfig initialisieren, indem Sie eine client secretangeben.

      const appAuthConfig: AppCredentialAuthConfig = {
       authorityHost: process.env.M365_AUTHORITY_HOST,
       clientId: process.env.M365_CLIENT_ID,
       tenantId: process.env.M365_TENANT_ID,
       clientSecret: process.env.M365_CLIENT_SECRET,
      };
      
    2. Sie können verwenden authConfig , um das Token abzurufen.

      const appCredential = new AppCredential(appAuthConfig);
      const token = appCredential.getToken();    
      

    Weitere Informationen zum Beispiel für die Verwendung der Graph-API in einer Botanwendung finden Sie im Beispiel hello-world-tab-with-backend.

Sonstige Szenarien

Dieser Abschnitt enthält mehrere Codeausschnitte für andere Szenarien, die sich auf Microsoft Graph beziehen. Sie können einen API-Client in Bot oder Azure Function erstellen und auf die SQL-Datenbank in Azure Function zugreifen.

Erstellen eines API-Clients zum Aufrufen einer vorhandenen API in Bot oder Azure Function

Dieser Codeausschnitt zeigt, wie Sie eine vorhandene API im Bot durch ApiKeyProvideraufrufen.

// Create an API Key auth provider. In addition to APiKeyProvider, following auth providers are also available:
// BearerTokenAuthProvider, BasicAuthProvider, CertificateAuthProvider.
const authProvider = new ApiKeyProvider("YOUR_API_KEY_NAME",
  "YOUR_API_KEY_VALUE",
  ApiKeyLocation.Header
);

// Create an API client using above auth provider.
// You can also implement AuthProvider interface and use it here.
const apiClient = createApiClient(
  "YOUR_API_ENDPOINT",
  authProvider
);

// Send a GET request to "RELATIVE_API_PATH", "/api/apiname" for example.
const response = await apiClient.get("RELATIVE_API_PATH");  
Zugreifen auf SQL-Datenbank in Azure Function

Verwenden Sie tedious die Bibliothek, um auf SQL zuzugreifen und die Authentifizierung zu verwalten DefaultTediousConnectionConfiguration . Sie können auch die Verbindungskonfiguration anderer SQL-Bibliotheken basierend auf dem Ergebnis von sqlConnectionConfig.getConfig()erstellen.

  1. Legen Sie die Verbindungskonfiguration fest.

    // Equivalent to:
    // const sqlConnectConfig = new DefaultTediousConnectionConfiguration({
    //    sqlServerEndpoint: process.env.SQL_ENDPOINT,
    //    sqlUsername: process.env.SQL_USER_NAME,
    //    sqlPassword: process.env.SQL_PASSWORD,
    // });
    const teamsfx = new TeamsFx();
    // If there's only one SQL database
    const config = await getTediousConnectionConfig(teamsfx);
    // If there are multiple SQL databases
    const config2 = await getTediousConnectionConfig(teamsfx, "your database name");  
    
  2. Stellen Sie eine Verbindung mit Ihrer Datenbank her.

    const connection = new Connection(config);
    connection.on("connect", (error) => {
    if (error) {
     console.log(error);
     }
    });  
    

    Hinweis

    Die getTediousConnectionConfig Funktion ist veraltet, es wird empfohlen, dass Sie Ihre eigene mühsame Konfiguration für eine bessere Flexibilität zusammenstellen.

Weitere Informationen zum Beispiel für den Zugriff auf SQL-Datenbank in Azure Function finden Sie unter share-now-Beispiel.

Erweiterte Anpassung

Protokoll konfigurieren

Sie können die Kundenprotokollebene festlegen und Ausgaben umleiten, wenn Sie diese Bibliothek verwenden.

Hinweis

Protokolle sind standardmäßig deaktiviert. Sie können sie aktivieren, indem Sie die Protokollebene festlegen.

Aktivieren Sie das Protokoll, indem Sie die Protokollebene festlegen

Wenn Sie den Protokolliergrad festlegen, wird die Protokollierung aktiviert. Standardmäßig werden Protokollinformationen in der Konsole ausgegeben.

Legen Sie die Protokollebene mit dem folgenden Snippet fest:

// Only need the warning and error messages.
setLogLevel(LogLevel.Warn);

Hinweis

Sie können die Protokollausgabe umleiten, indem Sie einen benutzerdefinierten Logger oder eine Protokollfunktion einstellen.

Umleitung durch Einstellen eines benutzerdefinierten Loggers

setLogLevel(LogLevel.Info);
// Set another logger if you want to redirect to Application Insights in Azure Function
setLogger(context.log);

Umleitung durch Einstellen der benutzerdefinierten Protokollfunktion

setLogLevel(LogLevel.Info);
// Only log error message to Application Insights in bot application.
setLogFunction((level: LogLevel, message: string) => {
  if (level === LogLevel.Error) {
    this.telemetryClient.trackTrace({
      message: message,
      severityLevel: Severity.Error,
    });
  }
});

Hinweis

Protokollfunktionen werden nicht wirksam, wenn Sie eine benutzerdefinierte Protokollierung festlegen.

Upgrade auf die neueste SDK-Version

Wenn Sie die SDK-Version verwenden, die enthält loadConfiguration(), können Sie die folgenden Schritte ausführen, um auf die neueste SDK-Version zu aktualisieren:

  1. Anstatt aufzurufen loadConfiguration(), verwenden Sie die spezifischen Authentifizierungskonfigurationsklassen, um die Einstellungen für jeden Anmeldeinformationstyp anzupassen. Verwenden Sie AppCredentialAuthConfig beispielsweise für AppCredential, OnBehalfOfUserCredentialAuthConfig für OnBehalfOfUserCredentialund TeamsUserCredentialAuthConfig für TeamsUserCredential.
  2. Ersetzen Sie new TeamsUserCredential() durch new TeamsUserCredential(authConfig).
  3. Ersetzen Sie new M365TenantCredential() durch new AppCredential(authConfig).
  4. Ersetzen Sie new OnBehalfOfUserCredential(ssoToken) durch new OnBehalfOfUserCredential(authConfig).

Siehe auch