Verwenden von Microsoft Graph in Ihrer Lösung

Microsoft Graph bietet ein einheitliches Programmierbarkeitsmodell, mit dem Sie Apps für Organisationen und Kunden erstellen können, die mit den Daten von Millionen von Benutzern interagieren. Sie können auch ganz einfach auf Microsoft Graph über SharePoint-Framework-Lösungen zugreifen.

Bevor Sie beginnen, führen Sie die Schritte in den folgenden Artikeln aus, um sicherzustellen, dass Sie den grundlegenden Fluss des Erstellens eines benutzerdefinierten, clientseitigen Webparts verstehen:

Sie können die nachfolgend beschriebene Anleitung auch anhand dieses Videos in unserem YouTube-Kanal „SharePoint Patterns & Practices“ nachvollziehen:

Erstellen eines SharePoint-Framework-Projekts für die Microsoft Graph-Nutzung

  1. Erstellen Sie an einem Speicherort Ihrer Wahl ein neues Projektverzeichnis:

    md graph-apis
    
  2. Wechseln Sie in das Projektverzeichnis:

    cd graph-apis
    
  3. Erstellen Sie ein neues Projekt, indem Sie den Yeoman SharePoint-Generator in dem neuen Verzeichnis ausführen, das Sie erstellt haben:

    yo @microsoft/sharepoint
    

    Der Yeoman SharePoint-Generator zeigt eine Reihe von Fragen an. Akzeptieren Sie bei allen Fragen die Standardoptionen mit Ausnahme der folgenden Fragen:

    • Möchten Sie dem Mandantenadministrator erlauben, festzulegen, ob die Lösung unmittelbar für alle Websites bereitgestellt wird, ohne die Bereitstellung von Features oder das Hinzufügen von Apps zu Websites? Ja
    • Welcher Typ von clientseitiger Komponente soll erstellt werden?: WebPart
    • Welches Framework möchten Sie verwenden?: Kein JavaScript-Framework

    An diesem Punkt installiert Yeoman die erforderlichen Abhängigkeiten und erstellt ein Gerüst für die Lösungsdateien. Die Erstellung der Lösung kann einige Minuten dauern. Yeoman erstellt ein Gerüst für das Projekt, um auch das MyFirstGraphWebPart-Webpart einzuschließen.

  4. Geben Sie als Nächstes Folgendes ein, um das Webpart-Projekt in Visual Studio Code zu öffnen:

    code .
    

Einschließen von Microsoft Graph-Typen zur einfacheren TypeScript-Entwicklung

  1. Geben Sie in der Konsole Folgendes ein, um Microsoft Graph-Typdeklarationen zu installieren, um die Entwicklungsumgebung zu verbessern.

    npm install @microsoft/microsoft-graph-types
    

Aktualisieren des Lösungsmanifests mit den erforderlichen Microsoft Graph-Berechtigungsanforderungen

Wenn Sie SharePoint Framework verwenden, müssen Sie nicht explizit Azure Active Directory-Anwendungen erstellen, um Ihre Berechtigungen für Ihre Lösungen zu verwalten. Stattdessen können Sie die erforderlichen Berechtigungen in Ihrem Lösungspaket anfordern, und Microsoft 365 Mandantenadministrator kann dann die angeforderten Berechtigungen im Allgemeinen für alle Lösungen oder für diese spezifische Lösung (isolierte Lösung) erteilen.

Hinweis

Mandantenadministratoren können die API-Berechtigungen auch mithilfe von PowerShell-Cmdlets verwalten. Es ist also nicht notwendig, die Berechtigungen in das Lösungspaket einzuschließen.

In diesem Fall fügen wir die lösungsspezifischen Berechtigungen in das Paket ein.

  1. Öffnen Sie die Datei ./config/package-solution.json.

  2. Aktualisieren Sie den Lösungsabschnitt, um die Anfrage zur Berechtigungserteilung wie im folgenden Codeabschnitt gezeigt durch Verwendung des webApiPermissionRequests-Elements aufzunehmen. In diesem Fall werden wir auf die E-Mails der Benutzer zugreifen, daher haben wir die erforderlichen Berechtigungen für den Mail.Read-Bereich angefordert.

    {
      "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
      "solution": {
        //...
    
        "webApiPermissionRequests": [
          {
            "resource": "Microsoft Graph",
            "scope": "Mail.Read"
          }
        ]
    
        //...
      }
    }
    

Aktualisieren von Code zum Aufrufen von Microsoft Graph

In diesem Fall wird der Code geändert, um Microsoft Graph für den Zugriff auf die letzten fünf E-Mail-Nachrichten des aktuellen Benutzers zu verwenden.

  1. Öffnen Sie ./src/webparts/helloWorld/MyFirstGraphWebPartWebPart.ts.

  2. Fügen Sie die folgenden import-Anweisungen nach den vorhandenen import-Anweisungen oben in der Datei hinzu:

    import { MSGraphClient } from '@microsoft/sp-http';
    import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
    
  3. Aktualisieren Sie die Methode render() wie folgt. Wie Sie sehen, verwenden wir das MSGraphClient-Objekt für die Microsoft Graph-Aufrufe. Dieses Objekt abstrahiert die Zugriffstokenverarbeitung, sodass Sie als Entwickler sich auf Ihre Geschäftslogik konzentrieren können.

    public render(): void {
      this.context.msGraphClientFactory
      .getClient()
      .then((client: MSGraphClient): 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 class="${ styles.container}">
            <div class="${ styles.row}">
              <div class="${ styles.column}">
                <span class="${ styles.title}">Welcome to SharePoint!</span>
                <p class="${ styles.subTitle}">Use Microsoft Graph in SharePoint Framework.</p>
                <div id="spListContainer" />
              </div>
            </div>
          </div>
          </div>`;
    
          // List the latest emails based on what we got from the Graph
          this._renderEmailList(messages.value);
    
        });
      });
    }
    
  4. Verwenden Sie auch folgende Hilfsprogramm-Funktion, um den E-Mail-Inhalt unmittelbar nach der vorhandenen render()-Methode zu rendern. Beachten Sie, wie wir die MicrosoftGraph.Message-Typen verwenden, um bei der Nutzung der API-Antwortdaten eine bessere Entwicklungsumgebung zu erhalten.

    private _renderEmailList(messages: MicrosoftGraph.Message[]): void {
      let html: string = '';
      for (let index = 0; index < messages.length; index++) {
        html += `<p class="${styles.description}">Email ${index + 1} - ${escape(messages[index].subject)}</p>`;
      }
    
      // Add the emails to the placeholder
      const listContainer: Element = this.domElement.querySelector('#spListContainer');
      listContainer.innerHTML = html;
    }
    

Verpacken und Bereitstellen Ihres Webparts in SharePoint

  1. Führen Sie die nachfolgenden Befehle aus, um Ihre Lösung in einem Bundle zu verpacken. Dadurch wird ein Releasebuild des Projekts ausgeführt, indem eine dynamische Bezeichnung als Host-URL für Ihre Objekte verwendet wird.

    gulp bundle --ship
    
  2. Führen Sie die folgende Aufgaben aus, um Ihre Lösung zu packen. Dadurch wird ein aktualisiertes Paket graph-apis.sppkg auf dem Sharepoint/Lösungsordner erstellt.

    gulp package-solution --ship
    

Als Nächstes müssen Sie das Paket, das generiert wurde, im App-Katalog des Mandanten bereitstellen.

Hinweis

Wenn Sie nicht über einen App-Katalog verfügen, kann ein SharePoint Online-Administrator einen erstellen, indem er die Anweisungen in dieser Führungslinie befolgt: Verwenden des App-Katalogs für die Bereitstellung von benutzerdefinierten Business-Apps in Ihrer SharePoint Online-Umgebung.

  1. Gehen Sie zum Microsoft Office SharePoint Online-App-Katalog Ihres Mandanten.

  2. Laden Sie die Datei graph-apis.sppkg hoch oder ziehen Sie sie per Drag & Drop in den Anwendungskatalog.

    Hochladen der Lösung in den App-Katalog

    Dadurch wird das clientseitige Lösungspaket bereitgestellt. Da es sich um eine vollständig vertrauenswürdige clientseitige Lösung handelt, zeigt SharePoint ein Dialogfeld an und fordert Sie auf, der bereitzustellenden clientseitigen Lösung zu vertrauen.

    Beachten Sie, dass die Domänenliste in der Aufforderung SharePoint Online enthält. Dies ist der Fall, da der Inhalt, je nach Mandanteneinstellungen, entweder von dem Office 365 CDN oder dem App-Katalog bereitgestellt wird.

    Stellen Sie sicher, dass die Option Diese Lösung an allen Standorten der Organisation verfügbar machen ausgewählt ist, damit das Webpart einwandfrei im gesamten Mandanten verwendet werden kann.

    Beachten Sie die Aufforderung, zur API-Verwaltungsseite für genehmigte ausstehende Berechtigungen zu gehen, und die Liste der erforderlichen Berechtigungen, in diesem Fall Mail.Read für Microsoft Graph.

    Vertrauen der Bereitstellung der clientseitigen Lösung

  3. Wählen Sie Bereitstellen.

    Beachten Sie, dass Sie in der Spalte App-Paket-Fehlermeldung im App-Katalog überprüfen können, ob im Paket Ausnahmen oder Probleme enthalten sind.

Jetzt wird das Webpart bereitgestellt und über die Microsoft Office SharePoint Online-Websites automatisch zur Verfügung gestellt. Es ist jedoch wichtig zu wissen, dass das Webpart nicht ordnungsgemäß funktioniert, bis die angeforderten Berechtigungen genehmigt wurden.

Genehmigen der angeforderten Microsoft Graph-Berechtigungen

  1. Wechseln Sie zu den administrativen Benutzeroberflächen für SharePoint-Mandanten, die sich in https://{{tenant}}-admin.sharepoint.com befinden.

  2. Wechseln Sie zu Erweitert > API-Verwaltung im Menü links, um die aktuell ausstehenden Berechtigungsanforderungen anzuzeigen. Wie Sie sehen, steht die Anforderung für die Mail.Read-Berechtigung für Microsoft Graph zur Genehmigung aus.

    API-Verwaltung

  3. Wählen Sie die Zeile „Ausstehende Berechtigung“ aus und wählen Sie auf der Symbolleiste Genehmigen oder ablehnen aus.

    Genehmigen oder ablehnen

  4. Überprüfen Sie die angeforderte Berechtigung im linken Bereich und wählen Sie Genehmigen aus.

    Genehmigen

Wichtig

Das Konto, das für die Erteilung der erforderlichen Berechtigungen verwendet wird, muss ein Mandantenadministrator sein. Die SharePoint-Administratorberechtigung reicht nicht aus, da der Vorgang derzeit für den dem Mandanten zugeordneten Azure Active Directory-Mandanten ausgeführt wird.

Jetzt sind die für das Webpart erforderlichen Berechtigungen genehmigt worden und wir können die Funktionalität testen.

Verwenden des Webparts in SharePoint

  1. Wechseln Sie zu einer Website, auf der Sie das Webpart testen möchten. Wir haben das Webpart mithilfe der Option „Mandantenweite Bereitstellung“ bereitgestellt, sodass es auf jeder beliebigen Website verfügbar ist.

  2. Erstellen Sie eine neue moderne Seite auf der Website, oder bearbeiten Sie eine bestehende Seite.

  3. Verwenden Sie den Suchausdruck Graph in der Auswahlfunktion für Webparts, um das Webpart zu finden:

    Auswahlfunktion für Webparts

  4. Wählen Sie MyFirstGraphWebPart aus der Liste aus und beachten Sie, wie das Webpart die neuesten fünf E-Mails des aktuellen Benutzers mithilfe von Informationen aus der Microsoft Graph-API rendert.

    Gerendertes Webpart

Siehe auch