Verwenden von MSGraphClientV3 zum Herstellen einer Verbindung mit Microsoft Graph

  • Artikel

Wenn Sie SharePoint-Framework Lösungen erstellen, können Sie mithilfe von MSGraphClientV3 problemlos eine Verbindung mit Microsoft Graph herstellen.

MSGraphClient-Übersicht

MSGraphClientV3 ist ein neuer HTTP-Client, der in SharePoint-Framework v1.15.0 eingeführt wurde und die Verbindung mit Microsoft Graph innerhalb SharePoint-Framework Lösungen vereinfacht. MSGraphClientV3 umschließt die Microsoft Graph-JavaScript-Clientbibliothek v3 und bietet Entwicklern die gleichen Funktionen wie bei der Verwendung der Clientbibliothek in anderen clientseitigen Lösungen.

MSGraphClientV3 ersetzt MSGraphClient, das in SharePoint-Framework v1.6.0 eingeführt wurde. MSGraphClient hat die Microsoft Graph JavaScript-Clientbibliothek v1 umschlossen.

Während Sie die Microsoft Graph-JavaScript-Clientbibliothek direkt in Ihrer Lösung verwenden könnten, übernimmt MSGraphClientV3 die Authentifizierung bei Microsoft Graph für Sie, sodass Sie sich auf die Erstellung Ihrer Lösung konzentrieren können.

Verwenden von MSGraphClient in einer Lösung

Hinweis

MSGraphClientV3 ist nur in Projekten verfügbar, die mit SharePoint-Framework v1.15.0 und höher erstellt wurden. MsGraphClientV3 wird in diesem Artikel mithilfe eines clientseitigen Webparts erläutert, Sie können es aber auch in SharePoint-Framework Extensions verwenden.

Hinweis

Das einmalige Anmelden für MSGraphClientV3 ist derzeit nur in SharePoint Online verfügbar. Sie können den Client für Entwicklungen vor Ort nutzen, aber Ihre Benutzer werden aufgefordert, sich innerhalb des Webparts erneut anzumelden.

  1. Um MSGraphClientV3 in Ihrer SharePoint-Framework-Lösung zu verwenden, fügen Sie die folgende import Klausel in Ihrer Hauptwebpartdatei hinzu:

    import { MSGraphClientV3 } from '@microsoft/sp-http';

  2. MSGraphClientV3 wird über die MSGraphClientFactory verfügbar gemacht, die im Webpartkontext verfügbar ist. Fügen Sie in Ihrem Code Folgendes hinzu, um auf einen Verweis auf MSGraphClient abzurufen:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // use MSGraphClient here
      });
  }

  // ...
}

  3. Nachdem Sie über den Verweis auf die MSGraphClientV3-Instanz verfügen, beginnen Sie mit der Kommunikation mit Microsoft Graph, indem Sie dessen JavaScript-Clientbibliothekssyntax verwenden:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  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')
          .get((error, response: any, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

Verwenden der Microsoft Graph-TypeScript-Typen

Bei der Arbeit mit Microsoft Graph und TypeScript können Sie die Microsoft Graph-TypeScript-Typen verwenden, um Fehler in Ihrem Code schneller zu erkennen. Die Microsoft Graph-TypeScript-Typen werden als separates Paket bereitgestellt.

  1. Installieren der Microsoft Graph-TypeScript-Typen:

    npm install @microsoft/microsoft-graph-types --save-dev

  2. Nach der Installation des Pakets in Ihrem Projekt importieren Sie es in der Webpartdatei:

    import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';

  3. Geben Sie die von Microsoft Graph abgerufenen Objekte ein. Beispiel:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  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')
          .get((error: any, user: MicrosoftGraph.User, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

Verfügbare Berechtigungsbereiche

Standardmäßig werden dem Dienstprinzipal keine expliziten Berechtigungen zum Zugriff auf Microsoft Graph erteilt. Wenn Sie jedoch ein Zugriffstoken für Microsoft Graph anfordern möchten, dann erhalten Sie ein Token mit dem Berechtigungsbereich user_impersonation, das zum Lesen von Informationen über die Benutzer verwendet werden kann (d. h. User.Read.All).

Zusätzliche Berechtigungsbereiche können von Entwicklern angefordert und von Mandantenadministratoren gewährt werden. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit durch Azure AD gesicherten APIs in SharePoint-Framework-Lösungen.

Bekannte Probleme

Azure AD-Rollen mit delegierter Authentifizierung

Der MSGraphClient verwendet zurzeit den impliziten Authentifizierungsverlauf, wenn delegierte Berechtigungen von Microsoft Graph angefordert werden. Wie in den Zugriffstoken der Microsoft Identity Platform angegeben, ist der wids Anspruch bei der Verwendung des impliziten Authentifizierungsflusses aus Gründen der Länge möglicherweise nicht vorhanden. Der wids-Anspruch enthält die Liste der Azure AD-Mandantenrollen, die dem delegierten Benutzer zugewiesen wurden.

Dies führt dazu, dass Abfragen an Microsoft Graph-Endpunkten, die auf Azure AD-Rollen basieren, auch bei delegierten Berechtigungen fehlschlagen können, weil wids-Anspruch nicht vorhanden ist. Zum Zeitpunkt der Abfassung dieses Artikels umfasst dies die folgenden Endpunkte:

Siehe auch