Usar o MSGraphClientV3 para se conectar ao Microsoft Graph

  • Artigo

Ao criar soluções Estrutura do SharePoint, você pode se conectar facilmente ao Microsoft Graph usando o MSGraphClientV3.

Visão geral do MSGraphClient

O MSGraphClientV3 é um novo cliente HTTP introduzido no Estrutura do SharePoint v1.15.0 que simplifica a conexão com o Microsoft Graph dentro de Estrutura do SharePoint soluções. O MSGraphClientV3 encerra a Biblioteca de Clientes JavaScript do Microsoft Graph v3, oferecendo aos desenvolvedores os mesmos recursos que ao usar a biblioteca de clientes em outras soluções do lado do cliente.

MSGraphClientV3 substitui o MSGraphClient, que foi introduzido em Estrutura do SharePoint v1.6.0. MSGraphClient embrulhou a Biblioteca de Clientes JavaScript do Microsoft Graph v1.

Embora você possa usar a Biblioteca de Clientes JavaScript do Microsoft Graph em sua solução diretamente, o MSGraphClientV3 manipula a autenticação no Microsoft Graph para você, o que permite que você se concentre na criação de sua solução.

Usar o MSGraphClient em sua solução

Observação

O MSGraphClientV3 está disponível apenas em projetos criados usando Estrutura do SharePoint v1.15.0 e posterior. Embora o MSGraphClientV3 seja explicado neste artigo usando uma Web Part do lado do cliente, você também pode usá-la em extensões de Estrutura do SharePoint.

Observação

O logon único para o MSGraphClientV3 só está disponível no SharePoint Online hoje. Você pode aproveitar o cliente para desenvolvimentos no local, mas os usuários serão solicitados a entrar novamente dentro da webpart.

  1. Para usar o MSGraphClientV3 em sua solução Estrutura do SharePoint, adicione a seguinte import cláusula no arquivo principal da Web Part:

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

  2. MSGraphClientV3 é exposto por meio do MSGraphClientFactory disponível no contexto da Web Part. Para obter uma referência a MSGraphClient, em seu código, adicione:

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

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

  // ...
}

  3. Depois de ter a referência à instância MSGraphClientV3 , comece a se comunicar com o Microsoft Graph usando sua sintaxe da Biblioteca de Clientes 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
        });
      });
  }

  // ...
}

Usar os tipos de TypeScript do Microsoft Graph

Ao trabalhar com o Microsoft Graph e o TypeScript, você pode usar os tipos de TypeScript do Microsoft Graph para ajudá-lo a capturar erros em seu código com maior rapidez. Os tipos de TypeScript do Microsoft Graph são fornecidos como um pacote separado.

  1. Instale os tipos de TypeScript do Microsoft Graph:

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

  2. Depois de instalar o pacote no projeto, importe-o para seu arquivo da Web Part:

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

  3. Insira os objetos recuperados do Microsoft Graph, por exemplo:

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

  // ...
}

Escopos de permissão disponíveis

Por padrão, a entidade de serviço não tem permissões explícitas concedidas para acessar o Microsoft Graph. No entanto, se você solicitar um token de acesso ao Microsoft Graph, receberá um token com o escopo de permissão user_impersonation, que pode ser usado para ler informações sobre os usuários (ou seja, User.Read.All).

Os escopos de permissão adicionais podem ser solicitados por desenvolvedores e concedidos pelos administradores de locatários. Saiba mais em Conectar-se às APIs protegidas pelo Azure AD em soluções da Estrutura do SharePoint.

Problemas conhecidos

Funções do Azure AD com autenticação delegada

Atualmente, o MSGraphClient usa o fluxo de autenticação implícita ao solicitar permissões delegadas do Microsoft Graph. Conforme indicado nos tokens de acesso à plataforma de identidade da Microsoft, a declaração de wids pode não estar presente ao usar o fluxo de autenticação implícita devido a problemas de extensão. A declaração de wids contém a listagem das funções de todos os locatários do Azure AD que foram atribuídas ao usuário delegado.

Como resultado, as consultas aos pontos de extremidade do Microsoft Graph que dependem de funções do Azure AD e de permissões delegadas, podem falhar devido à declaração de wids não estar presente. Ao gravar será incluso os seguintes pontos de extremidade:

Confira também