Kit de développement logiciel (SDK) TeamsFx
TeamsFx vous aide à réduire vos tâches en utilisant l’authentification unique (SSO) Microsoft Teams et en accédant aux ressources cloud jusqu’aux instructions d’une seule ligne sans configuration. Vous pouvez utiliser le Kit de développement logiciel (SDK) TeamsFx dans le navigateur et Node.js environnements. Les fonctionnalités principales de TeamsFx sont accessibles dans les environnements client et serveur. Vous pouvez écrire le code d’authentification utilisateur pour :
- Onglet Teams
- Bot Teams
- Fonction Azure
Configuration requise
Vous devez installer les outils suivants et configurer votre environnement de développement :
Installer | Pour l’utilisation... | |
---|---|---|
Visual Studio Code | Environnements de build JavaScript, TypeScript ou SharePoint Framework (SPFx). Utilisez la version 1.55 ou ultérieure. | |
Toolkit Teams | Extension Microsoft Visual Studio Code qui crée une structure de projet pour votre application. Utilisez la version 4.0.0. | |
Node.js | Environnement runtime JavaScript principal. Pour plus d’informations, consultez Node.js table 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 la conversation, les réunions, les appels et le tout au même endroit. | |
Microsoft Edge (recommandé) ou Google Chrome | Un navigateur avec des outils de développement. |
Pour plus d’informations sur Node.js compatibilité des versions, consultez Prérequis pour la création de votre application Teams à l’aide de Visual Studio Code.
Remarque
Si votre projet a installé botbuilder
des 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 points suivants :
Prise en main
Le Kit de développement logiciel (SDK) TeamsFx est préconfiguré dans le projet généré automatiquement à l’aide du Kit de ressources TeamsFx ou de l’interface CLI. Pour plus d’informations, consultez projet d’application Teams.
Conseil
Les extraits de code sont mis à jour pour la dernière version du Kit de développement logiciel (SDK) TeamsFx version 2.
Installer le package @microsoft/teamsfx
Installez le Kit de développement logiciel (SDK) TeamsFx pour TypeScript ou JavaScript avec npm
:
npm install @microsoft/teamsfx
Fonctionnalités principales de TeamsFx
Classe TeamsFx
Par défaut, l’instance de classe TeamsFx accède à tous les paramètres 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, consultez configuration de remplacement pour plus d’informations. Lors de la création d’une instance TeamsFx, vous devez spécifier le type d’identité.
La liste suivante fournit les deux types d’identités différents :
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 les mêmes pour ces deux types d’identité.
Pour en savoir plus sur l’identité de l’utilisateur et de l’application, consultez la section suivante :
Identité de l’utilisateur
Command | Description |
---|---|
new TeamsFx(IdentityType.User) |
L’application est authentifiée en tant qu’utilisateur Teams actuel. |
TeamsFx:setSsoToken() |
Identité de l’utilisateur dans l’environnement Node.js (sans navigateur). |
TeamsFx:getUserInfo() |
Pour obtenir les informations de base de l’utilisateur. |
TeamsFx:login() |
Il est utilisé pour permettre à l’utilisateur d’effectuer le processus de consentement, si vous souhaitez utiliser SSO 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
Command | 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() |
Il fournit des instances d’informations d’identification correspondant automatiquement au type d’identité. |
Remarque
Vous avez besoin du consentement de l’administrateur pour les ressources.
Credential
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 associées aux informations d’identification et au flux d’authentification, consultez dossier d’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 de navigateur
TeamsUserCredential
représente l’identité de l’utilisateur actuel de Teams. Pour la première fois que les informations d’identification de l’utilisateur sont authentifiées, l’authentification unique Teams effectue le flux On-Behalf-Of pour l’échange de jetons. Le 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
OnBehalfOfUserCredential
utilise le flux On-Behalf-Of et nécessite un jeton d’authentification unique Teams, dans les scénarios de fonction Azure ou de bot. Le Kit de développement logiciel (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 , , clientId
, ou certificateContent
qui se trouvent dans le type OnBehalfOfCredentialAuthConfig
. clientSecret
tenantId
authorityHost
Identité de l’application dans Node.js environnement
AppCredential
représente l’identité de l’application. Vous pouvez utiliser l’identité de l’application lorsque l’utilisateur n’est pas impliqué, par exemple dans un travail d’automatisation déclenché dans le temps. Le Kit de développement logiciel (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
, tenantId
, clientId
clientSecret
, ou certificateContent
qui se trouvent à l’intérieur du typeAppCredentialAuthConfig
Authentification unique du bot
Les classes associées au bot sont stockées sous dossier de bot.
TeamsBotSsoPrompt
s’intègre à l’infrastructure de bot. Il simplifie le processus d’authentification lorsque vous développez une application de bot et que vous 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 Kit de développement logiciel (SDK) TeamsFx fournit plusieurs fonctions pour faciliter la configuration des bibliothèques tierces. Ils se trouvent sous le dossier principal.
Service Microsoft Graph :
createMicrosoftGraphClient
,createMicrosoftGraphClientWithCredential
, etMsGraphAuthProvider
permet de créer une instance Graph authentifiée.Remarque
createMicrosoftGraphClient
la fonction a été déconseillée. Il vous est recommandé d’utilisercreateMicrosoftGraphClientWithCredential
à la place, pour une meilleure expérience de codage.SQL : retourne
getTediousConnectionConfig
une configuration de connexion fastidieuse.Configuration requise :
- Si vous souhaitez utiliser l’identité de l’utilisateur, ,
sqlServerEndpoint
sqlUsername
etsqlPassword
sont obligatoires. - Si vous souhaitez utiliser l’identité MSI,
sqlServerEndpoint
etsqlIdentityId
sont obligatoires.
Remarque
La
getTediousConnectionConfig
fonction a été déconseillée. Il vous est recommandé de composer votre propre configuration Tedious pour une meilleure flexibilité.- Si vous souhaitez utiliser l’identité de l’utilisateur, ,
Remplacer la configuration de la classe TeamsFx
Remarque
La classe TeamsFx a été déconseillée. Utilisez TeamsUserCredential
, OnBehalfOfUserCredential
et AppCredential
à la place.
Vous pouvez passer une configuration personnalisée lors de la création d’une nouvelle TeamsFx
instance pour remplacer la configuration par défaut ou définir les champs obligatoires lorsqu’ils environment variables
sont manquants.
Pour le 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 back-end
- apiName (REACT_APP_FUNC_NAME) // utilisé uniquement lorsqu’il existe une fonction back-end
Pour une fonction Azure ou un projet de bot
Si vous avez créé une fonction Azure ou un projet de bot à 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 une instance sql
sqlUsername (SQL_USER_NAME) // utilisé uniquement lorsqu’il existe une instance sql
sqlPassword (SQL_PASSWORD) // utilisé uniquement lorsqu’il existe une instance sql
sqlDatabaseName (SQL_DATABASE_NAME) // utilisé uniquement lorsqu’il existe une instance SQL
sqlIdentityId (IDENTITY_ID) // utilisé uniquement lorsqu’il existe une instance SQL
Gestion des erreurs
Le type de base de réponse d’erreur de l’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 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;
}
}
Remarque
La classe TeamsFx a été déconseillée et ErrorWithCode
n’est pas recommandée. Vous pouvez 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 front-end ou le back-end.
Autorisation de délégué d’utilisateur dans le front-end (utilisez
TeamsUserCredential
)Utiliser l’API graph dans l’application onglet
Cet extrait de code vous montre comment utiliser
TeamsUserCredential
etcreateMicrosoftGraphClientWithCredential
obtenir des profils utilisateur à partir de Microsoft Graph dans l’application onglet. Il vous montre également comment intercepter et résoudre unGraphError
.Importez les classes nécessaires.
import { createMicrosoftGraphClientWithCredential, TeamsUserCredential, } from "@microsoft/teamsfx";
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);
Utilisez
teamsUserCredential.login()
pour 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
Vous pouvez initialiser une instance TeamsFx et un client graph et obtenir des informations auprès 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 onglet, consultez Exemple d’application Graph Conector.
Intégration à Microsoft Graph Toolkit
La bibliothèque du Kit de ressources 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 utiliseTeamsFx
laTeamsFxProvider
classe pour connecter les utilisateurs et acquérir des jetons à utiliser avec Microsoft Graph.Vous pouvez installer les packages requis suivants :
npm install @microsoft/mgt-element @microsoft/mgt-teamsfx-provider @microsoft/teamsfx
Initialisez le fournisseur à l’intérieur de 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 teamsfx = new TeamsFx(); const provider = new TeamsFxProvider(teamsfx, scope); Providers.globalProvider = provider;
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);
Vous pouvez ajouter n’importe quel composant dans votre page HTML ou dans votre
render()
méthode avec React pour utiliser leTeamsFx
contexte pour 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 serveur principal (utilisez
OnBehalfOfUserCredential
)Utiliser l’API Graph dans une application de bot
Cet extrait de code vous montre comment utiliser
TeamsBotSsoPrompt
pour définir une boîte de dialogue, puis vous connecter pour obtenir un jeton d’accès.Initialisez et ajoutez
TeamsBotSsoPrompt
à l’ensemble de dialogues.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);
Démarrez la boîte de 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’exemple d’utilisation de l’API de graphe dans une application de bot, consultez exemple bot-sso.
Utiliser l’API Graph dans l’extension de message
L’extrait de code suivant montre comment remplacer
handleTeamsMessagingExtensionQuery
ce qui s’étend à partir deTeamsActivityHandler
et utiliserhandleMessageExtensionQueryWithSSO
fourni par le SDK TeamsFx pour se connecter afin d’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’exemple d’utilisation de l’API graph dans l’extension de message, consultez message-extension-sso-sample.
Utiliser l’API Graph dans command bot
Cet extrait de code vous montre comment implémenter
TeamsFxBotSsoCommandHandler
pour que le bot de commande appelle 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 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."; } } }
Pour plus d’informations sur l’implémentation du gestionnaire de commandes SSO dans le bot de commandes, consultez Ajouter l’authentification unique à l’application Teams. Et il existe un exemple de projet command-bot-with-sso , que vous pouvez essayer le bot de commande SSO.
Appeler la fonction Azure dans l’application d’onglet : Flux On-Behalf-Of
Cet extrait de code vous montre comment utiliser
CreateApiClient
ouaxios
bibliothèque pour appeler Une fonction Azure, et comment appeler l’API Graph dans Azure Function pour obtenir des profils utilisateur.Vous pouvez utiliser
CreateApiClient
le kit de développement logiciel (SDK) TeamsFx pour appeler la 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 Azure Function.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; }
Appelez l’API Graph dans Azure Function au nom 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’exemple d’utilisation de l’API de graphe dans une application de bot, consultez exemple hello-world-tab-with-backend.
Autorisation d’application dans le serveur principal
Utiliser l’authentification basée sur les certificats dans Azure Function
Cet extrait de code vous 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.
Vous pouvez initialiser en
appAuthConfig
fournissant unPEM-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', };
Vous pouvez utiliser
AppCredential
pour obtenir le jeton.const appCredential = new AppCredential(appAuthConfig); const token = appCredential.getToken();
Utiliser l’authentification de clé secrète client dans Azure Function
Cet extrait de code vous montre comment utiliser l’autorisation d’application de clé secrète client pour obtenir le jeton utilisé pour appeler l’API Graph.
Vous pouvez initialiser en
authConfig
fournissant unclient 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, };
Vous pouvez utiliser pour
authConfig
obtenir le jeton.const appCredential = new AppCredential(appAuthConfig); const token = appCredential.getToken();
Pour plus d’informations sur l’exemple d’utilisation de l’API de graphe dans une application de bot, 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 d’API dans Bot ou Azure Function et accéder à la base de données SQL dans Azure Function.
Créer un client d’API pour appeler une API existante dans Bot ou Azure Function
Cet extrait de code vous montre comment appeler une API existante dans le bot par ApiKeyProvider
.
// 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");
Accéder à la base de données SQL dans la fonction Azure
Utilisez la tedious
bibliothèque pour accéder à SQL et utilisez DefaultTediousConnectionConfiguration
qui gère l’authentification. Vous pouvez également composer la configuration de connexion d’autres bibliothèques SQL en fonction du résultat de sqlConnectionConfig.getConfig()
.
Définissez la configuration de la connexion.
// 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");
Connectez-vous à votre base de données.
const connection = new Connection(config); connection.on("connect", (error) => { if (error) { console.log(error); } });
Remarque
La
getTediousConnectionConfig
fonction a été déconseillée. Il vous est recommandé de composer votre propre configuration fastidieuse pour une meilleure flexibilité.
Pour plus d’informations sur l’exemple permettant d’accéder à une base de données SQL dans Azure Function, consultez exemple share-now.
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 journalisation.
Activer le journal en définissant le niveau du journal
Lorsque vous définissez le niveau de journalisation, la journalisation est activée. Il imprime les informations de journal sur la console par défaut.
Définissez le niveau du 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’enregistreur d’événements ou de journal personnalisée.
Rediriger en définissant un enregistreur d’événements 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 une fonction de journal personnalisée
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,
});
}
});
Remarque
Les fonctions de journal ne prennent pas effet si vous définissez un enregistreur d’événements personnalisé.
Mettre à niveau vers la dernière version du KIT de développement logiciel (SDK)
Si vous utilisez la version du Kit de développement logiciel (SDK) qui contient loadConfiguration()
, vous pouvez effectuer les étapes suivantes pour effectuer une mise à niveau vers la dernière version du KIT de développement logiciel (SDK) :
- 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, utilisezAppCredentialAuthConfig
pourAppCredential
,OnBehalfOfUserCredentialAuthConfig
pourOnBehalfOfUserCredential
etTeamsUserCredentialAuthConfig
pourTeamsUserCredential
. - Remplacez
new TeamsUserCredential()
parnew TeamsUserCredential(authConfig)
. - Remplacez
new M365TenantCredential()
parnew AppCredential(authConfig)
. - Remplacez
new OnBehalfOfUserCredential(ssoToken)
parnew OnBehalfOfUserCredential(authConfig)
.