Пакет SDK TeamsFx

TeamsFx помогает сократить число задач, используя единый вход Microsoft Teams и доступ к облачным ресурсам до инструкций в одной строке с нулевой конфигурацией. Пакет SDK TeamsFx можно использовать в браузере и Node.js средах. Доступ к основным функциям TeamsFx можно получить в клиентских и серверных средах. Код проверки подлинности пользователя можно написать для:

• Вкладка Teams
• Бот Teams
• Функция Azure

Предварительные условия

Необходимо установить следующие средства и настроить среду разработки:

Дополнительные сведения о совместимости версий Node.js см. в разделе Предварительные требования для создания приложения Teams с помощью Visual Studio Code.

Вы должны обладать рабочими знаниями о:

• Исходный код
• Пакет (NPM)
• Справочная документация по API
• Примеры

Начало работы

Пакет SDK TeamsFx предварительно настроен в проекте со сформированными шаблонами с помощью набора средств TeamsFx или CLI. Дополнительные сведения см. в проекте приложения Teams.

Установка пакета @microsoft/teamsfx

Установите пакет SDK TeamsFx для TypeScript или JavaScript с помощью npm.

npm install @microsoft/teamsfx

Основные функции TeamsFx

Класс TeamsFx

Экземпляр класса TeamsFx по умолчанию обращается ко всем параметрам TeamsFx из переменных среды. Вы можете задать настраиваемые значения конфигурации, чтобы переопределить значения по умолчанию. Дополнительные сведения см. в разделе Конфигурация переопределения . При создании экземпляра TeamsFx необходимо указать тип удостоверения.

В следующем списке представлены два разных типа удостоверений:

• Удостоверение пользователя. Представляет текущего пользователя Teams.

• Удостоверение приложения. Представляет само приложение.

  Примечание.

  Конструкторы и методы TeamsFx не совпадают для этих двух типов удостоверений.

Дополнительные сведения об удостоверении пользователя и удостоверении приложения см. в следующем разделе:

Credential

Классы учетных TokenCredential данных реализуют интерфейс, который широко используется в API библиотеки Azure, предназначенных для предоставления маркеров доступа для определенных областей. Дополнительные сведения о классах, связанных с учетными данными и потоком проверки подлинности, см. в разделе Папка учетных данных.

Есть три класса учетных данных для упрощения проверки подлинности. Ниже приведены соответствующие сценарии для каждого целевого класса учетных данных:

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

SSO бота

Классы, связанные с ботом, хранятся в папке bot folder.

TeamsBotSsoPrompt интегрируется с платформой бота. Это упрощает процесс проверки подлинности при разработке приложения бота и использовании единого входа бота.

Следующий код является примером для создания 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);

Поддерживаемые функции

Пакет SDK TeamsFx предоставляет несколько функций для упрощения настройки сторонних библиотек. Они находятся в основной папке.

• Служба Microsoft Graph:createMicrosoftGraphClient , createMicrosoftGraphClientWithCredentialи MsGraphAuthProvider помогает создать экземпляр Graph с проверкой подлинности.

  Примечание.

  createMicrosoftGraphClient функция устарела. Вместо этого рекомендуется использовать createMicrosoftGraphClientWithCredential для более эффективного программирования.

• SQL: getTediousConnectionConfig возвращает оголительную конфигурацию подключения.

  Требуемая конфигурация

  • Если вы хотите использовать удостоверение пользователя, требуются sqlServerEndpoint, sqlUsernameи sqlPassword .
  • Если вы хотите использовать удостоверение MSI, то sqlServerEndpointи sqlIdentityId являются обязательными.

  Примечание.

  Функция getTediousConnectionConfig устарела. Рекомендуется создавать собственную конфигурацию для повышения гибкости.

Конфигурация переопределения для класса TeamsFx

Вы можете передать настраиваемую конфигурацию при создании нового TeamsFx экземпляра, чтобы переопределить конфигурацию по умолчанию или задать обязательные поля, если environment variables они отсутствуют.

Обработка ошибок

Базовый тип ответа на ошибку API — ErrorWithCode, который содержит код ошибки и сообщение об ошибке. Например, чтобы отфильтровать определенную ошибку, можно использовать следующий фрагмент кода:

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

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

Если экземпляр учетных данных используется в другой библиотеке, например Microsoft Graph, возможно, ошибка перехватывается и преобразуется.

Сценарии Microsoft Graph

В этом разделе представлено несколько фрагментов кода для распространенных сценариев, связанных с Microsoft Graph. В таких сценариях пользователь может вызывать API с разными разрешениями во интерфейсе или серверной части.

• Пользователь делегировать разрешение во интерфейсном интерфейсе (используйте TeamsUserCredential)

  Использование API graph в приложении tab

  В этом фрагменте кода показано, как использовать TeamsUserCredential и createMicrosoftGraphClientWithCredential получать профили пользователей из Microsoft Graph в приложении вкладки. В нем также показано, как перехватывать и разрешать .GraphError

  1. Импорт необходимых классов.

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

  2. Создание экземпляра TeamsUserCredential .

     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. Используйте teamsUserCredential.login() для получения согласия пользователя.

     // 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. Вы можете инициализировать экземпляр TeamsFx и клиент graph и получать сведения из Microsoft Graph этим клиентом.

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

  Дополнительные сведения об использовании API Graph в приложении tab см. в разделе Пример приложения Graph Conector.

  Интеграция с Microsoft Graph Toolkit

  Библиотека Microsoft Graph Toolkit — это коллекция различных поставщиков проверки подлинности и компонентов пользовательского интерфейса на платформе Microsoft Graph.

  Пакет @microsoft/mgt-teamsfx-provider предоставляет TeamsFxProvider класс, который использует TeamsFx класс для входа пользователей и получения маркеров для использования с Microsoft Graph.

  1. Вы можете установить следующие необходимые пакеты:

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

  2. Инициализация поставщика внутри компонента.

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

  3. Метод можно использовать для получения необходимого teamsfx.login(scopes) маркера доступа.

     // 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. Вы можете добавить любой компонент на HTML-странице или в render() метод с помощью React, чтобы использовать TeamsFx контекст для доступа к Microsoft Graph.

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

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

  Дополнительные сведения об инициализации поставщика TeamsFx см. в примере экспорта контактов.

• Делегирование пользователем разрешений во внутренней части (используйте OnBehalfOfUserCredential)

  Использование API Graph в приложении бота

  В этом фрагменте кода показано, как настроить TeamsBotSsoPrompt диалоговое окно, а затем выполнить вход для получения маркера доступа.

  1. Инициализация и добавление TeamsBotSsoPrompt в набор диалоговых окон.

     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. Запустите диалоговое окно и выполните вход.

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

  Дополнительные сведения об использовании API graph в приложении бота см. в разделе пример bot-sso.

  Использование API Graph в расширении сообщений

  В следующем фрагменте кода показано, как переопределить handleTeamsMessagingExtensionQuery , который расширяется от TeamsActivityHandler, и использовать handleMessageExtensionQueryWithSSO предоставленный TeamsFx пакет SDK для входа для получения маркера доступа:

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

  Дополнительные сведения об использовании API graph в расширении сообщений см. в разделе message-extension-sso-sample.

  Использование API Graph в командном боте

  В этом фрагменте кода показано, как реализовать для TeamsFxBotSsoCommandHandler командного бота вызов Microsoft API.

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

  Дополнительные сведения о реализации обработчика команд единого входа в боте команд см. в статье Добавление единого входа в приложение Teams. Существует пример проекта command-bot-with-sso , в который можно попробовать бот единого входа.

  Вызов функции Azure в приложении вкладки: поток On-Behalf-Of

  В этом фрагменте кода показано, как использовать CreateApiClient или axios библиотеку для вызова функции Azure, а также как вызывать API Graph в Функции Azure для получения профилей пользователей.

  1. Для вызова функции Azure можно использовать CreateApiClient пакет sdk TeamsFx:

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

     Вы также можете использовать axios библиотеку для вызова функции 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. Вызов API Graph в функции Azure от имени пользователя в ответ.

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

  Дополнительные сведения об использовании API graph в приложении бота см. в разделе пример hello-world-tab-with-backend.

• Разрешение приложения в серверной части

  Использование проверки подлинности на основе сертификатов в Функции Azure

  В этом фрагменте кода показано, как использовать разрешение приложения на основе сертификата для получения маркера, который можно использовать для вызова API Graph.

  1. Можно инициализировать , appAuthConfig указав 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. Вы можете использовать AppCredential для получения маркера.

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

  Использование проверки подлинности секрета клиента в функции Azure

  В этом фрагменте кода показано, как использовать разрешение секретного приложения клиента для получения маркера, используемого для вызова API Graph.

  1. Можно инициализировать , authConfig указав 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. Для получения маркера authConfig можно использовать .

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

  Дополнительные сведения об использовании API graph в приложении бота см. в примере hello-world-tab-with-backend.

Прочие сценарии

В этом разделе представлено несколько фрагментов кода для других сценариев, связанных с Microsoft Graph. Вы можете создать клиент API в Bot или Функции Azure и получить доступ к базе данных SQL в Функции Azure.

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

Дополнительная настройка

Настройка журнала

При использовании этой библиотеки можно настроить уровень журнала клиента и перенаправить выходные данные.

Включите журнал, установив уровень ведения журнала

При настройке уровня журнала включено ведение журнала. По умолчанию в консоли выводится информация журнала.

Установите уровень журнала, используя следующий фрагмент кода:

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

Перенаправление путем настройки пользовательской записи журнала

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

Перенаправление путем настройки пользовательской функции журнала

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

Обновление до последней версии пакета SDK

Если вы используете версию пакета SDK loadConfiguration()с , вы можете выполнить следующие действия для обновления до последней версии пакета SDK:

1. Вместо вызова loadConfiguration()используйте определенные классы конфигурации проверки подлинности для настройки параметров для каждого типа учетных данных. Например, используйте AppCredentialAuthConfig для AppCredential, OnBehalfOfUserCredentialAuthConfig для OnBehalfOfUserCredentialи TeamsUserCredentialAuthConfig для TeamsUserCredential.
2. Замените new TeamsUserCredential() на new TeamsUserCredential(authConfig).
3. Замените new M365TenantCredential() на new AppCredential(authConfig).
4. Замените new OnBehalfOfUserCredential(ssoToken) на new OnBehalfOfUserCredential(authConfig).

См. также

• Обзор набора средств Teams
• CLI набора средств Teams
• Образец галереи Microsoft TeamsFx.
• Добавление функциональности единого входа в приложение Teams