TeamsFx SDK

O TeamsFx reduz suas tarefas utilizando o logon único (SSO) do Microsoft Teams e acessando recursos de nuvem com instruções de linha única e configuração zero. Você pode usar o SDK do TeamsFx em ambientes de navegador e Node.js. As principais funcionalidades do TeamsFx estão acessíveis em ambientes de cliente e servidor. Você pode escrever código de autenticação de usuário para:

• Guia Teams
• Bot do Teams
• Função do Azure

Pré-requisitos

Instale as seguintes ferramentas e configure seu ambiente de desenvolvimento:

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

Você deve ter conhecimento prático de:

• Código-fonte
• Pacote (NPM)
• Documentação de referência da API
• Exemplos

Introdução

O SDK do TeamsFx é pré-configurado no projeto scaffolded usando a CLI do Microsoft 365 Agents Toolkit (anteriormente conhecida como TeamsFx Toolkit ou CLI). Para obter mais informações, consulte Projeto de aplicativo do Teams.

Instalar o pacote

Instale @microsoft/m365agentstoolkit-cli de e execute atk -h para marcar todos os comandos npm disponíveis:

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

Principais funcionalidades 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 Substituir configuraçã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.

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

Credencial

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

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:

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

const credential = new TeamsUserCredential(authConfig);

const oboAuthConfig: OnBehalfOfCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};

const oboCredential = new OnBehalfOfUserCredential(ssoToken, oboAuthConfig);

const appAuthConfig: AppCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};
const appCredential = new AppCredential(appAuthConfig);

Bot SSO

As classes relacionadas ao Bot são armazenadas na pasta Bot.

TeamsBotSsoPrompt integra-se com a 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 suportadas

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

• Microsoft Graph Service: createMicrosoftGraphClient, createMicrosoftGraphClientWithCredentiale MsGraphAuthProvider ajuda para criar uma instância autenticada do Graph.

• SQL: O retorna uma configuração de conexão tediosa getTediousConnectionConfig .

  Configuração necessária:

  • Se você quiser usar a identidade do usuário, então sqlServerEndpoint, sqlUsername, e sqlPassword são necessários.
  • Se você quiser usar a identidade MSI, então sqlServerEndpoint e sqlIdentityId são necessários.

Substituir a configuração para a classe TeamsFx

Você pode passar a configuração personalizada ao criar uma nova TeamsFx instância para substituir a configuração padrão ou definir campos obrigatórios quando environment variables estiverem ausentes.

Gestão de erros

O tipo básico de resposta a erros da API é ErrorWithCode, que contém o código e a mensagem de erro. Por exemplo, para filtrar erros específicos, pode utilizar o seguinte fragmento:

try {
  const atk = new TeamsFx();
  await teamsfx.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

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

  const credential = new TeamsUserCredential(authConfig);  
  await credential.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

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

Cenários do Microsoft Graph

Esta secção fornece vários fragmentos de código para cenários comuns relacionados com o Microsoft Graph. Nesses cenários, o usuário pode chamar APIs usando permissões diferentes no frontend ou no backend.

• Permissão de delegado de usuário no frontend (Usar TeamsUserCredential)

  Utilizar a API de gráfico na aplicação de separador

  Este fragmento de código mostra-lhe como utilizar TeamsUserCredential e createMicrosoftGraphClientWithCredential obter perfis de utilizador do Microsoft Graph na aplicação de separadores. Ele também mostra como pegar e resolve um GraphError.

  1. Importe as turmas necessárias.

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

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

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

  4. Pode inicializar uma instância do TeamsFx e um cliente de gráfico e obter informações do Microsoft Graph através deste 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 guia, consulte Exemplo de aplicativo Conector do Graph.

  Integração com o Kit de ferramentas do Microsoft Graph

  A biblioteca 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 usa TeamsFx a classe para entrar em usuários e adquirir tokens para usar com o TeamsFxProvider Microsoft Graph.

  1. Você pode instalar os seguintes pacotes necessários:

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

  2. Inicialize o provedor dentro do 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 atk = new TeamsFx();
     const provider = new TeamsFxProvider(teamsfx, scope);
     Providers.globalProvider = provider;   
     

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

  4. Pode adicionar qualquer componente na sua página HTML ou no seu render() método com React 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 provedor TeamsFx, consulte o exemplo de exportador de contatos.

• Permissão de delegado do usuário em back-end (Uso OnBehalfOfUserCredential)

  Utilizar API do Graph na Aplicação 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.

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

  2. 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 como usar o API do Graph em um aplicativo de bot, consulte o exemplo de bot-sso.

  Utilizar API do Graph numa extensão de mensagem

  O trecho de código a seguir demonstra como substituir handleTeamsMessagingExtensionQueryo , que se estende de TeamsActivityHandler. Ele usa handleMessageExtensionQueryWithSSO fornecido pelo SDK do TeamsFx para fazer login e 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 como usar o API do Graph em uma extensão de mensagem, consulte o exemplo message-extension-sso.

  Utilizar API do Graph no Command Bot

  Este trecho de código demonstra como implementar TeamsFxBotSsoCommandHandler para um bot de comando 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 using `graph` instance to get user profile information
      const me = await graphClient.api("/me").get();
  
      if (me) {
        // Bot will send the user profile info to user
        return `Your command is '${message.text}' and you're logged in as ${me.displayName}`;
      } else {
        return "Could not retrieve profile information from Microsoft Graph.";
      }
    }
   }    
  
  

  Para obter mais informações sobre como implementar um manipulador de comando SSO em um bot de comando, consulte Adicionar logon único ao aplicativo Teams. Há também um projeto de exemplo command-bot-with-sso que você pode tentar para o bot de comando SSO.

  Função de Azure de chamadas na aplicação de separadores: fluxo em nome de

  Este trecho de código demonstra como usar CreateApiClient ou a axios biblioteca para chamar uma Função Azure e como chamar a API do Graph em uma Função Azure para obter perfis de usuário.

  1. Você pode usar CreateApiClient fornecido pelo SDK do TeamsFx para chamar uma função 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 a axios biblioteca para chamar uma Função Azure.

     async function callFunction() {
       const authConfig: TeamsUserCredentialAuthConfig = {
         clientId: process.env.REACT_APP_CLIENT_ID,
         initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
       };
       const teamsUserCredential = new TeamsUserCredential(authConfig);
       const accessToken = await teamsUserCredential.getToken(""); // Get SSO token 
       const endpoint = "https://YOUR_API_ENDPOINT";
       const response = await axios.default.get(endpoint + "/api/" + functionName, {
         headers: {
           authorization: "Bearer " + accessToken.token,
         },
       });
       return response.data;
     }    
     
     

  2. Chame o API do Graph em uma função Azure 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 como usar o API do Graph em um aplicativo de bot, consulte o exemplo hello-world-tab-with-backend.

• Permissão do aplicativo no back-end

  Utilizar autenticação baseada em certificado no Azure Função

  Este trecho de código demonstra como usar a permissão de aplicativo baseada em certificado para obter o token que pode ser usado para chamar o API do Graph.

  1. Você pode inicializar o appAuthConfig fornecendo um PEM-encoded key certificatearquivo .

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

  Usar a autenticação de segredo do cliente na função do Azure

  Este trecho de código demonstra como usar a permissão do aplicativo secreto do cliente para obter o token usado para chamar a API do Graph.

  1. Você pode inicializar fornecendo authConfig um client secretarquivo .

     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 como usar a API do Graph em um aplicativo de bot, consulte o exemplo hello-world-tab-with-backend.

Outros cenários

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

// Create an API Key auth provider. In addition to ApiKeyProvider, the following auth providers are also available:
// BearerTokenAuthProvider, BasicAuthProvider, CertificateAuthProvider.
const authProvider = new ApiKeyProvider("YOUR_API_KEY_NAME",
  "YOUR_API_KEY_VALUE",
  ApiKeyLocation.Header
);

// Create an API client using the above auth provider.
// You can also implement the AuthProvider interface and use it here.
const apiClient = createApiClient(
  "YOUR_API_ENDPOINT",
  authProvider
);

// Send a GET request to "RELATIVE_API_PATH", "/api/apiname" for example.
const response = await apiClient.get("RELATIVE_API_PATH");  

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.

Habilitar o log definindo o nível de log

Quando você define o nível de log, o registro em log é habilitado. Ele imprime informações de log no console por padrão.

Defina o nível de log usando o seguinte trecho:

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

Redirecione definindo o agente personalizado

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

Redirecione definindo a função de log personalizada

setLogLevel(LogLevel.Info);
// Only log error messages to Application Insights in bot application.
setLogFunction((level: LogLevel, message: string) => {
  if (level === LogLevel.Error) {
    this.telemetryClient.trackTrace({
      message: message,
      severityLevel: Severity.Error,
    });
  }
});

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:

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

Confira também

• Visão geral do Kit de Ferramentas de Agentes do Microsoft 365
• CLI do Kit de Ferramentas de Agentes do Microsoft 365
• Galeria de exemplos do Microsoft TeamsFx.
• Adicionar logon único ao aplicativo Teams