TeamsFx SDK

Artigo
07/16/2024

O TeamsFx ajuda a reduzir as suas tarefas ao utilizar o início de sessão único (SSO) do Microsoft Teams e ao aceder aos recursos da cloud até instruções de linha única com zero configurações. Pode utilizar o SDK do TeamsFx nos ambientes de browser e Node.js. As principais funcionalidades do TeamsFx podem ser acedidas em ambientes de cliente e servidor. Pode escrever código de autenticação de utilizador para:

Separador Teams
Bot do Teams
Função do Azure

Pré-requisitos

Tem de instalar as seguintes ferramentas e configurar o seu ambiente de desenvolvimento:

	Instalar	Para usar...
	Visual Studio Code	Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Utilize a versão 1.55 ou posterior.
	Kit de ferramentas do Teams	Uma extensão do Microsoft Visual Studio Code que cria um projeto estruturado para a sua aplicação. Utilize a versão 4.0.0.
	Node.js	Ambiente de runtime do JavaScript de back-end. Para obter mais informações, veja Node.js tabela de compatibilidade de versões para o tipo de projeto.
	Microsoft Teams	Microsoft Teams para colaborar com todas as pessoas com quem trabalha através de aplicações para chat, reuniões, chamadas e tudo num único local.
	Microsoft Edge (recomendado) ou Google Chrome	Um navegador com ferramentas de desenvolvedor.

Para obter mais informações sobre Node.js compatibilidade de versões, veja Pré-requisitos para criar a sua aplicação teams com o Visual Studio Code.

Observação

Se o projeto tiver instalado botbuilderpacotes relacionados como dependências, certifique-se de que têm a mesma versão.

Tem de ter conhecimentos práticos sobre:

Introdução

O SDK do TeamsFx é pré-configurado no projeto com scaffolding usando o Kit de Ferramentas do TeamsFx ou a CLI. Para obter mais informações, Project de aplicativo Teams.

Dica

Os fragmentos de código são atualizados para a versão 2 mais recente do SDK do TeamsFx.

Instalar o pacote `@microsoft/teamsfx`

Instale o SDK do TeamsFx para TypeScript ou JavaScript com npm:

npm install @microsoft/teamsfx

Funcionalidades principais do TeamsFx

Classe TeamsFx

A instância de classe TeamsFx acede a todas as definições do TeamsFx a partir das variáveis de ambiente por predefinição. Pode definir valores de configuração personalizados para substituir os valores predefinidos. Para obter mais informações, veja Substituir a configuração para obter detalhes. Ao criar uma instância do TeamsFx, tem de especificar o tipo de identidade.

A lista seguinte fornece os dois tipos diferentes de identidades:

Identidade do Utilizador: representa o utilizador atual do Teams.
Identidade da Aplicação: representa a própria aplicação.

Observação

Os construtores e métodos do TeamsFx não são os mesmos para estes dois tipos de identidade.

Pode saber mais sobre a identidade do utilizador e a identidade da aplicação na secção seguinte:

Identidade do utilizador

Comando	Descrição
`new TeamsFx(IdentityType.User)`	O aplicativo é autenticado como usuário atual do Teams.
`TeamsFx:setSsoToken()`	Identidade do usuário no ambiente node.js (sem navegador).
`TeamsFx:getUserInfo()`	Para obter informações básicas do usuário.
`TeamsFx:login()`	Ele é usado para permitir que o usuário execute o processo de consentimento, se desejar usar o SSO para obter o token de acesso para determinados escopos do OAuth.

Observação

Você pode acessar recursos em nome do usuário atual do Teams.

Identidade da aplicação

Comando	Descrição
`new TeamsFx(IdentityType.App)`	A aplicação é autenticada como uma aplicação. Normalmente, a permissão precisa da aprovação do administrador.
`TeamsFx:getCredential()`	Fornece instâncias de credenciais correspondentes automaticamente ao tipo de identidade.

Observação

Você precisa do consentimento do administrador para recursos.

Credential

As classes de credenciais implementam a TokenCredential interface que é amplamente utilizada nas APIs da biblioteca do Azure concebida para fornecer tokens de acesso para âmbitos específicos. Para obter mais informações sobre classes relacionadas com credenciais e fluxo de autenticação, veja pasta de credenciais.

Há três classes de credenciais para simplificar a autenticação. Eis os cenários correspondentes para cada destino de classe de credenciais:

Identidade do utilizador no ambiente do browser

TeamsUserCredential representa a identidade do usuário atual do Teams. Pela primeira vez, as credenciais do utilizador são autenticadas e, em seguida, o SSO do Teams faz o fluxo Em Nome de De para troca de tokens. O SDK utiliza esta credencial quando escolhe a identidade do utilizador no ambiente do browser.

O código seguinte é um exemplo para criar 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);

As configurações necessárias são initiateLoginEndpoint e clientId encontram-se no tipo TeamsUserCredentialAuthConfig.

Identidade do utilizador no ambiente Node.js

OnBehalfOfUserCredential utiliza o fluxo Em Nome de e requer token SSO do Teams, em cenários de Bot ou Função do Azure. O SDK do TeamsFx utiliza a seguinte credencial quando escolhe a identidade de utilizador no Node.js ambiente.

O código seguinte é um exemplo para criar 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);

As configurações necessárias são authorityHost, tenantId, clientId, clientSecretou certificateContent que são encontradas no tipo OnBehalfOfCredentialAuthConfig.

Identidade da aplicação no ambiente Node.js

AppCredential representa a identidade da aplicação. Pode utilizar a identidade da aplicação quando o utilizador não estiver envolvido, por exemplo, numa tarefa de automatização acionada pelo tempo. O SDK do TeamsFx utiliza a seguinte credencial quando escolhe a identidade da aplicação no Node.js ambiente.

O código seguinte é um exemplo para criar 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);

As configurações necessárias são authorityHost, tenantId, clientId, clientSecretou certificateContent que estão dentro do tipo AppCredentialAuthConfig

Bot SSO

Classes relacionadas ao bot são armazenadas em bot.

TeamsBotSsoPrompt integra-se com a arquitetura de bot. Simplifica o processo de autenticação quando desenvolve a aplicação de bot e quer utilizar o SSO do bot.

O código seguinte é um exemplo para criar 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);

Funções com suporte

O SDK do TeamsFx fornece várias funções para facilitar a configuração de bibliotecas de terceiros. Estão localizados sob a pasta principal.

O Serviço Microsoft Graph:createMicrosoftGraphClient, createMicrosoftGraphClientWithCredentiale MsGraphAuthProvider ajuda a criar uma instância autenticada do Graph.

Observação

createMicrosoftGraphClient a função foi preterida. Recomenda-se que utilize createMicrosoftGraphClientWithCredential , em vez disso, para uma melhor experiência de codificação.
SQL: getTediousConnectionConfig devolve uma configuração de ligação entediante.

Configuração necessária:
- Se quiser utilizar a identidade de utilizador, sqlServerEndpointentão , sqlUsernamee sqlPassword são necessários.
- Se quiser utilizar a identidade MSI, sqlServerEndpointe sqlIdentityId são necessários.
Observação

A getTediousConnectionConfig função foi preterida. Recomenda-se que componha a sua própria configuração Tedious para uma melhor flexibilidade.

Substituir a configuração da classe TeamsFx

Observação

A classe TeamsFx foi preterida. Utilize TeamsUserCredential, OnBehalfOfUserCredentiale AppCredential em vez disso.

Pode transmitir a configuração personalizada ao criar uma nova TeamsFx instância para substituir a configuração predefinida ou definir os campos necessários quando environment variables estiverem em falta.

Para o projeto de separador

Se tiver criado um projeto de separador com o Microsoft Visual Studio Code Toolkit, os seguintes valores de configuração são utilizados a partir de variáveis de ambiente pré-configuradas:

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) // utilizado apenas quando existe uma função de back-end
apiName (REACT_APP_FUNC_NAME) // utilizado apenas quando existe uma função de back-end

Para o projeto de função ou bot do Azure

Se tiver criado o projeto de Função ou bot do Azure com o Visual Studio Code Toolkit, os seguintes valores de configuração são utilizados a partir de variáveis de ambiente pré-configuradas:

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) // utilizado apenas quando existe uma instância do sql
sqlUsername (SQL_USER_NAME) // utilizado apenas quando existe uma instância sql
sqlPassword (SQL_PASSWORD) // utilizado apenas quando existe uma instância do sql
sqlDatabaseName (SQL_DATABASE_NAME) // utilizado apenas quando existe uma instância do SQL
sqlIdentityId (IDENTITY_ID) // utilizado apenas quando existe uma instância do SQL

Tratamento de erros

O tipo básico de resposta de erro da API é ErrorWithCode, que contém o código de erro e a mensagem de erro. Por exemplo, para filtrar um erro específico, você pode usar o seguinte trecho de código:

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

Observação

A classe TeamsFx foi preterida e ErrorWithCode não é recomendada. Em alternativa, pode utilizar 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;
  }
}

Se uma instância de credencial for utilizada noutra biblioteca, como o Microsoft Graph, é possível que um erro seja detetado e transformado.

Cenários do Microsoft Graph

Esta secção fornece vários fragmentos de código para cenários comuns relacionados com o Microsoft Graph. Nestes cenários, o utilizador pode chamar APIs com permissões diferentes no front-end ou back-end.

Permissão de delegado do utilizador no front-end (Utilizar TeamsUserCredential)

Utilizar a graph API na aplicação de separadores

Este fragmento de código mostra-lhe como utilizar TeamsUserCredential e createMicrosoftGraphClientWithCredential obter perfis de utilizador a partir do Microsoft Graph na aplicação de separadores. Também mostra como capturar e resolver um GraphError.

Importe as classes necessárias.

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

Criar TeamsUserCredential instância.

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

const teamsUserCredential = new TeamsUserCredential(authConfig);

Utilize teamsUserCredential.login() para obter o consentimento do utilizador.

// 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

Pode inicializar uma instância do TeamsFx e um cliente de gráficos e obter informações do Microsoft Graph por este cliente.

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

Para obter mais informações sobre o exemplo para utilizar a Graph API na aplicação de separadores, veja Exemplo de aplicação Conector do Graph.

Integração com o Microsoft Graph Toolkit

A biblioteca do Microsoft Graph Toolkit é uma coleção de vários fornecedores de autenticação e componentes de IU com tecnologia microsoft Graph.

O @microsoft/mgt-teamsfx-provider pacote expõe a classe que utiliza TeamsFx a classe para iniciar sessão de utilizadores e adquirir tokens para utilizar com o TeamsFxProvider Microsoft Graph.

Pode instalar os seguintes pacotes necessários:

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

Inicialize o fornecedor no seu 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 teamsfx = new TeamsFx();
const provider = new TeamsFxProvider(teamsfx, scope);
Providers.globalProvider = provider;

Pode utilizar o método para obter o teamsfx.login(scopes) token de acesso necessário.

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

Pode adicionar qualquer componente na sua página HTML ou no seu render() método com o React para utilizar o TeamsFx contexto para aceder ao Microsoft Graph.

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

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

Para obter mais informações sobre o exemplo para inicializar o fornecedor do TeamsFx, veja o exemplo do exportador de contactos.

Permissão de delegado do utilizador no back-end (Utilizar OnBehalfOfUserCredential)

Utilizar a Graph API na Aplicação de bot

Este fragmento de código mostra-lhe como utilizar TeamsBotSsoPrompt para definir uma caixa de diálogo e, em seguida, iniciar sessão para obter um token de acesso.

Inicialize e adicione TeamsBotSsoPrompt ao conjunto de diálogo.

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

Inicie a caixa de diálogo e inicie sessão.

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

Para obter mais informações sobre o exemplo para utilizar a graph API na aplicação de bot, veja exemplo bot-sso.

Utilizar a Graph API na Extensão de Mensagens

O fragmento de código seguinte mostra como substituir handleTeamsMessagingExtensionQuery que se estende a partir de TeamsActivityHandlere utilização handleMessageExtensionQueryWithSSO fornecida pelo SDK do TeamsFx para iniciar sessão para obter um token de acesso:


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

Para obter mais informações sobre o exemplo para utilizar a graph API na extensão de mensagens, veja message-extension-sso-sample.

Utilizar a Graph API no Bot de Comandos

Este fragmento de código mostra-lhe como implementar TeamsFxBotSsoCommandHandler o bot de comando para chamar a API da 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.";
    }
  }
 }

Para obter mais informações sobre como implementar o processador de comandos SSO no bot de comandos, veja Adicionar início de sessão único à aplicação Teams. E existe um projeto de exemplo command-bot-with-sso , que pode experimentar o bot de comandos SSO.

Chamar a Função do Azure na aplicação de separadores: Fluxo Em Nome de

Este fragmento de código mostra-lhe como utilizar CreateApiClient ou axios a biblioteca para chamar a Função do Azure e como chamar a Graph API na Função do Azure para obter perfis de utilizador.

Pode utilizar CreateApiClient o sdk do TeamsFx para chamar a Função do 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;
}

Também pode utilizar axios a biblioteca para chamar a Função do 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;
}

Chame a Graph API na Função do Azure em nome do utilizador em resposta.


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

Para obter mais informações sobre o exemplo para utilizar a graph API na aplicação de bot, veja hello-world-tab-with-back-end sample (Exemplo hello-world-tab-with-back-end).

Permissão da aplicação no back-end
Utilizar a autenticação baseada em certificados na Função do Azure

Este fragmento de código mostra-lhe como utilizar a permissão de aplicação baseada em certificado para obter o token que pode ser utilizado para chamar a Graph API.
1. Pode inicializar o appAuthConfig ao fornecer um 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. Pode utilizar AppCredential para obter o token.
```
const appCredential = new AppCredential(appAuthConfig);
const token = appCredential.getToken();    
```
Utilizar a autenticação secreta do cliente na Função do Azure

Este fragmento de código mostra-lhe como utilizar a permissão da aplicação secreta do cliente para obter o token utilizado para chamar a Graph API.
1. Pode inicializar o authConfig ao fornecer um 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. Pode utilizar o authConfig para obter o token.
```
const appCredential = new AppCredential(appAuthConfig);
const token = appCredential.getToken();    
```
Para obter mais informações sobre o exemplo para utilizar a graph API na aplicação de bot, veja o exemplo hello-world-tab-with-back-end.

Outros cenários

Esta secção fornece vários fragmentos de código para outros cenários relacionados com o Microsoft Graph. Pode criar um cliente de API no Bot ou na Função do Azure e aceder à base de dados SQL na Função do Azure.

Criar um cliente de API para chamar a API existente no Bot ou na Função do Azure

Este fragmento de código mostra-lhe como chamar uma API existente no bot por 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");

Aceder à base de dados SQL na Função do Azure

Utilize tedious a biblioteca para aceder ao SQL e utilizar DefaultTediousConnectionConfiguration que gere a autenticação. Também pode compor a configuração de ligação de outras bibliotecas SQL com base no resultado de sqlConnectionConfig.getConfig().

Defina a configuração da ligação.

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

Ligue-se à sua base de dados.
```
const connection = new Connection(config);
connection.on("connect", (error) => {
if (error) {
 console.log(error);
 }
});  
```
Observação

A getTediousConnectionConfig função foi preterida, recomenda-se que componha a sua própria configuração entediante para uma melhor flexibilidade.

Para obter mais informações sobre o exemplo para aceder à base de dados SQL na Função do Azure, veja share-now sample (exemplo de partilha agora).

Personalização avançada

Configurar log

Você pode definir o nível de log do cliente e redirecionar as saídas ao usar essa biblioteca.

Observação

Os registos estão desativados por predefinição. Pode ativá-los ao definir o nível de registo.

Habilitar o log definindo o nível de log

Quando define o nível de registo, o Registo fica ativado. Imprime as informações de registo na consola por predefinição.

Defina o nível de log usando o seguinte trecho de código:

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

Observação

Você pode redirecionar a saída do log definindo o agente personalizado ou a função de log.

Redirecionar definindo o agente personalizado

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

Redirecionar definindo a função de log personalizada

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

Observação

As funções de registo não produzem efeito se definir um logger personalizado.

Atualizar para a versão mais recente do SDK

Se estiver a utilizar a versão do SDK que tem loadConfiguration()o , pode executar os seguintes passos para atualizar para a versão mais recente do SDK:

Em vez de chamar loadConfiguration(), utilize as classes de configuração de autenticação específicas para personalizar as definições para cada tipo de credencial. Por exemplo, utilize AppCredentialAuthConfig para AppCredential, OnBehalfOfUserCredentialAuthConfig para OnBehalfOfUserCredentiale TeamsUserCredentialAuthConfig para TeamsUserCredential.
Substitua new TeamsUserCredential() por new TeamsUserCredential(authConfig).
Substitua new M365TenantCredential() por new AppCredential(authConfig).
Substitua new OnBehalfOfUserCredential(ssoToken) por new OnBehalfOfUserCredential(authConfig).

Compartilhar via

TeamsFx SDK

Pré-requisitos

Introdução

Instalar o pacote `@microsoft/teamsfx`

Funcionalidades principais do TeamsFx

Classe TeamsFx

Credential

Bot SSO

Funções com suporte

Substituir a configuração da classe TeamsFx

Tratamento de erros

Cenários do Microsoft Graph

Outros cenários

Personalização avançada

Configurar log

Habilitar o log definindo o nível de log

Redirecionar definindo o agente personalizado

Redirecionar definindo a função de log personalizada

Atualizar para a versão mais recente do SDK

Confira também

Recursos adicionais

Compartilhar via

TeamsFx SDK

Pré-requisitos

Introdução

Instalar o pacote @microsoft/teamsfx

Funcionalidades principais do TeamsFx

Classe TeamsFx

Credential

Bot SSO

Funções com suporte

Substituir a configuração da classe TeamsFx

Tratamento de erros

Cenários do Microsoft Graph

Outros cenários

Personalização avançada

Configurar log

Habilitar o log definindo o nível de log

Redirecionar definindo o agente personalizado

Redirecionar definindo a função de log personalizada

Atualizar para a versão mais recente do SDK

Confira também

Recursos adicionais

Instalar o pacote `@microsoft/teamsfx`