TeamsFx SDK

Важно

Корпорация Майкрософт больше не поддерживает пакет SDK TeamsFx для создания расширений Microsoft 365 Copilot, агентов Microsoft 365 или сценариев современных приложений Teams. Пакет SDK в настоящее время находится в режиме устаревания и будет получать поддержку только от сообщества на GitHub до сентября 2026 года.

Для всех новых разработок, поддерживаемых Майкрософт (расширения Copilot, агенты ИИ, приложения Teams или более широкие возможности расширения Microsoft 365), используйте:

• Пакет SDK агентов Microsoft 365 (рекомендуется для всех новых возможностей Copilot или агентов)
• Пакет SDK для Teams (для создания приложений и ботов, доступных только для Teams)

Новые проекты не следует создавать с помощью TeamsFx. Существующие решения TeamsFx следует перенести в пакет SDK для агентов Microsoft 365 Agents, Microsoft 365.

TeamsFx сокращает количество задач за счет использования единого входа (SSO) Microsoft Teams и доступа к облачным ресурсам с помощью однострочных операторов и нулевой конфигурации. Вы можете использовать TeamsFx SDK как в браузерной, так и в Node.js среде. Основные функции TeamsFx доступны в клиентской и серверной средах. Вы можете написать код проверки подлинности пользователей для:

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

Необходимые условия

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

	Установка	Для использования...
	Visual Studio Code	Среды сборки JavaScript, TypeScript или SharePoint Framework (SPFx). Используйте версию 1.55 или более позднюю.
	Набор средств для агентов Microsoft 365 (ранее известный как Teams Toolkit)	Расширение Microsoft Visual Studio Code, создающее шаблоны проекта для вашего приложения. Используйте версию 4.0.0.
	Node.js	Внутренняя среда выполнения JavaScript. Дополнительные сведения см. Node.js таблице совместимости версий для типа проекта.
	Microsoft Teams	Microsoft Teams для совместной работы со всеми, с кем вы работаете, с помощью приложений для чата, собраний, звонков и все в одном месте.
	Microsoft Edge (рекомендуется) или Google Chrome	Браузер со средствами разработчика.

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

Примечание

Если в проекте установлены botbuilder связанные пакеты в качестве зависимостей, убедитесь, что они имеют одну и ту же версию.

Вы должны обладать следующими рабочими знаниями:

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

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

Пакет SDK TeamsFx предварительно настраивается в проекте на основе шаблонов с помощью Microsoft 365 Agents Toolkit CLI (ранее известного как TeamsFx Toolkit или CLI). Дополнительные сведения см. в проекте приложения Teams.

Совет

Фрагменты кода обновлены для последней версии 2 пакета SDK TeamsFx.

Установка пакета

Установите @microsoft/m365agentstoolkit-cli и npm запустите atk -h для проверки все доступные команды:

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

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

Класс TeamsFx

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

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

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

Примечание

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

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

Удостоверение пользователя

Команда	Описание
new TeamsFx(IdentityType.User)	Приложение проходит проверку подлинности в качестве текущего пользователя Teams.
TeamsFx:setSsoToken()	Удостоверение пользователя в Node.js среде (без браузера).
TeamsFx:getUserInfo()	Получение основных сведений о пользователе.
TeamsFx:login()	Она используется, чтобы позволить пользователю выполнять процесс согласия, если вы хотите использовать единый вход для получения маркера доступа для определенных областей OAuth.

Примечание

Вы можете получать доступ к ресурсам от имени текущего пользователя Teams.

Удостоверение приложения

Команда	Описание
new TeamsFx(IdentityType.App)	Приложение проходит проверку подлинности как приложение. Для получения разрешения обычно требуется утверждение администратора.
TeamsFx:getCredential()	Она предоставляет экземпляры учетных данных, автоматически соответствующие типу удостоверения.

Примечание

Для ресурсов требуется согласие администратора.

Учетные данные

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

Существует три класса учетных данных, которые упрощают проверку подлинности. Ниже приведены соответствующие сценарии для каждого целевого объекта класса учетных данных.

Удостоверение пользователя в среде браузера

TeamsUserCredential представляет удостоверение текущего пользователя Teams. При первой проверке подлинности учетных данных пользователя единый вход Teams выполняет поток On-Behalf-Of для обмена токенами. Пакет SDK использует эти учетные данные при выборе удостоверения пользователя в среде браузера.

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

Необходимые конфигурации находятся initiateLoginEndpointclientId и находятся внутри type TeamsUserCredentialAuthConfig.

Удостоверение пользователя в Node.js среде

OnBehalfOfUserCredentialиспользует поток On-Behalf-Of и требует маркера единого входа Teams в сценариях функции Azure или бота. Пакет SDK TeamsFx использует следующие учетные данные при выборе удостоверения пользователя в Node.js среде.

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

Требуемые конфигурации: authorityHost, tenantId, clientIdclientSecret, или certificateContent которые находятся внутри type OnBehalfOfCredentialAuthConfig.

Удостоверение приложения в среде Node.js

AppCredential Представляет удостоверение приложения. Удостоверение приложения можно использовать, когда пользователь не задействован, например в задании автоматизации, запускаемом по времени. Пакет SDK TeamsFx использует следующие учетные данные при выборе удостоверения приложения в Node.js среде.

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

Обязательные конфигурации: authorityHost, clientSecrettenantIdclientIdили certificateContent that's inside typeAppCredentialAuthConfig

Единый вход бота

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

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

Следующий код является примером создания 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 предоставляет несколько функций, облегчающих настройку сторонних библиотек. Они расположены в папке "Core".

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

Примечание

createMicrosoftGraphClient Эта функция устарела. Рекомендуется использовать createMicrosoftGraphClientWithCredential его вместо этого для лучшего опыта программирования.

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

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

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

Примечание

Эта getTediousConnectionConfig функция устарела. Рекомендуется составить собственную конфигурацию Tedious для большей гибкости.

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

Примечание

Класс TeamsFx устарел. Используйте вместо этого , TeamsUserCredential, и AppCredential . OnBehalfOfUserCredential

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

Для проекта вкладки

Если вы создали проект вкладки с помощью Microsoft Visual Studio Code Toolkit, используются следующие значения конфигурации из предварительно настроенных переменных среды:

• 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) // используется только при наличии серверной функции
• apiName (REACT_APP_FUNC_NAME) // используется только при наличии серверной функции

Для функции Azure или проекта бота

Если вы создали функцию Azure или проект бота с помощью набора средств Visual Studio Code, используются следующие значения конфигурации из предварительно настроенных переменных среды:

• 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) // используется только при наличии экземпляра SQL

• sqlUsername (SQL_USER_NAME) // Используется только при наличии экземпляра SQL

• sqlPassword (SQL_PASSWORD) // Используется только при наличии экземпляра SQL

• sqlDatabaseName (SQL_DATABASE_NAME) // используется только при наличии экземпляра SQL

• sqlIdentityId (IDENTITY_ID) // используется только при наличии экземпляра SQL

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

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

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

Примечание

Класс TeamsFx устарел и ErrorWithCode не рекомендуется. Вместо этого можно использовать 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;
  }
}

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

Сценарии Microsoft Graph

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

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

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

  В этом фрагменте кода показано, как использовать 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 в приложении "Вкладка" см. в примере приложения Graph Conctor.

  Интеграция с 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 atk = 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 в приложении бота см. в примере единого входа бота.

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

  Следующий фрагмент кода демонстрирует, как переопределить handleTeamsMessagingExtensionQuery, который расширяется от TeamsActivityHandler. Он использует компоненты handleMessageExtensionQueryWithSSO , предоставляемые пакетом SDK 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;
   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 вызов 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 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.";
      }
    }
   }    
  
  

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

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

  В этом фрагменте кода показано, как использовать 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 в боте или функции Azure и получить доступ к базе данных SQL в функции Azure.

Создайте клиент API для вызова существующего API в функции Bot или Azure

В этом фрагменте кода показано, как вызывать существующий API в боте с помощью ApiKeyProvider.

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

База данных SQL Access в функции Azure

Используйте библиотеку tedious для доступа к SQL и используйте DefaultTediousConnectionConfiguration приложение, управляющее проверкой подлинности. Кроме того, на основе результата sqlConnectionConfig.getConfig().

1. Задайте конфигурацию подключения.

   // Equivalent to:
   // const sqlConnectConfig = new DefaultTediousConnectionConfiguration({
   //    sqlServerEndpoint: process.env.SQL_ENDPOINT,
   //    sqlUsername: process.env.SQL_USER_NAME,
   //    sqlPassword: process.env.SQL_PASSWORD,
   // });
   const atk = 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");  
   

2. Подключение к базе данных.

   const connection = new Connection(config);
   connection.on("connect", (error) => {
   if (error) {
    console.log(error);
    }
   });  
   

   Примечание

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

Дополнительные сведения о доступе к базе данных SQL в функции Azure см. в примере share-now.

Расширенная настройка

Настроить журнал

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

Примечание

По умолчанию журналы отключены. Их можно включить, задав уровень журнала.

Включение журнала путем настройки уровня журнала

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

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

// 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 messages 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).

См. также

• Обзор набора средств агентов Microsoft 365
• Интерфейс интерфейса командной строки набора инструментов для агентов Microsoft 365
• Коллекция примеров Microsoft TeamsFx.
• Добавление единого входа в приложение Teams