TeamsFx SDK

Important

Le SDK TeamsFx n’est plus pris en charge par Microsoft pour la création d’extensions Microsoft 365 Copilot, d’agents Microsoft 365 ou de scénarios d’applications Teams modernes. Le Kit de développement logiciel (SDK) est actuellement en mode dépréciation et bénéficiera d’un support communautaire uniquement sur GitHub jusqu’en septembre 2026.

Pour tous les nouveaux développements pris en charge par Microsoft (extensions Copilot, agents d’IA, applications Teams ou extensibilité plus large de Microsoft 365), utilisez :

  • Microsoft 365 Agents SDK (recommandé pour toutes les nouvelles expériences Copilot ou basées sur un agent)
  • SDK Teams (pour la création d’applications et de bots Teams uniquement)

Les nouveaux projets ne doivent pas être construits avec TeamsFx. Les solutions TeamsFx existantes doivent être migrées vers le Microsoft 365 Agents SDK.

TeamsFx réduit vos tâches en utilisant l’authentification unique (SSO) de Microsoft Teams et en accédant aux ressources cloud avec des instructions sur une seule ligne et une configuration nulle. Vous pouvez utiliser le SDK TeamsFx dans les environnements de navigateur et de Node.js. Les fonctionnalités de base de TeamsFx sont accessibles dans les environnements client et serveur. Vous pouvez écrire du code d’authentification utilisateur pour :

  • Onglet Teams
  • Bot Teams
  • Fonction Azure

Configuration requise

Installez les outils suivants et configurez votre environnement de développement :

  Installer Pour utiliser...
  Visual Studio Code environnements de construction JavaScript, TypeScript ou SharePoint Framework (SPFx). Utilisez la version 1.55 ou ultérieure.
  Microsoft 365 Agents Toolkit (anciennement Teams Toolkit) Extension de Microsoft Visual Studio Code qui crée une génération de modèles automatique de projet pour votre application. Utilisez la version 4.0.0.
  Node.js Environnement d’exécution JavaScript back-end. Pour plus d’informations, consultez Node.js tableau de compatibilité des versions pour le type de projet.
  Microsoft Teams Microsoft Teams pour collaborer avec toutes les personnes avec lesquelles vous travaillez via des applications pour le chat, les réunions, les appels, et le tout au même endroit.
  Microsoft Edge (recommandé) ou Google Chrome Navigateur avec outils de développement.

Pour plus d’informations sur Node.js compatibilité de version, voir Conditions préalables à la création de votre application Teams à l’aide de Visual Studio Code.

Remarque

Si votre projet a installé botbuilderdes packages associés en tant que dépendances, vérifiez qu’ils sont de la même version.

Vous devez avoir une connaissance pratique des domaines suivants :

Prise en main

Le SDK TeamsFx est préconfiguré dans le projet de génération de modèles automatiques à l’aide de l’interface de ligne de commande Microsoft 365 Agents Toolkit (anciennement TeamsFx Toolkit ou CLI). Pour plus d’informations, voir Projet d’application Teams.

Conseil

Les extraits de code sont mis à jour pour le dernier SDK TeamsFx version 2.

Installer le package

Installez @microsoft/m365agentstoolkit-cli à partir de et exécutez atk -h pour vérifier toutes les commandes disponibles dans le cas de npm la case activée :

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

Fonctionnalités principales de TeamsFx

Classe TeamsFx

L’instance de classe TeamsFx accède par défaut à tous les paramètres de TeamsFx à partir des variables d’environnement. Vous pouvez définir des valeurs de configuration personnalisées pour remplacer les valeurs par défaut. Pour plus d’informations, voir Remplacer la configuration pour plus de détails. Lors de la création d’une instance TeamsFx, vous devez spécifier le type d’identité.

La liste suivante répertorie les deux types d’identités :

  • Identité de l’utilisateur : représente l’utilisateur actuel de Teams.
  • Identité de l’application : représente l’application elle-même.

Remarque

Les constructeurs et méthodes TeamsFx ne sont pas identiques pour ces deux types d’identité.

Vous pouvez en savoir plus sur l’identité utilisateur et l’identité d’application dans la section suivante :

Identité de l’utilisateur
Commande Description
new TeamsFx(IdentityType.User) L’application est authentifiée en tant qu’utilisateur actuel de Teams.
TeamsFx:setSsoToken() Identité de l’utilisateur dans Node.js environnement (sans navigateur).
TeamsFx:getUserInfo() Pour obtenir les informations de base de l’utilisateur.
TeamsFx:login() Il est utilisé pour permettre à l’utilisateur d’effectuer un processus de consentement, si vous voulez utiliser l’authentification unique pour obtenir un jeton d’accès pour certaines étendues OAuth.

Remarque

Vous pouvez accéder aux ressources pour le compte de l’utilisateur Teams actuel.

Identité de l’application
Commande Description
new TeamsFx(IdentityType.App) L’application est authentifiée en tant qu’application. L’autorisation nécessite généralement l’approbation de l’administrateur.
TeamsFx:getCredential() Elle fournit des instances d’informations d’identification correspondant automatiquement au type d’identité.

Remarque

Vous devez obtenir le consentement de l’administrateur pour les ressources.

Informations d’identification

Les classes d’informations d’identification implémentent l’interface TokenCredential largement utilisée dans les API de bibliothèque Azure conçues pour fournir des jetons d’accès pour des étendues spécifiques. Pour plus d’informations sur les classes liées aux informations d’identification et au flux d’authentification, consultez Dossier des informations d’identification.

Il existe trois classes d’informations d’identification pour simplifier l’authentification. Voici les scénarios correspondants pour chaque cible de classe d’informations d’identification :

Identité de l’utilisateur dans l’environnement du navigateur

TeamsUserCredential représente l’identité de l’utilisateur actuel Teams. Pour la première authentification des informations d’identification d’un utilisateur, l’authentification unique Teams effectue le flux de la part de pour l’échange de jetons. Le Kit de développement logiciel (SDK) utilise ces informations d’identification lorsque vous choisissez l’identité de l’utilisateur dans l’environnement du navigateur.

Le code suivant est un exemple à créer 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);

Les configurations requises sont initiateLoginEndpoint et clientId se trouvent dans le type TeamsUserCredentialAuthConfig.

Identité de l’utilisateur dans Node.js environnement

OnBehalfOfUserCredentialutilise le flux De la part de et nécessite le jeton SSO Teams dans les scénarios de fonction ou de bot Azure. Le SDK TeamsFx utilise les informations d’identification suivantes lorsque vous choisissez l’identité de l’utilisateur dans Node.js environnement.

Le code suivant est un exemple à créer 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);

Les configurations requises sont authorityHost, tenantIdclientIdclientSecretou certificateContent qui se trouve dans le type .OnBehalfOfCredentialAuthConfig

Identité de l’application dans Node.js environnement

AppCredential Représente l’identité de l’application. Vous pouvez utiliser l’identité d’application lorsque l’utilisateur n’est pas impliqué, par exemple, dans une tâche d’automatisation déclenchée par le temps. Le SDK TeamsFx utilise les informations d’identification suivantes lorsque vous choisissez l’identité de l’application dans Node.js environnement.

Le code suivant est un exemple à créer 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);

Les configurations requises sont authorityHost, tenantIdclientIdclientSecretou certificateContent qui est de type intérieurAppCredentialAuthConfig

Bot SSO

Les classes liées aux bots sont stockées dans le dossier bot.

TeamsBotSsoPrompt s’intègre à Bot Framework. Il simplifie le processus d’authentification lorsque vous développez une application bot et souhaitez utiliser l’authentification unique du bot.

Le code suivant est un exemple à créer 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);

Fonctions prises en charge

Le SDK TeamsFx fournit plusieurs fonctions pour faciliter la configuration des bibliothèques tierces. Ils se trouvent sous le dossier principal.

  • Service Microsoft Graph : createMicrosoftGraphClient, createMicrosoftGraphClientWithCredentialet MsGraphAuthProvider aide à la création d’une instance Graph authentifiée.

Remarque

createMicrosoftGraphClient La fonction a été déconseillée. Il est recommandé de l’utiliser createMicrosoftGraphClientWithCredential à la place, pour une meilleure expérience de codage.

  • SQL : Le getTediousConnectionConfig retourne une configuration de connexion fastidieuse.

    Configuration requise :

    • Si vous souhaitez utiliser l’identité de l’utilisateur, alors sqlServerEndpoint, sqlUsernameet sqlPassword sont obligatoires.
    • Si vous souhaitez utiliser l’identité MSI, alors sqlServerEndpoint et sqlIdentityId sont obligatoires.

Remarque

Cette getTediousConnectionConfig fonction a été déconseillée. Pour plus de flexibilité, il est recommandé de composer votre propre configuration fastidieuse.

Remplacer la configuration pour la classe TeamsFx

Remarque

La classe TeamsFx a été déconseillée. Utilisez TeamsUserCredential, OnBehalfOfUserCredentialet AppCredential à la place.

Vous pouvez transmettre une configuration personnalisée lors de la création d’une TeamsFx nouvelle instance pour remplacer la configuration par défaut ou définir des champs obligatoires lorsqu’ils environment variables sont manquants.

Pour projet d’onglet

Si vous avez créé un projet d’onglet à l’aide de Microsoft Visual Studio Code Toolkit, les valeurs de configuration suivantes sont utilisées à partir de variables d’environnement préconfigurées :

  • 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) // utilisé uniquement lorsqu’il existe une fonction backend
  • apiName (REACT_APP_FUNC_NAME) // utilisé uniquement lorsqu’il existe une fonction backend
Pour un projet de fonction ou de bot Azure

Si vous avez créé un projet de fonction ou de bot Azure à l’aide de Visual Studio Code Toolkit, les valeurs de configuration suivantes sont utilisées à partir de variables d’environnement préconfigurées :

  • 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) // Utilisé uniquement lorsqu’il existe un instance SQL

  • sqlUsername (SQL_USER_NAME) // utilisé uniquement lorsqu’il existe un instance sql

  • sqlPassword (SQL_PASSWORD) // utilisé uniquement lorsqu’il existe un instance SQL

  • sqlDatabaseName (SQL_DATABASE_NAME) // utilisé uniquement lorsqu’il existe un instance SQL

  • sqlIdentityId (IDENTITY_ID) // utilisé uniquement lorsqu’il existe un instance SQL

Gestion des erreurs

Le type de base de la réponse d’erreur d’API est ErrorWithCode, qui contient le code d’erreur et le message d’erreur. Par exemple, pour filtrer une erreur spécifique, vous pouvez utiliser l’extrait de code suivant :

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

Remarque

La classe TeamsFx a été déconseillée et ErrorWithCode n’est pas recommandée. Vous pouvez l’utiliser TeamsUserCredential à la place.

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

Si une instance d’informations d’identification est utilisée dans une autre bibliothèque, telle que Microsoft Graph, il est possible qu’une erreur soit interceptée et transformée.

Scénarios Microsoft Graph

Cette section fournit plusieurs extraits de code pour les scénarios courants liés à Microsoft Graph. Dans de tels scénarios, l’utilisateur peut appeler des API à l’aide d’autorisations différentes dans le serveur frontal ou principal.

  • Autorisation de délégué d’utilisateur dans le serveur frontal (Utiliser TeamsUserCredential)

    Utiliser l’API Graph dans l’application d’onglet

    Cet extrait de code vous montre comment utiliser TeamsUserCredential et createMicrosoftGraphClientWithCredential obtenir des profils utilisateur à partir de Microsoft Graph dans l’application d’onglet. Il vous montre également comment intercepter et résoudre un GraphErrorfichier .

    1. Importez les classes nécessaires.

      import {
       createMicrosoftGraphClientWithCredential,
       TeamsUserCredential,
      } from "@microsoft/teamsfx";
      
    2. Créer une TeamsUserCredential instance.

      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. Permet teamsUserCredential.login() d’obtenir le consentement de l’utilisateur.

      // 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. Vous pouvez initialiser un client TeamsFx instance et graphique et obtenir des informations de Microsoft Graph par ce 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.
       }
      }
      

    Pour plus d’informations sur l’exemple d’utilisation de l’API Graph dans l’application d’onglet, consultez l’exemple d’application Graph Conector.

    Intégration à Boîte à outils Microsoft Graph

    La bibliothèque Boîte à outils Microsoft Graph est une collection de différents fournisseurs d’authentification et composants d’interface utilisateur optimisés par Microsoft Graph.

    Le @microsoft/mgt-teamsfx-provider package expose la classe qui utilise TeamsFx class TeamsFxProvider pour connecter des utilisateurs et acquérir des jetons à utiliser avec Microsoft Graph.

    1. Vous pouvez installer les packages requis suivants :

         npm install @microsoft/mgt-element @microsoft/mgt-teamsfx-provider @microsoft/teamsfx
      
    2. Initialisez le fournisseur dans votre composant.

      // 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. Vous pouvez utiliser la méthode pour obtenir le teamsfx.login(scopes) jeton d’accès requis.

      // 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. Vous pouvez ajouter n’importe quel composant dans votre page HTML ou dans votre render() méthode avec React pour utiliser le TeamsFx contexte afin d’accéder à Microsoft Graph.

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

    Pour plus d’informations sur l’exemple d’initialisation du fournisseur TeamsFx, consultez l’exemple d’exportateur de contacts.

  • Autorisation de délégué d’utilisateur dans le back-end (Utiliser OnBehalfOfUserCredential)

    Utiliser l’API Graph dans l’application bot

    Cet extrait de TeamsBotSsoPrompt code vous montre comment utiliser pour configurer une boîte de dialogue, puis vous connecter pour obtenir un jeton d’accès.

    1. Initialiser et ajouter TeamsBotSsoPrompt à l’ensemble de dialogue.

      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. Démarrez le dialogue et connectez-vous.

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

    Pour plus d’informations sur l’utilisation de l’API Graph dans une application de bot, consultez l’exemple bot-sso.

    Utiliser l’API Graph dans l’extension de message

    L’extrait de code suivant montre comment remplacer handleTeamsMessagingExtensionQuery, qui s’étend de TeamsActivityHandler. Il utilise handleMessageExtensionQueryWithSSO fourni par le SDK TeamsFx pour se connecter et obtenir un jeton d’accès :

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

    Pour plus d’informations sur l’utilisation de l’API Graph dans une extension de message, consultez message-extension-sso-sample.

    Utiliser l’API Graph dans le bot de commande

    Cet extrait de code montre comment implémenter TeamsFxBotSsoCommandHandler un bot de commande pour appeler 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.";
        }
      }
     }    
    
    

    Pour plus d’informations sur l’implémentation d’un gestionnaire de commandes SSO dans un bot de commande, consultez Ajouter une authentification unique à l’application Teams. Il existe également un exemple de projet command-bot-with-sso que vous pouvez essayer pour le bot de commande SSO.

    Appeler la fonction Azure dans l’application d’onglet : Flux de la part de

    Cet extrait de code montre comment utiliser CreateApiClient la axios bibliothèque pour appeler une fonction Azure, et comment appeler l’API Graph dans une fonction Azure pour obtenir des profils utilisateur.

    1. Vous pouvez utiliser CreateApiClient fourni par le SDK TeamsFx pour appeler une fonction 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;
      }    
      

      Vous pouvez également utiliser la axios bibliothèque pour appeler une fonction 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. Appelez l’API Graph dans une fonction Azure pour le compte de l’utilisateur en réponse.

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

    Pour plus d’informations sur l’utilisation de l’API Graph dans une application de robot, consultez l’exemple hello-world-tab-with-backend.

  • Autorisation d’application dans le back-end

    Utiliser l’authentification basée sur les certificats dans Fonction Azure

    Cet extrait de code montre comment utiliser l’autorisation d’application basée sur un certificat pour obtenir le jeton qui peut être utilisé pour appeler l’API Graph.

    1. Vous pouvez initialiser le appAuthConfig en fournissant un PEM-encoded key certificatefichier .

       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. Vous pouvez l’utiliser AppCredential pour obtenir le jeton.

      const appCredential = new AppCredential(appAuthConfig);
      const token = appCredential.getToken();    
      
    Utiliser l’authentification par clé secrète client dans Fonction Azure

    Cet extrait de code montre comment utiliser l’autorisation d’application de secret client pour obtenir le jeton utilisé pour appeler l’API Graph.

    1. Vous pouvez initialiser le authConfig en fournissant un client secretfichier .

      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. Vous pouvez utiliser le authConfig pour obtenir le jeton.

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

    Pour plus d’informations sur l’utilisation de l’API Graph dans une application de robot, consultez l’exemple hello-world-tab-with-backend.

Autres scénarios

Cette section fournit plusieurs extraits de code pour d’autres scénarios liés à Microsoft Graph. Vous pouvez créer un client API dans un bot ou une fonction Azure et accéder à une base de données SQL dans une fonction Azure.

Créer un client API pour appeler une API existante dans Bot ou Fonction Azure

Cet extrait de code montre comment appeler une API existante dans un bot à l’aide de ApiKeyProvider.

// 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");  
Accéder à la base de données SQL dans la fonction Azure

Utiliser la tedious bibliothèque pour accéder à SQL et utiliser DefaultTediousConnectionConfiguration cette gère l’authentification. Vous pouvez également composer une configuration de connexion d’autres bibliothèques SQL en fonction du résultat de sqlConnectionConfig.getConfig().

  1. Définissez la configuration de connexion.

    // 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. Connectez-vous à votre base de données.

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

    Remarque

    Cette getTediousConnectionConfig fonction a été déconseillée. Nous vous recommandons de composer votre propre configuration fastidieuse pour une meilleure flexibilité.

Pour plus d’informations sur l’accès à une base de données SQL dans une fonction Azure, consultez l’exemple Partager maintenant.

Personnalisation avancée

Configurer le journal

Vous pouvez définir le niveau du journal client et rediriger les sorties lors de l’utilisation de cette bibliothèque.

Remarque

Les journaux sont désactivés par défaut. Vous pouvez les activer en définissant le niveau de journal.

Activer le journal en définissant le niveau de journal

Lorsque vous définissez le niveau de journalisation, la journalisation est activée. Il imprime les informations du journal sur la console par défaut.

Définissez le niveau de journal à l’aide de l’extrait de code suivant :

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

Remarque

Vous pouvez rediriger la sortie du journal en définissant une fonction d’enregistrement ou de journal personnalisée.

Rediriger en définissant un enregistreur personnalisé

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

Rediriger en définissant la fonction log personnalisée

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

Remarque

Les fonctions de journal ne prennent effet pas si vous définissez un enregistreur personnalisé.

Mise à niveau vers la dernière version du Kit de développement logiciel (SDK)

Si vous utilisez la version du SDK qui a loadConfiguration(), vous pouvez effectuer les étapes suivantes pour effectuer la mise à niveau vers la dernière version du SDK :

  1. Au lieu d’appeler loadConfiguration(), utilisez les classes de configuration d’authentification spécifiques pour personnaliser les paramètres de chaque type d’informations d’identification. Par exemple, utilisez AppCredentialAuthConfig for AppCredential, OnBehalfOfUserCredentialAuthConfig for OnBehalfOfUserCredential, et TeamsUserCredentialAuthConfig for TeamsUserCredential.
  2. Remplacer new TeamsUserCredential() par new TeamsUserCredential(authConfig).
  3. Remplacer new M365TenantCredential() par new AppCredential(authConfig).
  4. Remplacer new OnBehalfOfUserCredential(ssoToken) par new OnBehalfOfUserCredential(authConfig).

Voir aussi