Use Microsoft Graph na solução

Artigo
03/21/2023

O Microsoft Graph fornece um modelo de programação unificada que você pode usar para criar aplicativos para empresas e clientes que interagem com os dados de milhões de usuários. Você pode acessar facilmente o Microsoft Graph usando as soluções da Estrutura do SharePoint.

Antes de começar, conclua as etapas nos artigos a seguir para garantir que você compreenda o fluxo básico da criação de uma web part personalizada do lado do cliente:

Você também pode seguir estas etapas assistindo a este vídeo no Canal do YouTube da Comunidade (PnP) da Plataforma Microsoft 365:

Criar um projeto da Estrutura do SharePoint para uso do Microsoft Graph

Crie um novo diretório de projeto em seu local favorito:
```
md graph-apis
```
Vá para o diretório do projeto:
```
cd graph-apis
```
Crie um novo projeto executando o Gerador Yeoman do SharePoint a partir do novo diretório que você criou:
```
yo @microsoft/sharepoint
```
O Gerador Yeoman do Microsoft Office SharePoint Online solicitará uma série de perguntas. Para todas as perguntas, aceite as opções padrão, exceto para as seguintes perguntas:
- Deseja permitir ao administrador do inquilino a opção de implantar a solução em todos os sites imediatamente, sem executar nenhuma implantação de recurso ou adicionar aplicativos nos sites?: Sim
- Que tipo de componente para o cliente você deseja criar?: WebPart
- Qual é o nome da sua Web part?: MyFirstGraphWebPart
- Qual estrutura você deseja usar?: nenhuma estrutura
Neste ponto, o Yeoman instalará as dependências necessárias e manterá a estrutura dos arquivos da solução. A criação da solução pode levar alguns minutos. O Yeoman aplica o scaffolding ao projeto para incluir sua web part MyFirstGraphWebPart também.
Em seguida, para abrir o projeto da web part no Visual Studio Code, digite o seguinte:
```
code .
```

Como incluir tipos do Microsoft Graph para simplificar o desenvolvimento em TypeScript

No console, insira o seguinte para instalar as declarações de tipo do Microsoft Graph para melhorar a experiência de desenvolvimento
```
npm install @microsoft/microsoft-graph-types
```

Atualização do manifesto da solução com as solicitações de permissões necessárias do Microsoft Graph

Usando a Estrutura do SharePoint, não é necessário criar explicitamente aplicativos do Azure Active Directory para gerenciar suas permissões para suas soluções. Em vez disso, você pode solicitar as permissões necessárias em seu pacote de solução e o administrador de locatários do Microsoft 365 pode conceder as permissões solicitadas em geral para todas as soluções ou para essa solução específica (solução isolada).

Observação

Os administradores de locatários também podem gerenciar as permissões de API usando cmdlets do PowerShell, portanto, não há necessidade de ter as permissões incluídas no pacote de solução.

Nesse caso, incluiremos as permissões específicas da solução no pacote.

Abra o arquivo ./config/package-solution.json.
Atualize a seção da solução para incluir a solicitação de concessão de permissão conforme mostrado na seção de código a seguir usando o elemento webApiPermissionRequests. Nesse caso, acessaremos os emails do usuário e, portanto, solicitamos permissões para o escopo da Mail.Read.
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...

    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Mail.Read"
      }
    ]

    //...
  }
}
```

Atualizar código para chamar o Microsoft Graph

Nesse caso, modificaremos o código para usar o Microsoft Graph para obter acesso aos últimos cinco emails do usuário atual.

Abra ./src/webparts/helloWorld/MyFirstGraphWebPartWebPart.ts.

Adicione as seguintes instruções import a seguir depois das instruções import existentes na parte superior do arquivo:

import { MSGraphClientV3 } from '@microsoft/sp-http';
import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';

Atualizar o método render() da seguinte maneira. Observe como estamos usando o objeto MSGraphClientV3 para chamadas do Microsoft Graph. Esse objeto abstrai o tratamento de token de acesso, para que, como desenvolvedor, você possa se concentrar em sua lógica de negócios.

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/messages')
    .top(5)
    .orderby("receivedDateTime desc")
    .get((error, messages: any, rawResponse?: any) => {

      this.domElement.innerHTML = `
      <div class="${styles.myFirstGraphWebPart}">
        <div>
            <h3>Welcome to SharePoint Framework!</h3>
            <p>
                The SharePoint Framework (SPFx) is a extensibility model for Microsoft Viva, Microsoft Teams and SharePoint. It's the easiest way to extend Microsoft 365 with automatic Single Sign On, automatic hosting and industry standard tooling.
            </p>
        </div>
        <div id="spListContainer" />
      </div>`;

      // List the latest emails based on what we got from the Graph
      this._renderEmailList(messages.value);
    });
  });
}

Inclua também a função de ajuda seguinte para renderizar o conteúdo do email imediatamente após o método de render() existente. Observe como estamos usando os tipos MicrosoftGraph.Message para oferecer uma melhor experiência de desenvolvimento para o acesso aos dados de resposta da API.

private _renderEmailList(messages: MicrosoftGraph.Message[]): void {
  let html: string = '';
  for (let index = 0; index < messages.length; index++) {
    html += `<p class="${styles.welcome}">Email ${index + 1} - ${escape(messages[index].subject)}</p>`;
  }

  // Add the emails to the placeholder
  const listContainer: Element = this.domElement.querySelector('#spListContainer');
  listContainer.innerHTML = html;
}

Empacotar e implantar sua Web Part no Microsoft Office SharePoint Online

Execute os seguintes comandos para empacotar sua solução. Isso executa uma versão de lançamento do seu projeto usando um rótulo dinâmico como a URL do host para seus ativos.
```
gulp bundle --ship
```
Execute a seguinte tarefa para criar um pacote para a solução. Isso cria um pacote atualizado graph-apis.sppkg na pasta sharepoint/solution.
```
gulp package-solution --ship
```

Em seguida, você precisa implantar o pacote que foi gerado no Catálogo de Aplicativos do locatário.

Observação

Se você não tiver um catálogo de aplicativos, um Administrador do SharePoint Online poderá criar um seguindo as instruções neste guia: Usar o Catálogo de Aplicativos para criar aplicativos corporativos personalizados disponíveis para seu ambiente do SharePoint Online.

Vá para o Catálogo de Aplicativos do SharePoint do seu locatário.
Carregar ou arrastar e soltar graph-apis.sppkg no catálogo de aplicativos.

Isso implanta o pacote da solução do lado do cliente. Como esta é uma solução do lado do cliente de confiança total, o SharePoint exibirá uma caixa de diálogo e solicitará que você confie na solução do lado do cliente para a implantação.

Observe como a lista domínio no prompt exibe SharePoint Online. Isso ocorre porque o conteúdo é fornecido por meio da CDN do Office 365 ou do Catálogo de Aplicativos, dependendo das configurações do locatário.

Verifique se a opção Disponibilizar esta solução para todos os sites da organização está selecionada para que a web part possa ser usada com facilidade no locatário.

Observe a solicitação para ir para a Página de Gerenciamento de APIs para permissões pendentes aprovadas e a lista de permissões necessárias, neste caso, Mail.Read para o Microsoft Graph.
Selecione Implantar.

Observe que você pode ver se há exceções ou problemas no pacote conferindo a coluna Mensagem de Erro do Pacote do Aplicativo no Catálogo de Aplicativos.

Agora, a web part foi implantada e está automaticamente disponível entre os sites do SharePoint Online; no entanto, é importante observar que a web part não funcionará corretamente até que as permissões solicitadas sejam aprovadas.

Aprovar as permissões do Microsoft Graph solicitadas

Mova para as UIs administrativas do locatário do SharePoint localizadas em https://{{tenant}}-admin.sharepoint.com.
Mova para o gerenciamento avançado > de API na opção de menu esquerdo para ver as solicitações de permissão pendentes no momento. Observe que a solicitação de permissão Mail.Read do Microsoft Graph está pendente para aprovação.
Selecione a linha da permissão pendente e escolha Aprovar ou rejeitar na barra de ferramentas
Examine a permissão solicitada no painel esquerdo e escolha Aprovar

Importante

A conta usada para conceder as permissões necessárias deve ser um administrador de locatários. A permissão de Administrador de serviços do SharePoint não é suficiente, uma vez que a operação é, na verdade, realizada no locatário do Azure Active Directory associado do locatário.

Neste ponto, as permissões solicitadas necessárias para a Web Part foram aprovadas e podemos testar a funcionalidade.

Use a web part no Microsoft Office SharePoint Online

Vá para um site onde você queira testar a web part. Nós implantamos uma web part usando a opção implantação com escopo de locatários para que ela fique disponível em qualquer site.
Criar uma nova página moderna para o site ou editar uma página existente.
Use o termo de pesquisa Graph no seletor de Web Parts para localizar a Web Part:
Escolha MyFirstGraphWebPart na lista e observe como a web part processa os cinco últimos emails do usuário atual usando as informações da API do Microsoft Graph.