Créer des applications SharePoint Framework avec Microsoft Graph

Article
Developer (Débutant)
41 minutes avant achèvement

Ce didacticiel vous apprend à créer un SharePoint côté client qui utilise l’API Microsoft Graph pour récupérer les informations de calendrier d’un utilisateur.

Conseil

Si vous préférez simplement télécharger le didacticiel terminé, vous pouvez télécharger ou cloner le GitHub complet.

Conditions préalables

Avant de commencer ce didacticiel, vous devez avoir installé les outils suivants sur votre ordinateur de développement.

Vous trouverez plus d’informations sur les conditions requises SharePoint Framework développement à l’aide de la SharePoint Framework de développement.

Vous devez également avoir un compte scolaire ou scolaire Microsoft, avec accès à un compte d’administrateur général dans la même organisation. Si vous n’avez pas de compte Microsoft, vous pouvez vous inscrire au programme Microsoft 365 développeur pour obtenir un abonnement Microsoft 365 gratuit.

Votre Microsoft 365 client doit être configuré pour le développement SharePoint Framework, avec un catalogue d’applications et un site de test créés avant de commencer ce didacticiel.

Notes

Ce didacticiel a été écrit avec les versions suivantes des outils ci-dessus. Les étapes de ce guide peuvent fonctionner avec d’autres versions, mais elles n’ont pas été testées.

Node.js 14.15.0
Yeoman 4.1.0
Gulp 4.0.2
Yeoman SharePoint générateur 1.12.1

Commentaires

N’hésitez pas à nous faire part de vos commentaires sur ce didacticiel dans GitHub référentiel.

Créer un composant WebPart SPFX

40 minutes restantes

Dans ce didacticiel, vous allez créer un partie web côté client SharePoint qui utilisera Microsoft Graph pour obtenir le calendrier de l’utilisateur pour la semaine en cours et permettre à l’utilisateur d’ajouter un événement à son calendrier.

Créer un projet de partie Web

Ouvrez votre interface de ligne de commande (CLI) dans un répertoire vide où vous souhaitez créer le projet. Exécutez la commande suivante pour démarrer le générateur SharePoint Yeoman.
```
yo @microsoft/sharepoint
```
Répondez aux invites comme suit.
- Quel est le nom de votre solution ? graph-tutorial
- Quels packages de base voulez-vous cibler pour vos composants ? SharePoint Online only (latest)
- Où souhaitez-vous placer les fichiers ? Use the current folder
- Voulez-vous autoriser l’administrateur client à choisir de pouvoir déployer la solution sur tous les sites immédiatement sans exécuter de déploiement de fonctionnalité ni ajouter d’applications sur les sites. Yes
- Les composants de la solution nécessiteront-ils des autorisations pour accéder aux API Web qui sont uniques et qui ne sont pas partagées avec d'autres composants du client ? No
- Quel type de composant côté client créer? WebPart
- Quel est le nom de votre composant WebPart ? GraphTutorial
- Quelle est la description de votre composant WebPart ? GraphTutorial description
- Quelle infrastructure voulez-vous utiliser ? No JavaScript framework

Installer les dépendances

Avant de passer à autre chose, installez des packages NPM supplémentaires que vous utiliserez ultérieurement.

Microsoft Graph des définitions TypeScript pour fournir Intellisense aux objets Microsoft Graph.
Microsoft Graph Shared Computer Toolkit fournir des composants d’interface utilisateur pour le composant Web Part.
date-fns pour les fonctions utiles pour travailler avec des dates.

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

Configurer des autorisations

35 minutes restantes

Le SharePoint Framework élimine la nécessité d’inscrire une application dans Azure AD pour obtenir des jetons d’accès pour accéder à Microsoft Graph. Il gère l’authentification de l’utilisateur connecté SharePoint, ce qui permet à votre partie Web d’obtenir des jetons utilisateur. Votre partie Web Doit indiquer les Graph d’autorisations dont elle a besoin, et un administrateur client peut approuver ces autorisations lors de l’installation.

Configuration des autorisations

Ouvrez ./config/package-solution.json.

Ajoutez le code suivant à la solution propriété.

"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"
  }
]

L’autorisation Calendars.ReadWrite permet à votre élément Web Part de récupérer le calendrier de l’utilisateur et d’ajouter des événements à l’aide de Microsoft Graph. Les autres autorisations sont utilisées par les composants de Microsoft Graph Shared Computer Toolkit pour restituer des informations sur les participants à l’événement et les organisateurs.

Facultatif : tester l’acquisition d’un jeton

Notes

Le reste des étapes de cette page sont facultatives. Si vous préférez utiliser le codage Microsoft Graph immédiatement, vous pouvez passer à l’affichage Obtenir un affichage Calendrier.

Nous allons ajouter du code temporaire au partie Web Part pour tester l’acquisition de jetons.

Ouvrez ./src/webparts/graphTutorial/GraphTutorialWebPart.ts import et ajoutez l’instruction suivante en haut du fichier.
```
import { AadTokenProvider } from '@microsoft/sp-http';
```

Remplacez la fonction render existante par ce qui suit.

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

Déployer le site Web Part

Exécutez les deux commandes suivantes dans votre CLI pour créer et créer un package de votre partie Web.
```
gulp bundle --ship
gulp package-solution --ship
```
Ouvrez votre navigateur et go to your tenant’s SharePoint App Catalog. Sélectionnez l’élément de menu SharePoint applications sur le côté gauche.
Télécharger fichier ./sharepoint/solution/graph-tutorial.sppkg.
Dans l’invite Faites-vous confiance ... confirmez que l’invite répertorie les 4 autorisations Microsoft Graph que vous avez définies dans le fichier package-solution.json. Sélectionnez Rendre cette solution disponible pour tous les sites de l’organisation, puis déployer.
Go to the SharePoint admin center using a tenant administrator.
Dans le menu de gauche, sélectionnez Avancé, puis Accès à l’API.
Sélectionnez chacune des demandes en attente à partir du package de solution graph-tutorial-client-side-solution et choisissez Approuver.

Tester le composant WebPart

Go to a SharePoint site where you want to test the web part. Créez une page sur la page de test du partie Web.
Utilisez le s sélectionneur de partie Web Pour rechercher le partie Web Part GraphTutorial et l’ajouter à la page.
Le jeton d’accès est imprimé sous l’SharePoint ! dans le volet Web. Vous pouvez copier ce jeton et l’utiliser https://jwt.ms/ pour vérifier qu’il contient les étendues d’autorisation requises par le partie Web.

Obtenir un affichage Calendrier

25 minutes restantes

Le SharePoint Framework fournit MSGraphClient pour effectuer des appels à Microsoft Graph. Cette classe encapsule la bibliothèque cliente Microsoft Graph JavaScript,en l’authentifier préalablement auprès de l’utilisateur actuellement connecté.

Comme elle encapsule la bibliothèque JavaScript existante, son utilisation est la même et elle est entièrement compatible avec les définitions TypeScript de Microsoft Graph.

Obtenir le calendrier de l’utilisateur

Ouvrez ./src/webparts/graphTutorial/GraphTutorialWebPart.ts et ajoutez les instructions suivantes en haut import du fichier.

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

Ajoutez la fonction suivante à la classe GraphTutorialWebPart pour restituer une erreur.

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

Ajoutez la fonction suivante pour imprimer les événements dans le calendrier de l’utilisateur.

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

Remplacez la fonction render existante par ce qui suit.

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

Notez ce que fait ce code.

Il permet this.context.msGraphClientFactory.getClient d’obtenir un objet MSGraphClient authentifié.
Il appelle le point de terminaison, en fixant les paramètres de requête sur le début et la /me/calendarView fin de la semaine en startDateTime endDateTime cours.
Il permet de limiter les champs renvoyés, en demandant select uniquement les champs que l’application utilise.
Il utilise orderby pour trier les événements par heure de début.
Il utilise top pour limiter les résultats à 25 événements.

Déployer le site Web Part

Exécutez les deux commandes suivantes dans votre CLI pour créer et créer un package de votre partie Web.
```
gulp bundle --ship
gulp package-solution --ship
```
Ouvrez votre navigateur et go to your tenant’s SharePoint App Catalog. Sélectionnez l’élément SharePoint menu Applications pour le côté gauche.
Télécharger fichier ./sharepoint/solution/graph-tutorial.sppkg.
Dans l’invite Faites-vous confiance... confirmez que l’invite répertorie les 4 autorisations microsoft Graph que vous avez définies dans le fichierpackage-solution.jssur. Sélectionnez Rendre cette solution disponible pour tous les sites de l’organisation, puis sélectionnez Déployer.
Si vous n’avez pas encore approuvé les autorisations Graph pour votre partie Web, faites-le maintenant.
1. Go to the SharePoint admin center using a tenant administrator.
2. Dans le menu de gauche, sélectionnez Avancé, puis Accès à l’API.
3. Sélectionnez chacune des demandes en attente à partir du package graph-tutorial-client-side-solution et choisissez Approuver.

Tester le composant WebPart

Go to a SharePoint site where you want to test the web part. Créez une page sur la page de test du partie Web.
Utilisez le s sélectionneur de partie Web Pour rechercher le partie Web Part GraphTutorial et l’ajouter à la page.
La liste des événements de la semaine en cours est imprimée dans le volet Web.

Ajouter la boîte à outils Microsoft Graph

15 minutes restantes

Dans cette section, vous allez utiliser microsoft Graph Shared Computer Toolkit pour remplacer la liste simple des événements par une interface utilisateur enrichie.

Le kit de ressources fournit un composant d’agenda,qui est bien adapté pour restituer notre liste d’événements.

Mettre à jour le site Web Part

Ouvrez ./src/webparts/graphTutorial/GraphTutorialWebPart.module.scss. Modifiez la valeur de background-color l’attribut dans .row l’entrée en $ms-color-white .
```
.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-white;
  padding: 20px;
}
```
Ajoutez l’entrée suivante à l’intérieur de .graphTutorial l’entrée.
```
#addSocialBtn {
  margin-bottom: 1em;
}
```
Ouvrez ./src/webparts/graphTutorial/GraphTutorialWebPart.ts et ajoutez l’instruction suivante en haut import du fichier.
```
import { Providers, SharePointProvider, MgtAgenda } from '@microsoft/mgt';
```

Ajoutez la fonction suivante à la classe GraphTutorialWebPart pour initialiser le kit de ressources.

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

Remplacez la fonction renderCalendarView existante par ce qui suit.

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

Cette action remplace la liste de base par le composant Agenda du kit de ressources.

Créez, créez un package et téléchargez à nouveau le partie Web, puis actualisez la page dans laquelle vous le testez.

Une autre approche

À ce stade, vous avez du code qui :

Utilise MSGraphClient pour obtenir l’affichage Calendrier de l’utilisateur pour la semaine en cours auprès de Microsoft Graph.
Ajoutez ces événements au composant Agenda à partir de Microsoft Graph Shared Computer Toolkit.

Avec cette approche, vous avez un contrôle total sur l’appel Graph API et pouvez traiter les événements avant le rendu voulu. Toutefois, si ce n’est pas obligatoire, vous pouvez simplifier l’action en laissant le composant Agenda faire le travail à votre place.

Tous les composants Graph Shared Computer Toolkit Microsoft peuvent effectuer tous les appels d’API pertinents au microsoft Graph. Par exemple, en ajoutant simplement le composant Agenda au composant Web Part, sans définir de propriétés, le composant Web Part utiliserait ses paramètres par défaut pour obtenir les événements du jour en cours. Examinons comment obtenir les mêmes résultats que ceux actuellement obtenus (événements de la semaine en cours).

Remplacez la méthode render existante par ce qui suit.

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

À présent, au lieu d’effectuer un appel d’API, il vous suffit d’ajouter un élément render directement dans le code mgt-agenda HTML. En appelez le début de la semaine et la 7, le composant effectuera le même appel d’API que la date days version render précédente.

Ajoutez la fonction vide suivante à la classe GraphTutorialWebPart.
```
private async addSocialToCalendar() {}
```
Notes

Nous avons également ajouté un bouton Ajouter un lien de réseau social d’équipe au partie Web Et ajouté la méthode en tant qu’écouteur addSocialToCalendar d’événements. Vous allez implémenter le code-behind dans la section suivante. Pour l’instant, nous voulons simplement compiler le code.
Créez, créez un package et téléchargez à nouveau le partie Web, puis actualisez la page dans laquelle vous le testez. L’affichage doit être identique à celui de votre test précédent.

Utilisation du kit de ressources et appels d’API

À ce stade, vous vous demandez peut-être pourquoi vous avez du mal à utiliser MSGraphClient, lorsque le kit de ressources fait le travail pour vous. Le kit de ressources est conçu pour le rendu des résultats que vous interrogez à partir de Microsoft Graph, tels qu’une liste d’événements. Toutefois, il existe des scénarios dans lequel effectuer vous-même des appels d’API est nécessaire.

Tous les appels d’API qui ne sont pas une GET demande. Par exemple, la création d’un événement dans le calendrier ou la mise à jour du numéro de téléphone d’un utilisateur.
Appels d’API pour obtenir des données destinées à être utilisées « en arrière-plan » et qui ne sont pas rendues directement.

Créer un événement

5 minutes restantes

Dans cette section, vous allez mettre à jour le partie Web Pour permettre à l’utilisateur d’ajouter un événement à son calendrier pour l’heure sociale hebdomadaire de l’équipe. Dans ce scénario, l’équipe a une heure sociale hebdomadaire à 16 h le vendredi.

Ouvrez ./src/webparts/graphTutorial/GraphTutorialWebPart.ts et remplacez la méthode addSocialToCalendar() existante par ce qui suit.

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

Prenez en compte ce que fait ce code.

Il détermine le prochain vendredi à venir et construit une date pour 16h00 ce jour-là.
Il construit un nouvel objet MicrosoftGraph.Event, en fixant le début sur la valeur date et la fin une heure plus tard.
Il utilise MSGraphClient pour publier le nouvel événement sur le /me/events point de terminaison.
Il restituera le site Web Part afin que l’affichage soit mis à jour avec le nouvel événement.

Créez, créez un package et téléchargez à nouveau le partie Web, puis actualisez la page dans laquelle vous le testez.
Cliquez sur le bouton Ajouter une équipe sociale. Une fois la page actualisée, faites défiler jusqu’au vendredi et recherchez le nouvel événement.

Créer des applications SharePoint Framework avec Microsoft Graph

Conditions préalables

Commentaires

Créer un composant WebPart SPFX

Créer un projet de partie Web

Installer les dépendances

Configurer des autorisations

Configuration des autorisations

Facultatif : tester l’acquisition d’un jeton

Déployer le site Web Part

Tester le composant WebPart

Obtenir un affichage Calendrier

Obtenir le calendrier de l’utilisateur

Déployer le site Web Part

Tester le composant WebPart

Ajouter la boîte à outils Microsoft Graph

Mettre à jour le site Web Part

Une autre approche

Utilisation du kit de ressources et appels d’API

Créer un événement

Félicitations !

Commentaires