TeamsFx SDK

TeamsFx riduce le attività usando l'accesso Single Sign-on (SSO) di Microsoft Teams e l'accesso alle risorse cloud con istruzioni a riga singola e configurazione zero. È possibile usare TeamsFx SDK sia in ambienti browser che Node.js. Le funzionalità di base di TeamsFx sono accessibili in ambienti client e server. È possibile scrivere il codice di autenticazione utente per:

• Scheda Teams
• Bot di Teams
• Funzione di Azure

Prerequisiti

Installa gli strumenti seguenti e configura l'ambiente di sviluppo:

Per altre informazioni sulla compatibilità delle versioni di Node.js, vedere Prerequisiti per la creazione dell'app Teams con Visual Studio Code.

Devi avere una conoscenza pratica di:

• Codice sorgente
• Pacchetto (NPM)
• Documentazione di riferimento API
• Esempi

Guida introduttiva

TeamsFx SDK è preconfigurato nel progetto con scaffolding usando l'interfaccia della riga di comando di Microsoft 365 Agents Toolkit (in precedenza nota come TeamsFx Toolkit o CLI). Per altre informazioni, vedere Progetto app Teams.

Installare il pacchetto

Installa @microsoft/m365agentstoolkit-cli da npm ed esegui atk -h per controllare tutti i comandi disponibili:

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

Funzionalità di base di TeamsFx

Classe TeamsFx

Per impostazione predefinita, l'istanza della classe TeamsFx accede a tutte le impostazioni di TeamsFx dalle variabili di ambiente. È possibile impostare valori di configurazione personalizzati per sostituire i valori predefiniti. Per altre informazioni, vedere Sostituire la configurazione per i dettagli. Quando si crea un'istanza di TeamsFx, è necessario specificare il tipo di identità.

L'elenco seguente fornisce i due diversi tipi di identità:

• Identità utente: rappresenta l'utente corrente di Teams.
• Identità applicazione: rappresenta l'applicazione stessa.

Per altre informazioni sull'identità dell'utente e sull'identità dell'applicazione, vedere la sezione seguente:

Credenziale

Le classi di credenziali implementano l'interfaccia TokenCredential ampiamente usata nelle API della libreria di Azure progettate per fornire token di accesso per ambiti specifici. Per altre informazioni sulle classi correlate al flusso di credenziali e autenticazione, vedere Cartella delle credenziali.

Esistono tre classi di credenziali per semplificare l'autenticazione. Ecco gli scenari corrispondenti per ogni destinazione della classe di credenziali:

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

const credential = new TeamsUserCredential(authConfig);

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

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

Bot SSO

Le classi correlate ai bot sono archiviate nella cartella bot.

TeamsBotSsoPrompt Si integra con Bot Framework. Semplifica il processo di autenticazione quando si sviluppa un'applicazione bot e si vuole usare il bot SSO.

Il codice seguente è un esempio per creare 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);

Funzioni supportate

TeamsFx SDK offre diverse funzioni per facilitare la configurazione delle librerie di terze parti. Si trovano nella cartella principale.

• Microsoft Graph Service: createMicrosoftGraphClient, createMicrosoftGraphClientWithCredential, e MsGraphAuthProvider aiuto per creare istanze di Graph autenticate.

• SQL: restituisce getTediousConnectionConfig una configurazione di connessione noiosa.

  Configurazione richiesta:

  • Se si desidera utilizzare l'identità dell'utente, , , sqlServerEndpointsqlUsernamee sqlPassword sono obbligatori.
  • Se si desidera utilizzare l'identità MSI, allora sqlServerEndpoint e sqlIdentityId sono obbligatori.

Configurazione di override per la classe TeamsFx

È possibile passare la configurazione personalizzata durante la creazione di una nuova TeamsFx istanza per ignorare la configurazione predefinita o impostare i campi obbligatori quando environment variables mancano.

Gestione degli errori

Il tipo base di risposta all'errore dell'API è ErrorWithCode, che contiene il codice di errore e il messaggio di errore. Ad esempio, per escludere un errore specifico, è possibile usare il frammento seguente:

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

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

Se un'istanza delle credenziali viene usata in altre raccolte, ad esempio Microsoft Graph, è possibile che un errore venga rilevato e trasformato.

Scenari di Microsoft Graph

In questa sezione vengono forniti diversi frammenti di codice per gli scenari comuni correlati a Microsoft Graph. In questi scenari, l'utente può chiamare le API usando autorizzazioni diverse nel front-end o nel back-end.

• Autorizzazione utente delegato nel front-end (Uso TeamsUserCredential)

  Usare l'API Graph nell'app a schede

  Questo frammento di codice mostra come usare TeamsUserCredential e createMicrosoftGraphClientWithCredential ottenere i profili utente da Microsoft Graph nell'app a schede. Viene inoltre descritto come individuare e risolvere un file .GraphError

  1. Importa le classi necessarie.

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

  2. Creare TeamsUserCredential un'istanza.

     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. Da usare teamsUserCredential.login() per ottenere il consenso dell'utente.

     // 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. È possibile inizializzare un'istanza di TeamsFx e un client graph e ottenere informazioni da Microsoft Graph tramite questo client.

     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.
      }
     }
     

  Per altre informazioni sull'esempio per usare l'API Graph nell'app a schede, vedere Esempio di app Graph Conector.

  Integrazione con Microsoft Graph Toolkit

  La libreria Microsoft Graph Toolkit è una raccolta di vari provider di autenticazione e componenti dell'interfaccia utente basati su Microsoft Graph.

  Il @microsoft/mgt-teamsfx-provider pacchetto espone la classe che usa TeamsFx la TeamsFxProvider classe per accedere agli utenti e acquisire i token da usare con Microsoft Graph.

  1. Puoi installare i seguenti pacchetti richiesti:

        npm install @microsoft/mgt-element @microsoft/mgt-teamsfx-provider @microsoft/teamsfx
     

  2. Inizializza il provider all'interno del componente.

     // 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. È possibile usare il metodo per ottenere il teamsfx.login(scopes) token di accesso richiesto.

     // 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. È possibile aggiungere qualsiasi componente nella pagina HTML o nel metodo render() con React per utilizzare il TeamsFx contesto per accedere a Microsoft Graph.

     <mgt-person query="me" view="threeLines"></mgt-person>
     

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

  Per altre informazioni sull'esempio di inizializzazione del provider TeamsFx, vedere l'esempio di esportatore di contatti.

• Autorizzazione utente delegato nel back-end (Uso OnBehalfOfUserCredential)

  Usare l'API Graph nell'applicazione bot

  Questo frammento di codice illustra come impostare TeamsBotSsoPrompt una finestra di dialogo e quindi accedere per ottenere un token di accesso.

  1. Inizializza e aggiungi TeamsBotSsoPrompt al set di finestre di dialogo.

     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. Avvia la finestra di dialogo e accedi.

     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();
         }
       },
      ])
     );    
     

  Per altre informazioni su come usare l'API Graph in un'applicazione bot, vedere l'esempio bot-sso.

  Usare l'API Graph nell'estensione del messaggio

  Il frammento di codice seguente illustra come eseguire l'override handleTeamsMessagingExtensionQuerydi , che si estende da TeamsActivityHandler. handleMessageExtensionQueryWithSSO Utilizza quelli forniti dall'SDK di TeamsFx per accedere e ottenere un token di accesso:

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

  Per altre informazioni su come usare l'API Graph in un'estensione messaggio, vedere message-extension-sso-sample.

  Usa l'API Graph nel bot di comando

  Questo frammento di codice mostra come implementare TeamsFxBotSsoCommandHandler un bot di comando per chiamare l'API Microsoft.

   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.";
      }
    }
   }    
  
  

  Per altre informazioni sull'implementazione di un gestore di comandi SSO in un bot di comando, vedere Aggiungere l'accesso Single Sign-On all'app Teams. Esiste anche un progetto di esempio command-bot-with-sso che puoi provare per il bot di comando SSO.

  Chiama la funzione di Azure nell'app schede: flusso per conto di

  Questo frammento di codice illustra come usare CreateApiClient la axios libreria OR per chiamare una funzione di Azure e come chiamare l'API Graph in una funzione di Azure per ottenere profili utente.

  1. È possibile usare CreateApiClient fornito da TeamsFx SDK per chiamare una funzione di Azure:

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

     È anche possibile usare la axios libreria per chiamare una funzione di Azure.

     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. Chiamare l'API Graph in una funzione di Azure per conto dell'utente in risposta.

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

  Per ulteriori informazioni su come utilizzare l'API Graph in un'applicazione bot, vedere l'esempio hello-world-tab-with-backend.

• Autorizzazione dell'applicazione nel back-end

  Usare l'autenticazione basata su certificati nella funzione di Azure

  Questo frammento di codice illustra come usare l'autorizzazione dell'applicazione basata su certificato per ottenere il token che può essere usato per chiamare l'API API Graph.

  1. È possibile inizializzare fornendo appAuthConfig un file .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. Puoi usarlo AppCredential per ottenere il token.

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

  Usare l'autenticazione del segreto client nella funzione di Azure

  Questo frammento di codice illustra come usare l'autorizzazione dell'applicazione client secret per ottenere il token usato per chiamare l'API API Graph.

  1. È possibile inizializzare fornendo authConfig un file .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. Puoi usare il authConfig per ottenere il token.

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

  Per ulteriori informazioni su come utilizzare l'API Graph in un'applicazione bot, vedere l'esempio hello-world-tab-with-backend.

Altri scenari

In questa sezione sono disponibili diversi frammenti di codice per altri scenari correlati a Microsoft Graph. È possibile creare un client API in un bot o una funzione di Azure e accedere a un database SQL in una funzione di Azure.

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

Personalizzazione avanzata

Configura registro

È possibile impostare il livello di registro dei clienti e reindirizzare gli output quando si utilizza questa libreria.

Abilita il registro impostando il livello di registro

Quando si imposta il livello di log, la registrazione viene abilitata. Per impostazione predefinita, stampa le informazioni di log nella console.

Imposta il livello di log usando il frammento seguente:

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

Reindirizza impostando un logger personalizzato

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

Reindirizza impostando una funzione di log personalizzata

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

Aggiornare alla versione più recente dell'SDK

Se usi la versione dell'SDK che ha loadConfiguration(), puoi eseguire i passaggi seguenti per eseguire l'aggiornamento all'ultima versione dell'SDK:

1. Invece di chiamare loadConfiguration(), utilizzare le classi di configurazione di autenticazione specifiche per personalizzare le impostazioni per ogni tipo di credenziale. Ad esempio, utilizzate AppCredentialAuthConfig for AppCredential, OnBehalfOfUserCredentialAuthConfig for OnBehalfOfUserCredentiale TeamsUserCredentialAuthConfig for TeamsUserCredential.
2. Sostituisci new TeamsUserCredential() con new TeamsUserCredential(authConfig).
3. Sostituisci new M365TenantCredential() con new AppCredential(authConfig).
4. Sostituisci new OnBehalfOfUserCredential(ssoToken) con new OnBehalfOfUserCredential(authConfig).

Vedere anche

• Panoramica di Microsoft 365 Agents Toolkit
• Interfaccia della riga di comando di Microsoft 365 Agents Toolkit
• Raccolta di esempio Microsoft TeamsFx.
• Aggiungere l'accesso Single Sign-On all'app Teams