TeamsFx SDK

Artigo
04/16/2023

O TeamsFx ajuda a reduzir suas tarefas usando o SSO (logon único) do Microsoft Teams e acessando recursos de nuvem até instruções de linha única sem configuração. Você pode usar o SDK do TeamsFx nos ambientes de navegador e Node.js. As funcionalidades principais do TeamsFx podem ser acessadas em ambientes de cliente e servidor. Você pode escrever o código de autenticação do usuário para:

Guia Teams
Bot do Teams
Função do Azure

Pré-requisitos

Você precisa instalar as seguintes ferramentas e configurar seu ambiente de desenvolvimento:

	Instalar	Para usar...
	Visual Studio Code	Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Use a versão 1.55 ou posterior.
	Kit de ferramentas do Teams	Uma extensão do Microsoft Visual Studio Code que cria um scaffolding de projeto para seu aplicativo. Use a versão 4.0.0.
	Node.js	Ambiente de runtime do JavaScript de back-end. Para obter mais informações, consulte Node.js tabela de compatibilidade de versão para o tipo de projeto.
	Microsoft Teams	Microsoft Teams para colaborar com todos com quem você trabalha por meio de aplicativos para chat, reuniões, chamadas e tudo em um só lugar.
	Microsoft Edge (recomendado) ou Google Chrome	Um navegador com ferramentas de desenvolvedor.

Para obter mais informações sobre Node.js compatibilidade com a versão, consulte Pré-requisitos para criar seu aplicativo teams usando Visual Studio Code.

Observação

Se o projeto tiver instalado botbuilderpacotes relacionados como dependências, verifique se eles são da mesma versão.

Você deve ter conhecimento de trabalho de:

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 snippets de código são atualizados para o SDK do TeamsFx versão 2 mais recente.

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 da classe TeamsFx acessa todas as configurações do TeamsFx das variáveis de ambiente por padrão. Você pode definir valores de configuração personalizados para substituir os valores padrão. Para obter mais informações, consulte a configuração de substituição para obter detalhes. Ao criar uma instância do TeamsFx, você precisa especificar o tipo de identidade.

A lista a seguir fornece os dois tipos diferentes de identidades:

Identidade do usuário: representa o usuário atual do Teams.
Identidade do aplicativo: representa o próprio aplicativo.

Observação

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

Você pode saber mais sobre identidade do usuário e identidade do aplicativo na seção a seguir:

Identidade do usuário

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 do aplicativo

Comando	Descrição
`new TeamsFx(IdentityType.App)`	O aplicativo é autenticado como um aplicativo. A permissão geralmente precisa da aprovação do administrador.
`TeamsFx:getCredential()`	Ele fornece instâncias de credencial correspondentes automaticamente ao tipo de identidade.

Observação

Você precisa do consentimento do administrador para recursos.

Credential

As classes de credencial implementam a TokenCredential interface amplamente usada em APIs de biblioteca do Azure projetadas para fornecer tokens de acesso para escopos específicos. Para obter mais informações sobre classes relacionadas a credenciais e fluxo de auth, confira pasta de credencial.

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

Identidade do usuário no ambiente do navegador

TeamsUserCredential representa a identidade do usuário atual do Teams. Pela primeira vez, as credenciais do usuário são autenticadas, em seguida, o SSO do Teams faz o fluxo On-Behalf-Of para troca de tokens. O SDK usa essa credencial quando você escolhe a identidade do usuário no ambiente do navegador.

O código a seguir é 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 encontradas dentro do tipo TeamsUserCredentialAuthConfig.

Identidade do usuário no ambiente Node.js

OnBehalfOfUserCredential usa o fluxo On-Behalf-Of e exige o token SSO do Teams, em cenários de função ou bot do Azure. O SDK do TeamsFx usa a credencial a seguir ao escolher a identidade do usuário em Node.js ambiente.

O código a seguir é 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 dentro do tipo OnBehalfOfCredentialAuthConfig.

Identidade do aplicativo no ambiente Node.js

AppCredential representa a identidade do aplicativo. Você pode usar a identidade do aplicativo quando o usuário não estiver envolvido, por exemplo, em um trabalho de automação com gatilho de tempo. O SDK do TeamsFx usa a credencial a seguir ao escolher a identidade do aplicativo em Node.js ambiente.

O código a seguir é 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 à estrutura do bot. Ele simplifica o processo de autenticação quando você desenvolve o aplicativo bot e deseja usar o SSO do bot.

O código a seguir é 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. Eles estão localizados em pasta principal.

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

Observação

createMicrosoftGraphClient a função foi preterida. É recomendável que você use createMicrosoftGraphClientWithCredential , em vez disso, para uma melhor experiência de codificação.
SQL: o getTediousConnectionConfig retorna uma configuração de conexão tediosa.

Configuração necessária:
- Se você quiser usar a identidade do usuário, então sqlServerEndpoint, sqlUsernamee sqlPassword são necessários.
- Se você quiser usar a identidade MSI, então sqlServerEndpointe sqlIdentityId são necessários.
Observação

A getTediousConnectionConfig função foi preterida. É recomendável que você componha sua própria configuração tediosa para obter uma melhor flexibilidade.

Configuração de substituição para a classe TeamsFx

Observação

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

Você pode passar uma configuração personalizada ao criar uma nova TeamsFx instância para substituir a configuração padrão ou definir campos necessários quando environment variables estiver ausente.

Para projeto de guia

Se você criou um projeto de guia usando o Microsoft Visual Studio Code Toolkit, os seguintes valores de configuração serão usados 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) // usado somente quando há uma função de back-end
apiName (REACT_APP_FUNC_NAME) // usado somente quando há uma função de back-end

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

Se você criou o projeto do Azure Function ou bot usando Visual Studio Code Toolkit, os seguintes valores de configuração serão usados 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) // usado somente quando há uma instância sql
sqlUsername (SQL_USER_NAME) // usado somente quando há uma instância sql
sqlPassword (SQL_PASSWORD) // usado somente quando há uma instância sql
sqlDatabaseName (SQL_DATABASE_NAME) // usado somente quando há uma instância SQL
sqlIdentityId (IDENTITY_ID) // usado somente quando há uma instância SQL

Tratamento de erros

O tipo básico de resposta de erro da API é ErrorWithCode, que contém código de erro e 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 vez disso, você pode usar 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 usada em outra biblioteca, como o Microsoft Graph, é possível que um erro seja capturado e transformado.

Cenários do Microsoft Graph

Esta seção fornece vários snippets de código para cenários comuns relacionados ao Microsoft Graph. Nesses cenários, o usuário pode chamar APIs usando permissões diferentes no front-end ou no back-end.

Permissão de delegado de usuário no front-end (Usar TeamsUserCredential)

Usar a API do grafo no aplicativo de guias

Este snippet de código mostra como usar TeamsUserCredential e createMicrosoftGraphClientWithCredential obter perfis de usuário do Microsoft Graph no aplicativo de guias. Ele também mostra como capturar e resolve 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);

Use teamsUserCredential.login() para obter o consentimento do usuário.

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

Você pode inicializar uma instância do TeamsFx e um cliente de grafo e obter informações do Microsoft Graph por esse 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 usar API do Graph no aplicativo de guias, consulte Exemplo do aplicativo Conector do Graph.

Integração com o Microsoft Graph Toolkit

A biblioteca do Kit de Ferramentas do Microsoft Graph é uma coleção de vários provedores de autenticação e componentes da interface do usuário alimentados pelo Microsoft Graph.

O @microsoft/mgt-teamsfx-provider pacote expõe a classe que usa classe para entrar usuários TeamsFx e adquirir tokens a serem usados com o TeamsFxProvider Microsoft Graph.

Você pode instalar os seguintes pacotes necessários:

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

Inicialize o provedor dentro de 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;

Você pode usar 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);

Você pode adicionar qualquer componente em sua página HTML ou em seu render() método com React para usar o contexto para acessar o TeamsFx 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 provedor teamsFx, consulte o exemplo de exportador de contatos.

Permissão de delegado de usuário no back-end (Usar OnBehalfOfUserCredential)

Usar API do Graph no aplicativo bot

Este snippet de código mostra como usar TeamsBotSsoPrompt para definir uma caixa de diálogo e, em seguida, entrar para obter um token de acesso.

Inicializar e adicionar TeamsBotSsoPrompt ao conjunto de caixas 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 entre.

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 usar a API de grafo no aplicativo bot, consulte exemplo de bot-sso.

Usar API do Graph na Extensão de Mensagem

O snippet de código a seguir mostra como substituir handleTeamsMessagingExtensionQuery o que se estende do e o uso handleMessageExtensionQueryWithSSO fornecido pelo SDK do TeamsFx para entrar para obter um token de TeamsActivityHandleracesso:


 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 usar a API de grafo na extensão de mensagem, consulte message-extension-sso-sample.

Usar API do Graph no Bot de Comando

Este snippet de código mostra 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 manipulador de comandoSO no bot de comando, confira adicionar logon único ao aplicativo teams. E há um projeto de exemplo command-bot-with-sso , que você pode tentar o bot de comando SSO.

Chamar a Função do Azure no aplicativo de guia: em nome do fluxo

Este snippet de código mostra como usar CreateApiClient ou axios biblioteca para chamar o Azure Function e como chamar API do Graph no Azure Function para obter perfis de usuário.

Você pode usar CreateApiClient o sdk fornecido pelo 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;
}

Você também pode usar 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 API do Graph no Azure Function em nome do usuário 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 usar a API de grafo no aplicativo bot, confira exemplo hello-world-tab-with-back-end.

Permissão do aplicativo no back-end
Usar autenticação baseada em certificado na Função do Azure

Este snippet de código mostra como usar a permissão de aplicativo baseada em certificado para obter o token que pode ser usado para chamar API do Graph.
1. Você pode inicializar o appAuthConfig fornecendo 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. Você pode usar AppCredential para obter o token.
```
const appCredential = new AppCredential(appAuthConfig);
const token = appCredential.getToken();    
```
Usar a autenticação de segredo do cliente no Azure Function

Este snippet de código mostra como usar a permissão do aplicativo segredo do cliente para obter o token usado para chamar API do Graph.
1. Você pode inicializar o authConfig fornecendo 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. Você pode usar o authConfig para obter o token.
```
const appCredential = new AppCredential(appAuthConfig);
const token = appCredential.getToken();    
```
Para obter mais informações sobre o exemplo para usar a API de grafo no aplicativo bot, consulte o exemplo hello-world-tab-with-back-end.

Outros cenários

Esta seção fornece vários snippets de código para outros cenários relacionados ao Microsoft Graph. Você pode criar um cliente de API no Bot ou no Azure Function e acessar o banco de dados SQL no Azure Function.

Criar cliente de API para chamar a API existente no Bot ou no Azure Function

Este snippet de código mostra 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");

Acessar banco de dados SQL no Azure Function

Use tedious a biblioteca para acessar o SQL e usar DefaultTediousConnectionConfiguration isso gerencia a autenticação. Você também pode compor a configuração de conexão de outras bibliotecas SQL com base no resultado de sqlConnectionConfig.getConfig().

Defina a configuração de conexã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");

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

A getTediousConnectionConfig função foi preterida, é recomendável que você componha sua própria configuração tediosa para obter melhor flexibilidade.

Para obter mais informações sobre o exemplo para acessar o banco de dados SQL no Azure Function, consulte exemplo de share-now.

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 logs são desativados por padrão, você pode ativá-los definindo o nível de log.

Habilitar o log definindo o nível de log

Quando você define o nível do log, o registro em log fica habilitado. Ele imprime informações de log para console por padrã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 log não entrarão em vigor se você definir um madeireiro personalizado.

Atualizar para a versão mais recente do SDK

Se você estiver usando a versão do SDK que tem loadConfiguration(), poderá executar as seguintes etapas para atualizar para a versão mais recente do SDK:

Em vez de chamar loadConfiguration(), use as classes de configuração de auth específicas para personalizar as configurações para cada tipo de credencial. Por exemplo, use 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).

Share 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

Configuração de substituição para a 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

Comentários

Recursos adicionais

Share 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

Configuração de substituição para a 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

Comentários

Recursos adicionais

Instalar o pacote `@microsoft/teamsfx`