Criar aplicativos da estrutura do SharePoint com o Microsoft Graph

Artigo
Developer (Iniciante)
41 minutos para concluir

Este tutorial ensina como criar uma web part SharePoint do lado do cliente que usa a API do Microsoft Graph para recuperar informações de calendário para um usuário.

Dica

Se você preferir apenas baixar o tutorial concluído, poderá baixar ou clonar o GitHub repositório.

Pré-requisitos

Antes de iniciar este tutorial, você deve ter as seguintes ferramentas instaladas em sua máquina de desenvolvimento.

Você pode encontrar mais detalhes sobre os requisitos para Estrutura do SharePoint desenvolvimento em Configurar seu ambiente de Estrutura do SharePoint de desenvolvimento.

Você também deve ter uma conta de estudante ou de trabalho da Microsoft, com acesso a uma conta de administrador global na mesma organização. Se você não tiver uma conta da Microsoft, poderá inscrever-se no programa de desenvolvedor Microsoft 365 para obter uma assinatura Microsoft 365 gratuita.

Seu Microsoft 365 locatário deve ser configurado para Estrutura do SharePoint desenvolvimento, com um catálogo de aplicativos e um site de teste criado antes de iniciar este tutorial.

Observação

Este tutorial foi escrito com as seguintes versões das ferramentas acima. As etapas neste guia podem funcionar com outras versões, mas que não foram testadas.

Node.js 14.15.0
Yeoman 4.1.0
Gulp 4.0.2
Yeoman SharePoint gerador 1.12.1

Comentários

Forneça qualquer comentário sobre este tutorial no repositório GitHub.

Criar uma Web Part do SPFX

40 minutos restantes

Neste tutorial, você criará uma web part SharePoint do lado do cliente que usará o Microsoft Graph para obter o calendário do usuário para a semana atual e permitir que o usuário adicione um evento ao calendário.

Criar um projeto de Web Part

Abra sua interface de linha de comando (CLI) em um diretório vazio onde você deseja criar o projeto. Execute o seguinte comando para iniciar o gerador yeoman SharePoint.
```
yo @microsoft/sharepoint
```
Responda aos prompts da seguinte forma.
- Qual é o nome da solução? graph-tutorial
- Quais pacotes de linha de base deseja direcionar para seus componentes? SharePoint Online only (latest)
- Onde você deseja colocar os arquivos? Use the current folder
- Você deseja permitir que o administrador de locatários possa implantar a solução para todos os sites imediatamente sem executar qualquer implantação de recurso ou adicionar aplicativos aos sites? Yes
- Os componentes da solução exigem permissões para acessar as APIs da Web que são exclusivas e não são compartilhadas com outros componentes no locatário? No
- Que tipo de componente do cliente será criado? WebPart
- Qual é o nome da Web Part? GraphTutorial
- Qual é a descrição da Web Part? GraphTutorial description
- Qual estrutura você deseja usar? No JavaScript framework

Instalar dependências

Antes de continuar, instale alguns pacotes NPM adicionais que você usará posteriormente.

As definições Graph TypeScript da Microsoft para fornecer o Intellisense para objetos Graph Microsoft.
A Microsoft Graph Toolkit fornecer componentes da interface do usuário para a Web Part.
date-fns para funções úteis para trabalhar com datas.

npm install @microsoft/microsoft-graph-types@1.36.0 --save-dev
npm install @microsoft/mgt@2.1.0 date-fns @2.21.1

Configurar permissões

35 minutos restantes

A Estrutura do SharePoint elimina a necessidade de registrar um aplicativo no Azure AD para obter tokens de acesso para acessar o Microsoft Graph. Ele lida com a autenticação do usuário que está conectado SharePoint, permitindo que sua Web Part receba tokens de usuário. Sua Web Part precisa indicar quais Graph escopos de permissão necessários, e um administrador de locatário pode aprovar essas permissões durante a instalação.

Configurar as permissões

Abra ./config/package-solution.json.

Adicione o código a seguir à solution propriedade.

"webApiPermissionRequests": [
  {
    "resource": "Microsoft Graph",
    "scope": "Calendars.ReadWrite"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "User.ReadBasic.All"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "Contacts.Read"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "People.Read"
  }
]

A Calendars.ReadWrite permissão permite que sua Web Part recupere o calendário do usuário e adicione eventos usando o Microsoft Graph. As outras permissões são usadas por componentes no microsoft Graph Toolkit para renderizar informações sobre participantes e organizadores de eventos.

Opcional: Aquisição de token de teste

Observação

O restante das etapas nesta página são opcionais. Se você preferir chegar à codificação do microsoft Graph imediatamente, você pode prosseguir para Obter um exibição de calendário.

Vamos adicionar algum código temporário à Web Part para testar a aquisição de token.

Abra ./src/webparts/graphTutorial/GraphTutorialWebPart.ts import e adicione a seguinte instrução na parte superior do arquivo.
```
import { AadTokenProvider } from '@microsoft/sp-http';
```

Substitua a função render existente pela seguinte.

public render(): void {
  this.context.aadTokenProviderFactory
    .getTokenProvider()
    .then((provider: AadTokenProvider)=> {
    provider
      .getToken('https://graph.microsoft.com')
      .then((token: string) => {
        this.domElement.innerHTML = `
        <div class="${ styles.graphTutorial }">
          <div class="${ styles.container }">
            <div class="${ styles.row }">
              <div class="${ styles.column }">
                <span class="${ styles.title }">Welcome to SharePoint!</span>
                <p><code style="word-break: break-all;">${ token }</code></p>
              </div>
            </div>
          </div>
        </div>`;
      });
    });
}

Implantar a Web Part

Execute os dois comandos a seguir em sua CLI para criar e empacotar sua Web Part.
```
gulp bundle --ship
gulp package-solution --ship
```
Abra seu navegador e vá para o Catálogo de Aplicativos SharePoint seu locatário. Selecione o item de menu Aplicativos SharePoint lado esquerdo.
Upload arquivo ./sharepoint/solution/graph-tutorial.sppkg.
No prompt Do you trust... confirm that the prompt lists the 4 Microsoft Graph permissions you set in the package-solution.json file. Selecione Disponibilizar essa solução para todos os sites da organização e selecione Implantar.
Vá para o centro SharePoint administrador usando um administrador de locatários.
No menu à esquerda, selecione Avançado e acesso à API.
Selecione cada uma das solicitações pendentes no pacote graph-tutorial-client-side-solution e escolha Aprovar.

Testar a web part

Vá para um SharePoint site em que você deseja testar a Web Part. Crie uma nova página para testar a Web Part.
Use o se picker da Web Part para encontrar a Web Part GraphTutorial e adicioná-la à página.
O token de acesso é impresso abaixo do welcome to SharePoint! mensagem na Web Part. Você pode copiar esse token e analisar https://jwt.ms/ para confirmar se ele contém os escopos de permissão exigidos pela Web Part.

Obter um modo de exibição de calendário

25 minutos restantes

O Estrutura do SharePoint fornece o MSGraphClient para fazer chamadas para o Microsoft Graph. Esta classe quebra a Biblioteca de Clientes JavaScriptdo Microsoft Graph , pré-autenticando-a com o usuário conectado ao usuário atual.

Como ela quebra a biblioteca JavaScript existente, seu uso é o mesmo e é totalmente compatível com as definições do Microsoft Graph TypeScript.

Obter o calendário do usuário

Abra ./src/webparts/graphTutorial/GraphTutorialWebPart.ts e adicione as instruções a seguir na import parte superior do arquivo.

import { MSGraphClient } from '@microsoft/sp-http';
import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
import { startOfWeek, endOfWeek, setDay, set } from 'date-fns';

Adicione a seguinte função à classe GraphTutorialWebPart para renderizar um erro.

private renderGraphError(error: any): void {
  const viewContainer = this.domElement.querySelector('#calendarView');

  // Basic error display
  viewContainer.innerHTML = `
  <h2 class="${ styles.title }">Error</h2>
  <code style="word-break: break-all;">${JSON.stringify(error, null, 2)}</code>`;
}

Adicione a seguinte função para imprimir os eventos no calendário do usuário.

private renderCalendarView(events: MicrosoftGraph.Event[]) : void {
  const viewContainer = this.domElement.querySelector('#calendarView');
  let html = '';

  // Temporary: print events as a list
  for(const event of events) {
    html += `
      <p class="${ styles.description }">Subject: ${event.subject}</p>
      <p class="${ styles.description }">Organizer: ${event.organizer.emailAddress.name}</p>
      <p class="${ styles.description }">Start: ${event.start.dateTime}</p>
      <p class="${ styles.description }">End: ${event.end.dateTime}</p>
      `;
  }

  viewContainer.innerHTML = html;
}

Substitua a função render existente pela seguinte.

public render(): void {
  this.context.msGraphClientFactory
    .getClient()
    .then((graphClient: MSGraphClient)=> {
      // Get current date
      const now = new Date();
      // Get the start and end of the week based on current date
      const weekStart = startOfWeek(now);
      const weekEnd = endOfWeek(now);

      graphClient
        .api(`/me/calendarView?startDateTime=${weekStart.toISOString()}&endDateTime=${weekEnd.toISOString()}`)
        .select('subject,organizer,start,end,location,attendees')
        .orderby('start/dateTime')
        .top(25)
        .get((error: any, events: any) => {
          this.domElement.innerHTML = `
          <div class="${ styles.graphTutorial }">
            <div class="${ styles.container }">
              <div class="${ styles.row }">
                <div class="${ styles.column }">
                  <div id="calendarView" />
                </div>
              </div>
            </div>
          </div>`;

          if (error) {
            this.renderGraphError(error);
          } else {
            this.renderCalendarView(events.value);
          }
        });
    });
}

Observe o que esse código faz.

Ele usa this.context.msGraphClientFactory.getClient para obter um objeto MSGraphClient autenticado.
Ele chama o /me/calendarView ponto de extremidade, definindo os parâmetros e de consulta como o início e o final da semana startDateTime endDateTime atual.
Ele usa select para limitar quais campos são retornados, solicitando apenas os campos que o aplicativo usa.
Ele usa orderby para classificar os eventos por hora de início.
Ele usa top para limitar os resultados a 25 eventos.

Implantar a Web Part

Execute os dois comandos a seguir em sua CLI para criar e empacotar sua Web Part.
```
gulp bundle --ship
gulp package-solution --ship
```
Abra o navegador e vá para o catálogo de aplicativos SharePoint seu locatário. Selecione o item de menu Aplicativos SharePoint lado esquerdo.
Upload arquivo ./sharepoint/solution/graph-tutorial.sppkg.
No prompt Do you trust... confirm that the prompt lists the 4 Microsoft Graph permissions you set in the package-solution.json file. Selecione Disponibilizar essa solução para todos os sites da organização e, em seguida, selecione Implantar.
Se você ainda não aprovou as permissões Graph para sua Web Part, faça isso agora.
1. Vá para o SharePoint de administração usando um administrador de locatários.
2. No menu à esquerda, selecione Avançado, em seguida, acesso à API.
3. Selecione cada uma das solicitações pendentes no pacote graph-tutorial-client-side-solution e escolha Aprovar.

Testar a web part

Vá para um SharePoint site em que você deseja testar a Web Part. Crie uma nova página para testar a Web Part.
Use o se picker da Web Part para encontrar a Web Part GraphTutorial e adicioná-la à página.
Uma lista de eventos da semana atual é impressa na Web Part.

Adicionar o Microsoft Graph Toolkit

15 minutos restantes

Nesta seção, você usará o microsoft Graph Toolkit para substituir a lista simples de eventos por interface do usuário rica.

O kit de ferramentas fornece um componente Agenda, que é adequado para renderizar nossa lista de eventos.

Atualizar a Web Part

Abra ./src/webparts/graphTutorial/GraphTutorialWebPart.module.scss. Altere o valor do background-color atributo na entrada para .row $ms-color-white .
```
.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-white;
  padding: 20px;
}
```
Adicione a entrada a seguir dentro da .graphTutorial entrada.
```
#addSocialBtn {
  margin-bottom: 1em;
}
```
Abra ./src/webparts/graphTutorial/GraphTutorialWebPart.ts e adicione a seguinte instrução na import parte superior do arquivo.
```
import { Providers, SharePointProvider, MgtAgenda } from '@microsoft/mgt';
```

Adicione a seguinte função à classe GraphTutorialWebPart para inicializar o kit de ferramentas.

protected async onInit() {
  // Set the toolkit's global auth provider to
  // SharePoint provider, allowing it to use the Graph
  // access token
  Providers.globalProvider =
    new SharePointProvider(this.context);
}

Substitua a função renderCalendarView existente pela seguinte.

private renderCalendarView(events: MicrosoftGraph.Event[]) : void {
  const viewContainer = this.domElement.querySelector('#calendarView');

  // Create an agenda component from the toolkit
  let agenda = new MgtAgenda();
  // Set the events
  agenda.events = events;
  // Group events by day
  agenda.groupByDay = true;

  viewContainer.appendChild(agenda);
}

Isso substitui a lista básica pelo componente Agenda do kit de ferramentas.

Crie, empacote e carregue a Web Part e atualize a página onde você a está testando.

Uma abordagem alternativa

Neste ponto, você tem um código que:

Usa o MSGraphClient para obter a exibição de calendário do usuário para a semana atual do Microsoft Graph.
Adicione esses eventos ao componente Agenda do microsoft Graph Toolkit.

Com essa abordagem, você tem controle total sobre a chamada da API Graph e pode fazer qualquer processamento dos eventos antes da renderização que você deseja. No entanto, se isso não for necessário, você poderá simplificar deixando o componente Agenda fazer o trabalho para você.

Todos os Graph Toolkit microsoft são capazes de fazer todas as chamadas de API relevantes para o microsoft Graph. Por exemplo, apenas adicionando o componente Agenda à Web Part e não definindo nenhuma propriedade, a Web Part usaria suas configurações padrão para obter eventos para o dia atual. Vamos ver como podemos alcançar os mesmos resultados que temos atualmente (eventos para a semana atual).

Substitua o método render existente pelo seguinte.

public render(): void {
  // Get current date
  const now = new Date();
  // Get the start of the week based on current date
  const weekStart = startOfWeek(now);

  this.domElement.innerHTML = `
  <div class="${ styles.graphTutorial }">
    <div class="${ styles.container }">
      <div class="${ styles.row }">
        <div class="${ styles.column }">
          <button class="${ styles.button }" id="${ styles.addSocialBtn }">
            <span class="${ styles.label }">Add team social</span>
          </button>
          <mgt-agenda
            date="${weekStart.toISOString()}"
            days="7"
            group-by-day></mgt-agenda>
        </div>
      </div>
    </div>
  </div>`;

  this.domElement.querySelector(`#${styles.addSocialBtn}`)
    .addEventListener('click', this.addSocialToCalendar.bind(this));
}

Agora, em vez de fazer uma chamada de render API, basta adicionar um mgt-agenda elemento diretamente ao HTML. Ao definir para o início da semana e para 7, o componente fará a mesma chamada de API da date versão anterior que estava days render fazendo.

Adicione a seguinte função vazia à classe GraphTutorialWebPart.
```
private async addSocialToCalendar() {}
```
Observação

Também adicionamos um botão Adicionar equipe social à Web Part e adicionamos o método como ouvinte de addSocialToCalendar eventos. Você implementará o código por trás disso na próxima seção. Por enquanto, só queremos que o código seja compilado.
Crie, empacote e carregue a Web Part e atualize a página onde você a está testando. O modo de exibição deve ser igual ao teste anterior.

Usar o kit de ferramentas vs fazer chamadas de API

Neste ponto, você pode estar se perguntando por que você passou pelo problema de usar o MSGraphClient em tudo, quando o kit de ferramentas faz o trabalho para você. O kit de ferramentas foi projetado para renderizar resultados que você consulta da Microsoft Graph, como uma lista de eventos. No entanto, há cenários em que fazer chamadas de API por conta própria é necessário.

Qualquer chamada de API que não seja uma GET solicitação. Por exemplo, criar um novo evento no calendário ou atualizar o número de telefone de um usuário.
Chamadas de API para obter dados destinados a serem usados "nos bastidores" e não renderizados diretamente.

Criar um novo evento

5 minutos restantes

Nesta seção, você atualizará a Web Part para permitir que o usuário adicione um evento ao calendário para a hora social semanal da equipe. Nesse cenário, a equipe tem uma hora social semanal às 16h de sexta-feira.

Abra ./src/webparts/graphTutorial/GraphTutorialWebPart.ts e substitua o método existente addSocialToCalendar() pelo seguinte.

private async addSocialToCalendar() {
  const graphClient = await this.context.msGraphClientFactory.getClient();

  // Get current date
  const now = new Date();

  // Set start time to next Friday
  // at 4 PM
  const socialHourStart = set(
    setDay(now, 5),
    {
      hours: 16,
      minutes: 0,
      seconds:0,
      milliseconds: 0
    });

  // Create a new event
  const socialHour: MicrosoftGraph.Event = {
    subject: 'Team Social Hour',
    body: {
      contentType: 'text',
      content: 'Come join the rest of the team for our end-of-week social hour.'
    },
    location: {
      displayName: 'Break room'
    },
    start: {
      dateTime: socialHourStart.toISOString(),
      timeZone: 'UTC'
    },
    end: {
      dateTime: set(socialHourStart, { hours: 17 }).toISOString(),
      timeZone: 'UTC'
    }
  };

  try {
    // POST /me/events
    await graphClient
      .api('/me/events')
      .post(socialHour);

    // Refresh the view
    this.render();
  } catch (error) {
    this.renderGraphError(error);
  }
}

Considere o que esse código faz.

Ele determina a próxima sexta-feira e constrói uma Data para 16:00 nesse dia.
Ele constrói um novo objeto MicrosoftGraph.Event, definindo o início como o valor da Data e o final de uma hora depois.
Ele usa o MSGraphClient para POSTAR o novo evento no /me/events ponto de extremidade.
Ele renderiza a Web Part de forma que o modo de exibição seja atualizado com o novo evento.

Crie, empacote e carregue a Web Part e atualize a página onde você a está testando.
Clique no botão Adicionar social da equipe. Depois que a página é atualizada, role para baixo até sexta-feira e localize o novo evento.

Criar aplicativos da estrutura do SharePoint com o Microsoft Graph

Pré-requisitos

Comentários

Criar uma Web Part do SPFX

Criar um projeto de Web Part

Instalar dependências

Configurar permissões

Configurar as permissões

Opcional: Aquisição de token de teste

Implantar a Web Part

Testar a web part

Obter um modo de exibição de calendário

Obter o calendário do usuário

Implantar a Web Part

Testar a web part

Adicionar o Microsoft Graph Toolkit

Atualizar a Web Part

Uma abordagem alternativa

Usar o kit de ferramentas vs fazer chamadas de API

Criar um novo evento

Parabéns!

Comentários