TeamsFx SDK

Wichtig

Das TeamsFx SDK wird von Microsoft nicht mehr zum Erstellen von Microsoft 365 Copilot-Erweiterungen, Microsoft 365-Agents oder modernen Teams-App-Szenarien unterstützt. Das SDK befindet sich derzeit im Veraltet-Modus und erhält bis September 2026 Support nur von der Community auf GitHub.

Verwenden Sie für alle neuen, von Microsoft unterstützten Entwicklungen (Copilot-Erweiterungen, KI-Agents, Teams-Apps oder Microsoft 365-Erweiterbarkeit) Folgendes:

• Microsoft 365 Agents SDK (empfohlen für alle neuen Copilot- oder Agent-basierten Erfahrungen)
• Teams SDK (zum Erstellen von Apps und Bots, die nur für Teams bestimmt sind)

Neue Projekte sollten nicht mit TeamsFx erstellt werden. Bestehende TeamsFx-Lösungen sollten auf das Microsoft 365 Agents SDK migriert werden.

TeamsFx reduziert Ihre Aufgaben durch die Verwendung von Microsoft Teams Single Sign-On (SSO) und den Zugriff auf Cloud-Ressourcen mit einzeiligen Anweisungen und ohne Konfiguration. Sie können TeamsFx SDK sowohl im Browser als auch in Node.js Umgebungen verwenden. TeamsFx-Kernfunktionen sind in Client- und Serverumgebungen zugänglich. Sie können Benutzerauthentifizierungscode schreiben für:

• Registerkarte "Teams"
• Teams-Bot
• Azure-Funktion

Voraussetzungen

Installieren Sie die folgenden Tools, und richten Sie Ihre Entwicklungsumgebung ein:

	Installieren	Zur Verwendung...
	Visual Studio Code	JavaScript, TypeScript oder SharePoint-Framework (SPFx)-Buildumgebungen. Verwenden Sie Version 1.55 oder höher.
	Microsoft 365 Agents Toolkit (früher als Teams Toolkit bezeichnet)	Eine Microsoft Visual Studio Code-Erweiterung, die ein Projektgerüst für Ihre App erstellt. Verwenden Sie Version 4.0.0.
	Node.js	JavaScript-Laufzeitumgebung für das Back-End. Weitere Informationen finden Sie in Node.js Versionskompatibilitätstabelle für den Projekttyp.
	Microsoft Teams	Microsoft Teams für die Zusammenarbeit mit allen Personen, mit denen Sie arbeiten, über Apps für Chat, Besprechungen, Anrufe und alles an einem Ort.
	Microsoft Edge (empfohlen) oder Google Chrome	Ein Browser mit Entwicklertools.

Weitere Informationen zur 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 botbuilder hat, stellen Sie sicher, dass sie die gleiche Version haben.

Sie müssen über praktische Kenntnisse in folgenden Bereichen verfügen:

• Quellcode
• Paket (NPM)
• API-Referenzdokumentation
• Beispiele

Erste Schritte

Das TeamsFx SDK ist im Gerüstprojekt mithilfe der Microsoft 365 Agents Toolkit CLI (früher als TeamsFx Toolkit oder CLI bezeichnet) vorkonfiguriert. Weitere Informationen finden Sie unter Teams-App-Projekt.

Tipp

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

Paket installieren

"Install from" (Installieren @microsoft/m365agentstoolkit-cli ) npm und "Ausführen atk -h ", um alle verfügbaren Befehle zu überprüfen:

npm install -g @microsoft/m365agentstoolkit-cli
atk -h

TeamsFx-Kernfunktionalitäten

TeamsFx-Klasse

Die TeamsFx-Klassen-instance greift standardmäßig über die Umgebungsvariablen auf alle TeamsFx-Einstellungen zu. Sie können benutzerdefinierte Konfigurationswerte festlegen, um die Standardwerte zu überschreiben. Weitere Informationen finden Sie unter Außerkraftsetzungskonfiguration für Details. Wenn Sie eine TeamsFx-Instance erstellen, müssen Sie den Identitätstyp angeben.

Die folgende Liste enthält die zwei verschiedenen Arten von Identitäten:

• 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 Node.js Umgebung (ohne Browser).
TeamsFx:getUserInfo()	Um die grundlegenden Informationen des Benutzers abzurufen.
TeamsFx:login()	Es wird verwendet, damit Benutzer den Zustimmungsprozess durchführen können, wenn Sie SSO verwenden möchten, um Zugriffstoken für bestimmte OAuth-Bereiche abzurufen.

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 authentifziert. Die Berechtigung muss in der Regel vom Administrator genehmigt werden.
TeamsFx:getCredential()	Er stellt Anmeldeinformationsinstanzen bereit, die automatisch dem Identitätstyp entsprechen.

Hinweis

Für Ressourcen benötigen Sie Administratorzustimmung.

Anmeldeinformationen

Anmeldeinformationsklassen implementieren die Schnittstelle, die TokenCredential häufig in Azure-Bibliotheks-APIs verwendet wird, um Zugriffstoken für bestimmte Bereiche bereitzustellen. Weitere Informationen zu Klassen im Zusammenhang mit Anmeldeinformationen und Authentifizierungsflüssen finden Sie im Ordner für Anmeldeinformationen.

Zur Vereinfachung der Authentifizierung gibt es drei Klassen von Anmeldeinformationen. Im Folgenden finden Sie die entsprechenden Szenarien für jedes Qualifikationsklassenziel:

Benutzeridentität in Browserumgebung

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

Der folgende Code ist ein Beispiel für die Erstellung TeamsUserCredential:

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 das befindet sich im Typ TeamsUserCredentialAuthConfig.

Benutzeridentität in Node.js Umgebung

OnBehalfOfUserCredentialverwendet On-Behalf-Of-Flow und erfordert Teams SSO-Token in Azure-Funktion oder Bot-Szenarien. Das TeamsFx SDK verwendet die folgenden Anmeldeinformationen, wenn Sie die Benutzeridentität in Node.js Umgebung auswählen.

Der folgende Code ist ein Beispiel für die Erstellung OnBehalfOfUserCredential:

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

Required configurations are authorityHost, tenantId, clientIdclientSecret, or certificateContent that is found inside type OnBehalfOfCredentialAuthConfig.

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 beteiligt ist, z. B. an einem zeitgesteuerten Automatisierungsauftrag. 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 für die Erstellung AppCredential:

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, clientIdclientSecret, oder certificateContent der Typ "Das ist im Inneren"AppCredentialAuthConfig

Bot-SSO

Bot-bezogene Klassen werden im Bot-Ordner gespeichert.

TeamsBotSsoPrompt Integration in das Botframework. Es vereinfacht den Authentifizierungsprozess, wenn Sie eine Bot-Anwendung entwickeln und das Bot-SSO verwenden möchten.

Der folgende Code ist ein Beispiel für die Erstellung TeamsBotSsoPrompt:

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 zur Vereinfachung der Konfiguration für Bibliotheken von Drittanbietern. Sie befinden sich im Kernordner.

• Microsoft Graph Service: createMicrosoftGraphClient, createMicrosoftGraphClientWithCredentialund MsGraphAuthProvider Hilfe beim Erstellen einer authentifizierten Graph-instance.

Hinweis

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

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

  Erforderliche Konfiguration:

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

Hinweis

Die getTediousConnectionConfig Funktion ist veraltet. Es wird empfohlen, dass Sie Ihre eigene Mühsame Konfiguration erstellen, um mehr Flexibilität zu erzielen.

Außerkraftsetzung der Konfiguration für TeamsFx-Klasse

Hinweis

Die TeamsFx-Klasse ist veraltet. Verwenden Sie , OnBehalfOfUserCredential, und AppCredential stattdessen .TeamsUserCredential

Sie können beim Erstellen einer neuen TeamsFx Instance eine benutzerdefinierte Konfiguration übergeben, um die Standardkonfiguration außer Kraft zu setzen oder erforderliche Felder festzulegen, wenn environment variables diese fehlen.

Für Registerkarte Projekt

Wenn Sie das Registerkartenprojekt mit 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 Azure-Funktion oder Bot-Projekt

Wenn Sie eine Azure-Funktion oder ein Bot-Projekt mit 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-instance vorhanden ist

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

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

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

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

Fehlerbehandlung

Der grundlegende Typ der API-Fehlerantwort ist ErrorWithCode, der Fehlercode und Fehlermeldung enthält. Um beispielsweise einen bestimmten Fehler herauszufiltern, können Sie den folgenden Codeausschnitt verwenden:

try {
  const atk = 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 Credential-Instance in einer anderen Bibliothek, z. B. 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 häufige Szenarien im Zusammenhang mit Microsoft Graph. In solchen Szenarien kann der Benutzer APIs mit unterschiedlichen Berechtigungen im Front-End oder Backend aufrufen.

• Benutzer-Stellvertretungsberechtigung im Frontend (Verwenden TeamsUserCredential)

  Verwenden der Graph-API in der Registerkarten-App

  Dieser Codeausschnitt zeigt Ihnen, wie Sie Benutzerprofile von Microsoft Graph in der Registerkarten-App verwenden TeamsUserCredential und createMicrosoftGraphClientWithCredential abrufen. Außerdem wird gezeigt, wie Sie einen .GraphError

  1. Importieren Sie die benötigten Klassen.

     import {
      createMicrosoftGraphClientWithCredential,
      TeamsUserCredential,
     } from "@microsoft/teamsfx";
     

  2. instance erstellen TeamsUserCredential .

     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 diese Methode teamsUserCredential.login() , um die Zustimmung des Benutzers 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-Instance und einen Graph-Client initialisieren und Informationen von Microsoft Graph über diesen Client 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 im Beispiel für die Graph Conector App.

  Integration mit dem 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 TeamsFxProvider die Klasse zum Anmelden von Benutzern und zum Abrufen von Token zur Verwendung mit Microsoft Graph verwendet TeamsFx .

  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 innerhalb 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 atk = new TeamsFx();
     const provider = new TeamsFxProvider(teamsfx, scope);
     Providers.globalProvider = provider;   
     

  3. Sie können die teamsfx.login(scopes) Methode verwenden, um das 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 in Ihre HTML-Seite oder in Ihre render() Methode mit React einfügen, um den TeamsFx Kontext für den 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 zur Initialisierung des TeamsFx-Anbieters finden Sie im Beispiel für den Export von Kontakten.

• Benutzer-Stellvertretungsberechtigung im Backend (Verwenden OnBehalfOfUserCredential)

  Verwenden der Graph-API in der Bot-Anwendung

  Dieser Codeausschnitt zeigt Ihnen, wie TeamsBotSsoPrompt Sie ein Dialogfeld festlegen und sich dann anmelden, um ein Zugriffstoken zu erhalten.

  1. Initialisieren und zum Dialogsatz hinzufügen 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 zur Verwendung der Graph-API in einer Bot-Anwendung finden Sie im Bot-SSO-Beispiel.

  Verwenden der Graph-API in der Nachrichtenerweiterung

  Der folgende Codeausschnitt veranschaulicht, wie das überschrieben handleTeamsMessagingExtensionQuerywird, das von TeamsActivityHandlerreicht. Es verwendet handleMessageExtensionQueryWithSSO das TeamsFx SDK, das vom TeamsFx SDK bereitgestellt wird, um sich anzumelden und 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 zur Verwendung der Graph-API in einer Nachrichtenerweiterung finden Sie im Beispiel message-extension-sso.

  Verwenden Sie die Graph-API im Befehlsbot

  Dieser Codeausschnitt veranschaulicht, wie TeamsFxBotSsoCommandHandler ein Befehlsbot implementiert, 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 using `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 eines SSO-Befehlshandlers in einem Befehlsbot finden Sie unter Hinzufügen von einmaligem Anmelden zur Teams-App. Es gibt auch ein command-bot-with-sso-Beispielprojekt , das Sie für den SSO-Befehlsbot ausprobieren können.

  Call Azure Function in tab app: On-Behalf-Of-Flow

  Dieser Codeausschnitt veranschaulicht, wie Sie die axios Bibliothek verwendenCreateApiClient, um eine Azure-Funktion aufzurufen, und wie Sie die Graph-API in einer Azure-Funktion aufrufen, um Benutzerprofile abzurufen.

  1. Zum Aufrufen einer Azure-Funktion können CreateApiClient Sie die vom TeamsFx-SDK bereitgestellte Funktion verwenden:

     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 axios Bibliothek auch verwenden, um eine 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);
       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 einer Azure-Funktion 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 zur Verwendung der Graph-API in einer Bot-Anwendung finden Sie im Beispiel hello-world-tab-with-backend.

• Anwendungsberechtigung im Back-End

  Verwenden der zertifikatbasierten Authentifizierung in der Azure-Funktion

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

  1. Sie können das appAuthConfig initialisieren, indem Sie eine PEM-encoded key certificate.

      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 geheimem Clientschlüssel in der Azure-Funktion

  Dieser Codeausschnitt veranschaulicht, wie Sie die Anwendungsberechtigung des geheimen Clientschlüssels verwenden, um das Token abzurufen, das zum Aufrufen der Graph-API verwendet wird.

  1. Sie können das authConfig initialisieren, indem Sie eine client secret.

     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 diese authConfig verwenden, um das Token abzurufen.

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

  Weitere Informationen zur Verwendung der Graph-API in einer Bot-Anwendung finden Sie im Beispiel hello-world-tab-with-backend.

Andere Szenarien

Dieser Abschnitt enthält mehrere Codeausschnitte für andere Szenarien im Zusammenhang mit Microsoft Graph. Sie können einen API-Client in einer Bot- oder Azure-Funktion erstellen und auf eine SQL-Datenbank in einer Azure-Funktion zugreifen.

API-Client zum Aufrufen vorhandener API in Bot oder Azure Function erstellen

Dieser Codeausschnitt zeigt, wie eine vorhandene API in einem Bot mit ApiKeyProvideraufgerufen wird.

// Create an API Key auth provider. In addition to ApiKeyProvider, the 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 the above auth provider.
// You can also implement the 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");  

Zugriff auf SQL-Datenbank in Azure Funktion

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

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 atk = 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 zu 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 erstellen, um mehr Flexibilität zu erzielen.

Weitere Informationen zum Zugriff auf eine SQL-Datenbank in einer Azure Funktion finden Sie im Beispiel "Jetzt freigeben".

Erweiterte Anpassung

Protokoll konfigurieren

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

Hinweis

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

Aktivieren des Protokolls durch Festlegen der Protokollebene

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

Legen Sie die Protokollebene mithilfe des folgenden Codeausschnitts fest:

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

Hinweis

Sie können die Protokollausgabe umleiten, indem Sie eine benutzerdefinierte Protokollierungs- oder Protokollfunktion festlegen.

Umleiten durch Festlegen einer benutzerdefinierten Protokollierung

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

Umleiten durch Festlegen einer benutzerdefinierten Protokollfunktion

setLogLevel(LogLevel.Info);
// Only log error messages 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.

Aktualisieren auf die neueste SDK-Version

Wenn Sie die Version des SDK verwenden, die über loadConfiguration()verfügt, können Sie die folgenden Schritte ausführen, um ein Upgrade auf die neueste SDK-Version durchzuführen:

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

Siehe auch

• Übersicht über das Microsoft 365 Agents-Toolkit
• Microsoft 365 Agents Toolkit CLI
• Microsoft TeamsFx-Beispielkatalog.
• Einmaliges Anmelden für die Teams-App hinzufügen