Verwenden von Microsoft Graph in Ihrer LösungUse Microsoft Graph in your solution

Microsoft Graph bietet ein einheitliches Programmierbarkeitsmodell, das Sie verwenden können, um Apps für Organisationen und Consumer zu erstellen, die mit den Daten von Millionen Benutzern interagieren.Microsoft Graph provides a unified programmability model that you can use to build apps for organizations and consumers that interact with the data of millions of users. Sie können ganz einfach auch von SharePoint-Framework-Lösungen aus auf Microsoft Graph zugreifen.You can easily access Microsoft Graph also from SharePoint Framework solutions.

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:Before you start, complete the procedures in the following articles to ensure that you understand the basic flow of creating a custom client-side web part:

Sie können die nachfolgend beschriebene Anleitung auch anhand dieses Videos in unserem YouTube-Kanal „SharePoint Patterns & Practices“ nachvollziehen:You can also follow these steps by watching this video on the SharePoint PnP YouTube Channel:

Erstellen eines SharePoint-Framework-Projekts für die Microsoft Graph-NutzungCreate a SharePoint Framework project for Microsoft Graph usage

  1. Erstellen Sie an einem Speicherort Ihrer Wahl ein neues Projektverzeichnis:Create a new project directory in your favorite location:

    md graph-apis
    
  2. Wechseln Sie in das Projektverzeichnis:Go to the project directory:

    cd graph-apis
    
  3. Führen Sie den Yeoman-SharePoint-Framework-Generator aus, um eine neue Lösung zu erstellen:Create a new solution by running the Yeoman SharePoint Framework Generator:

    yo @microsoft/sharepoint
    
  4. Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Werte ein (wählen Sie für alle unten nicht aufgeführten Eingabeaufforderungen die Standardoption aus):When prompted, enter the following values (select the default option for all prompts omitted below):

    • Wie lautet der Name Ihrer Lösung?: graph-apisWhat is your solution name?: graph-apis
    • 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? JaDo you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites?: Yes
    • **Welcher Typ von clientseitiger Komponente soll erstellt werden? **: WebPartWhich type of client-side component to create?: WebPart
    • Wie lautet der Name Ihres Webparts?: MyFirstGraphWebPartWhat is your Web part name?: MyFirstGraphWebPart
    • Welches Framework möchten Sie verwenden?: Kein JavaScript-FrameworkWhich framework would you like to use?: No JavaScript framework

    An diesem Punkt installiert Yeoman die erforderlichen Abhängigkeiten und erstellt ein Gerüst für die Lösungsdateien.At this point, Yeoman installs the required dependencies and scaffolds the solution files. Die Erstellung der Lösung kann einige Minuten dauern.Creation of the solution might take a few minutes. Yeoman erstellt ein Gerüst für das Projekt, um auch das MyFirstGraphWebPart-Webpart einzuschließen.Yeoman scaffolds the project to include your MyFirstGraphWebPart web part as well.

  5. Geben Sie als Nächstes Folgendes ein, um das Webpart-Projekt in Visual Studio Code zu öffnen:Next, enter the following to open the web part project in Visual Studio Code:

    code .
    

Einschließen von Microsoft Graph-Typen zur einfacheren TypeScript-EntwicklungIncluding Microsoft Graph types for easier TypeScript development

  1. Geben Sie in der Konsole Folgendes ein, um Microsoft Graph-Typdeklarationen zu installieren, um die Entwicklungsumgebung zu verbessern.In the console, enter the following to install Microsoft Graph type declarations to improve development experience

    npm install @microsoft/microsoft-graph-types
    

Aktualisieren des Lösungsmanifests mit den erforderlichen Microsoft Graph-BerechtigungsanforderungenUpdating solution manifest with the needed Microsoft Graph permissions requests

Bei Verwendung von SharePoint-Framework müssen Sie keine eigenen Azure Active Directory-Anwendungen erstellen, um die Berechtigungen für Ihre Lösungen zu verwalten.By using SharePoint Framework, you don't need to explicitly create Azure Active Directory applications to manage your permissions for your solutions. Stattdessen können Sie die erforderlichen Berechtigungen in Ihrem Lösungspaket anfordern, und der Microsoft 365-Mandantenadministrator kann die angeforderten Berechtigungen dann generell für alle Lösungen oder für diese spezifische Lösung (isolierte Lösung) gewähren.Instead, you can request the needed permissions in your solution package, and Microsoft 365 tenant administrator can then grant the requested permissions in general for all solutions or for this specific solution (isolated solution).

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.Tenant administrators can also manage the API permissions using PowerShell cmdlets, so there's no requirement to have the permissions included in the solution package.

In diesem Fall fügen wir die lösungsspezifischen Berechtigungen in das Paket ein.In this case, we'll include the solution-specific permissions in the package.

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

  2. Aktualisieren Sie den Lösungsabschnitt, um die Anfrage zur Berechtigungserteilung wie im folgenden Codeabschnitt gezeigt durch Verwendung des webApiPermissionRequests-Elements aufzunehmen.Update the solution section to include permission grant request as shown in the following code section by using webApiPermissionRequests element. 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.In this case, we'll access user's emails, so we have requested permissions for the Mail.Read scope.

    {
      "$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 GraphUpdate code to call 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.In this case, we'll modify the code to use Microsoft Graph to get access on the current user's last five emails.

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

  2. Fügen Sie die folgenden import-Anweisungen nach den vorhandenen import-Anweisungen oben in der Datei hinzu:Add the following import statements after the existing import statements at the top fo the file:

    import { MSGraphClient } from '@microsoft/sp-http';
    import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
    
  3. Aktualisieren Sie die Methode render() wie folgt.Update the render() method as follows. Wie Sie sehen, verwenden wir das MSGraphClient-Objekt für die Microsoft Graph-Aufrufe.Notice how we're using the MSGraphClient object for the Microsoft Graph calls. Dieses Objekt abstrahiert die Zugriffstokenverarbeitung, sodass Sie als Entwickler sich auf Ihre Geschäftslogik konzentrieren können.This object abstracts the access token handling, so that as a developer, you can concentrate on your business logic.

    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.Include also following helper function to render the email content immediately after the existing render() method. Beachten Sie, wie wir die MicrosoftGraph.Message-Typen verwenden, um bei der Nutzung der API-Antwortdaten eine bessere Entwicklungsumgebung zu erhalten.Notice how we're using the MicrosoftGraph.Message types to give us better development experience as accessing the API response data.

    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 SharePointPackage and deploying your web part to SharePoint

  1. Führen Sie die nachfolgenden Befehle aus, um Ihre Lösung in einem Bundle zu verpacken.Execute the following commands to build bundle your solution. Dadurch wird ein Freigabebuild des Projekts ausgeführt, indem eine dynamische Bezeichnung als Host-URL für Ihre Objekte verwendet wird.This executes a release build of your project by using a dynamic label as the host URL for your assets.

    gulp bundle --ship
    
  2. Führen Sie die folgende Aufgaben aus, um Ihre Lösung zu packen.Execute the following task to package your solution. Dadurch wird ein aktualisiertes Paket graph-apis.sppkg auf dem Sharepoint/Lösungsordner erstellt.This creates an updated graph-apis.sppkg package on the sharepoint/solution folder.

    gulp package-solution --ship
    

Als Nächstes müssen Sie das Paket, das generiert wurde, im App-Katalog des Mandanten bereitstellen.Next, you need to deploy the package that was generated to the tenant App Catalog.

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.If you don't have an app catalog, a SharePoint Online Admin can create one by following the instructions in this guide: Use the App Catalog to make custom business apps available for your SharePoint Online environment.

  1. Gehen Sie zum Microsoft Office SharePoint Online-App-Katalog Ihres Mandanten.Go to your tenant's SharePoint App Catalog.

  2. Laden Sie die Datei graph-apis.sppkg hoch oder ziehen Sie sie per Drag & Drop in den Anwendungskatalog.Upload or drag and drop the graph-apis.sppkg into the App Catalog.

    Hochladen der Lösung in den App-Katalog

    Dadurch wird das clientseitige Lösungspaket bereitgestellt.This deploys the client-side solution package. 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.Because this is a full trust client-side solution, SharePoint displays a dialog and asks you to trust the client-side solution to deploy.

    Beachten Sie, dass die Domänenliste in der Aufforderung SharePoint Online enthält.Notice how the domain list in the prompt says SharePoint Online. Dies ist der Fall, da der Inhalt, je nach Mandanteneinstellungen, entweder von dem Office 365 CDN oder dem App-Katalog bereitgestellt wird.This is because the content is either served from the Office 365 CDN or from the App Catalog, depending on the tenant settings.

    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.Ensure that the Make this solution available to all sites in the organization option is selected, so that the web part can be used easily across the tenant.

    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.Notice the request to go to API Management Page to approved pending permissions and the list of required permissions, in this case being Mail.Read for Microsoft Graph.

    Vertrauen der Bereitstellung der clientseitigen Lösung

  3. Wählen Sie Bereitstellen.Select Deploy.

    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.Notice that you can see if there's any exceptions or issues in the package by looking the App Package Error Message column in the App Catalog.

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.Now the web part is deployed and is automatically available cross the SharePoint Online sites, it's however important to realize that the web part won't work properly until the requested permissions have been approved.

Genehmigen der angeforderten Microsoft Graph-BerechtigungenApprove the requested Microsoft Graph permissions

  1. Navigieren Sie zu den administrativen Benutzeroberflächen für SharePoint-Mandanten, die sich unter https://-admin.sharepoint.com befinden.Move to the SharePoint tenant administrative UIs located at https://-admin.sharepoint.com.

  2. Wechseln Sie zu Erweitert > API-Verwaltung im Menü links, um die aktuell ausstehenden Berechtigungsanforderungen anzuzeigen.Move to Advanced > API management in the left menu option to see the currently pending permission requests. Wie Sie sehen, steht die Anforderung für die Mail.Read-Berechtigung für Microsoft Graph zur Genehmigung aus.Notice that the request for Mail.Read permission for Microsoft Graph is pending for approval.

    API-Verwaltung

  3. Wählen Sie die Zeile „Ausstehende Berechtigung“ aus und wählen Sie auf der Symbolleiste Genehmigen oder ablehnen aus.Select the pending permission row and choose Approve or reject from the toolbar

    Genehmigen oder ablehnen

  4. Überprüfen Sie die angeforderte Berechtigung im linken Bereich und wählen Sie Genehmigen aus.Review the requested permission in the left panel and choose Approve

    Genehmigen

Wichtig

Das Konto, das für die Erteilung der erforderlichen Berechtigungen verwendet wird, muss ein Mandantenadministrator sein.The account used for granting the requested permissions will need to be a tenant administrator. Die SharePoint-Administratorberechtigung reicht nicht aus, da der Vorgang derzeit für den dem Mandanten zugeordneten Azure Active Directory-Mandanten ausgeführt wird.The SharePoint administrator permission isn't sufficient as the operation is actually performed on the tenant's associated Azure Active Directory tenant.

Jetzt sind die für das Webpart erforderlichen Berechtigungen genehmigt worden und wir können die Funktionalität testen.At this point, the requested permissions needed for the web part have been approved and we can test the functionality.

Verwenden des Webparts in SharePointUse web part in SharePoint

  1. Wechseln Sie zu einer Website, auf der Sie das Webpart testen möchten.Go to a site where you want to test the web part. Wir haben das Webpart mithilfe der Option „Mandantenweite Bereitstellung“ bereitgestellt, sodass es auf jeder beliebigen Website verfügbar ist.We did deploy web part using the tenant scoped deployment option, so it will be available on any site.

  2. Erstellen Sie eine neue moderne Seite auf der Website, oder bearbeiten Sie eine bestehende Seite.Create a new modern page to the site or edit existing page.

  3. Verwenden Sie den Suchausdruck Graph in der Auswahlfunktion für Webparts, um das Webpart zu finden:Use search term Graph in the web part picker to find your web part:

    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.Choose MyFirstGraphWebPart from the list and notice how the web part renders the latest five emails from the current user using information from the Microsoft Graph API

    Auswahlfunktion für Webparts

Siehe auchSee also