Поделиться через

Использование MSGraphClientV3 для подключения к Microsoft Graph

  • Статья

При создании SharePoint Framework решений вы можете легко подключиться к Microsoft Graph с помощью MSGraphClientV3.

Обзор MSGraphClient

MSGraphClientV3 — это новый HTTP-клиент, представленный в SharePoint Framework версии 1.15.0, который упрощает подключение к Microsoft Graph в SharePoint Framework решениях. MSGraphClientV3 содержит оболочку клиентской библиотеки JavaScript версии 3 для Microsoft Graph, предоставляя разработчикам те же возможности, что и при использовании клиентской библиотеки в других клиентских решениях.

MSGraphClientV3 заменяет MSGraphClient, появившийся в SharePoint Framework версии 1.6.0. MSGraphClient упаковал клиентскую библиотеку JavaScript для Microsoft Graph версии 1.

Хотя вы можете использовать клиентскую библиотеку JavaScript Microsoft Graph в решении напрямую, MSGraphClientV3 обрабатывает проверку подлинности в Microsoft Graph, что позволяет сосредоточиться на создании решения.

Использование класса MSGraphClient в решении

Примечание.

MSGraphClientV3 доступен только в проектах, созданных с использованием SharePoint Framework версии 1.15.0 и более поздних версий. Хотя MSGraphClientV3 описывается в этой статье с помощью клиентской веб-части, ее также можно использовать в SharePoint Framework extensions.

Примечание.

Сейчас единый вход для MSGraphClientV3 доступен только в SharePoint Online. Вы можете использовать клиент для локальных разработок, но пользователям потребуется снова войти в веб-часть.

  1. Чтобы использовать MSGraphClientV3 в решении SharePoint Framework, добавьте следующее import предложение в основной файл веб-части:

    import { MSGraphClientV3 } from '@microsoft/sp-http';

  2. MSGraphClientV3 предоставляется через msGraphClientFactory, доступный в контексте веб-части. Чтобы получить ссылку на MSGraphClient, в коде добавьте:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // use MSGraphClient here
      });
  }

  // ...
}

  3. Получив ссылку на экземпляр MSGraphClientV3 , начните взаимодействовать с Microsoft Graph с помощью синтаксиса клиентской библиотеки JavaScript:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // get information about the current user from the Microsoft Graph
        client
          .api('/me')
          .get((error, response: any, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

Использование типов TypeScript для Microsoft Graph

При работе с Microsoft Graph и TypeScript вы можете использовать типы TypeScript для Microsoft Graph, которые помогут вам быстрее обнаруживать ошибки в коде. Типы TypeScript для Microsoft Graph предоставляются в виде отдельного пакета.

  1. Установите типы TypeScript для Microsoft Graph:

    npm install @microsoft/microsoft-graph-types --save-dev

  2. Установив пакет в проекте, импортируйте его в файл веб-части:

    import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';

  3. Укажите объекты, полученные из Microsoft Graph, например:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // get information about the current user from the Microsoft Graph
        client
          .api('/me')
          .get((error: any, user: MicrosoftGraph.User, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

Доступные области разрешений

По умолчанию субъекту-службе не назначены явные разрешения на доступ к Microsoft Graph. Однако если вы запрашиваете маркер доступа для Microsoft Graph, вы получите токен с областью разрешений user_impersonation, который можно использовать для считывания сведений о пользователях (т. е. User.Read.All).

Разработчики могут запрашивать дополнительные области разрешений, а администраторы клиентов — предоставлять их. Дополнительные сведения см. в статье Подключение к API, защищенным службой Azure AD, в решениях SharePoint Framework.

Известные проблемы

Роли Azure AD с делегированной проверкой подлинности

MSGraphClient в настоящее время использует неявный поток проверки подлинности при запросе делегированных разрешений из Microsoft Graph. Как указано в статье Маркеры доступа платформы удостоверений Майкрософт, утверждение wids может отсутствовать при использовании неявного потока проверки подлинности из-за проблем с длиной. Утверждение wids содержит перечень ролей Azure AD на уровне клиента, назначенных делегированному пользователю.

В результате запросы к конечным точкам Microsoft Graph, использующие роли Azure AD, а также к делегированным разрешениям могут завершаться неудачно из-за отсутствия утверждения wids. На момент написания этой статьи сюда относятся следующие конечные точки:

См. также