Nutzen von Microsoft Graph in SharePoint-FrameworkConsume the Microsoft Graph in the SharePoint Framework

Die Verarbeitung von REST-APIs, die durch Azure Active Directory (Azure AD) und Open Authorization (OAuth 2.0) in einer clientseitigem SharePoint-Framework-Webpart oder einer Erweiterung gesichert sind, sind ein gängiges Geschäftsszenario auf Unternehmensebene.Consuming REST APIs secured with Azure Active Directory (Azure AD) and Open Authorization (OAuth 2.0) from within a SharePoint Framework client-side web part or extension is a common enterprise-level business scenario.

Sie können das SharePoint-Framework (ab v.1.4.1) verwenden, um Microsoft Graph REST-APIs oder eine beliebige andere REST-API zu verarbeiten, die in Azure AD registriert ist.You can use the SharePoint Framework (starting from v.1.4.1) to consume Microsoft Graph REST APIs, or any other REST API that's registered in Azure AD.

In diesem Artikel erfahren Sie, wie Sie eine SharePoint-Framework-Lösung erstellen können, die die Microsoft Graph-API mit einem benutzerdefinierten Satz von Berechtigungen verwendet.In this article, you'll learn how to create a SharePoint Framework solution that uses the Microsoft Graph API with a custom set of permissions. Eine konzeptionelle Übersicht über diese Technologie finden Sie unter Herstellen einer Verbindung mit durch Azure AD gesicherten APIs in SharePoint-Framework-Lösungen.For a conceptual overview of this technology, see Connect to Azure AD-secured APIs in SharePoint Framework solutions.

Wichtig

Sie können die Microsoft Graph-API mit Versionen von SharePoint-Framework vor V.1.4.1 nutzen, entweder über den nativen graphHttpClient oder über einen manuellen impliziten ADAL JS-OAuth-Fluss.You can consume the Microsoft Graph API with versions of SharePoint Framework earlier than v.1.4.1, either via the native graphHttpClient, or via a manual ADAL JS implicit OAuth flow. Der frühere Ansatz ist jedoch an einen vordefinierten Satz von Berechtigungen gebunden, die einige Einschränkungen beinhalten, und der zweite ist aus Entwicklungsperspektive recht komplex.However, the former approach is bound to a predefined set of permissions, which presents some limitations, and the latter is complex from a development perspective. Details zur Implementierung eines impliziten OAuth-Flusses finden Sie unter Herstellen einer Verbindung zu einer mit Azure Active Directory gesicherten API.For details about how to implement an implicit OAuth flow, see Connect to APIs secured with Azure Active Directory.

Die Lösung im ÜberblickSolution overview

In den Schritten in diesem Artikel wird veranschaulicht, wie Sie ein clientseitiges Webpart erstellen können, mit dem Benutzer im aktuellen Mandanten gesucht werden können, wie im folgenden Screenshot gezeigt.The steps in this article show you how to build a client-side web part that enables searching for users in the current tenant, as shown in the following screenshot. Die Suche basiert auf Microsoft Graph und erfordert mindestens die Berechtigung User.ReadBasic.All.The search is based on Microsoft Graph and requires at least the User.ReadBasic.All permission.

Ein clientseitiger Webpart, der ein Textfeld und eine Suchen-Schaltfläche für die Suche nach Benutzern innerhalb eines Mandanten enthält.

Mit dem clientseitigen Webpart können Sie anhand des Namens nach Benutzern suchen, außerdem werden alle übereinstimmenden Benutzer über eine DetailsList-Komponente der Office UI Fabric bereitgestellt.The client-side web part enables searching for users based on their name, and provides all the matching users through a DetailsList Office UI Fabric component. Das Webpart verfügt über eine Option im Eigenschaftenbereich, mit der ausgewählt werden kann, wie auf Microsoft Graph zugegriffen werden soll.The web part has an option in the property pane to choose how to access Microsoft Graph. Ab SharePoint-Framework V1.4.1 können Sie entweder mithilfe des nativen Graph-Client (MSGraphClient) oder über den allgemeinen Typ, der für den Zugriff auf mit Azure AD gesicherte REST-APIs verwendet wird (AadHttpClient), auf Microsoft Graph zugreifen.In versions of the SharePoint Framework starting with v.1.4.1, you can access Microsoft Graph by using either the native graph client (MSGraphClient), or the low-level type used to access any Azure AD-secured REST API (AadHttpClient).

Hinweis

Den Quellcode für diese Lösung finden Sie im GitHub-Repository api-scopes.To get the source code for this solution, see the api-scopes GitHub repo.

Wenn Sie bereits mit dem Erstellen von SharePoint-Framework-Lösungen vertraut sind, können Sie mit Konfigurieren der API-Berechtigungsanforderungen fortfahren.If you're already familiar with how to create SharePoint Framework solutions, you can proceed to Configure the API permissions requests.

Erstellen der ersten LösungCreate the initial solution

Wenn Sie eine ältere Version des SharePoint-Framework-Generators verwenden, müssen Sie ihn als Erstes auf Version 1.4.1 oder höher aktualisieren.If you have an old version of the SharePoint Framework generator, you need to update it to version 1.4.1 or later. Führen Sie dazu den folgenden Befehl aus, um die aktuellste Version des Pakets global zu installieren.To do that, run the following command to globally install the latest version of the package.

npm install -g @microsoft/generator-sharepoint

Erstellen Sie als Nächstes eine neue SharePoint Framework-Lösung:Next, create a new SharePoint Framework solution:

  1. Ersrtellen Sie einen Ordner in Ihrem Dateisystem.Create a folder in your file system. Speichern Sie den Quellcode der Lösung und verschieben Sie den aktuellen Pfad in diesen Ordner.You will store the solution source code and move the current path into this folder.

  2. Führen Sie den Yeoman-Generator aus, um eine neue Lösung mit einem Gerüst zu versehen.Run the Yeoman generator to scaffold a new solution.

    yo @microsoft/sharepoint
    
  3. Gehen Sie in Ihrer Lösung folgendermaßen vor:In your solution, do the following:

    • Geben Sie einen Namen für die Lösung an (z. B. spfx-api-scopes-tutorial).Provide a name for the solution (for example spfx-api-scopes-tutorial).
    • Wählen Sie als Ziel für die Lösung SharePoint Online only (latest).Target the solution for SharePoint Online only (latest).
    • Verwenden Sie den aktuellen Ordner.Use the current folder.
    • Entscheiden Sie, ob Sie die Lösung global auf dem Zielmandanten bereitstellen möchten.Decide whether you want to globally deploy the solution to the target tenant.
    • Wählen Sie das Erstellen eines Webparts aus.Choose to create a web part.
    • Nennen Sie das Webpart GraphConsumer.Call the web part GraphConsumer.
    • Geben Sie eine Beschreibung an.Provide a description.
    • Wählen Sie die Option, React als Entwicklungsframework zu verwenden.Choose to use React as the development framework.

    Die Benutzeroberfläche des Yeoman-Generators beim Erstellen des Gerüsts der SPFx-Lösung

  4. Starten Sie Visual Studio Code (oder Ihren bevorzugten Quellcode-Editor) im Kontext des aktuellen Ordners.Start Visual Studio Code (or your favorite code editor) within the context of the current folder.

    code .
    

Konfigurieren der grundlegenden WebpartelementeConfigure the base web part elements

Konfigurieren Sie als Nächstes die anfänglichen Elemente des clientseitigen Webparts.Next, configure the initial elements of the client-side web part.

Konfigurieren der benutzerdefinierten EigenschaftenConfigure the custom properties

  1. Erstellen Sie eine neue Quellcodedatei im Ordner src/webparts/graphConsumer/components der Lösung.Create a new source code file under the src/webparts/graphConsumer/components folder of the solution. Nennen Sie die neue Datei ClientMode.ts, und verwenden Sie sie, um ein TypeScript-enum-Element mit den verfügbaren Optionen für die ClientMode-Eigenschaft des Webparts zu deklarieren.Call the new file ClientMode.ts and use it to declare a TypeScript enum with the available options for the ClientMode property of the web part.

    export enum ClientMode {
      aad,
      graph,
    }
    
  2. Öffnen Sie die Datei GraphConsumerWebPart.ts im Ordner src/webparts/graphConsumer der Lösung.Open the GraphConsumerWebPart.ts file in the src/webparts/graphConsumer folder of the solution. Ändern Sie die Definition der IGraphConsumerWebPartProps-Schnittstelle so, dass ein Wert vom Typ ClientMode akzeptiert wird.Change the definition of the IGraphConsumerWebPartProps interface to accept a value of type ClientMode.

    export interface IGraphConsumerWebPartProps {
      clientMode: ClientMode;
    }
    
  3. Aktualisieren Sie die getPropertyPaneConfiguration()-Methode des clientseitigen Webparts, um die Auswahl im Eigenschaftenbereich zu unterstützen.Update the getPropertyPaneConfiguration() method of the client-side web part to support the choice selection in the property pane. Im folgenden Beispiel wird die neue Implementierung der Methode gezeigt.The following example shows the new implementation of the method.

    protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
      return {
        pages: [
          {
            header: {
              description: strings.PropertyPaneDescription
            },
            groups: [
              {
                groupName: strings.BasicGroupName,
                groupFields: [
                  PropertyPaneChoiceGroup('clientMode', {
                    label: strings.ClientModeLabel,
                    options: [
                      { key: ClientMode.aad, text: "AadHttpClient"},
                      { key: ClientMode.graph, text: "MSGraphClient"},
                    ]
                  }),
                ]
              }
            ]
          }
        ]
      };
    }
    
  4. Darüber hinaus müssen Sie die render-Methode des clientseitigen Webparts aktualisieren, um eine ordnungsgemäß konfigurierte Instanz der React-Komponente für das Rendern zu erstellen.In addition, you need to update the render method of the client-side web part to create a properly configured instance of the React component for rendering. Der folgenden Code zeigt die aktualisierte Methodendefinition.The following code shows the updated method definition.

    public render(): void {
      const element: React.ReactElement<IGraphConsumerProps > = React.createElement(
        GraphConsumer,
        {
          clientMode: this.properties.clientMode,
          context: this.context,
        }
      );
    
      ReactDom.render(element, this.domElement);
    }
    
  5. Damit dieser Code funktioniert, müssen Sie einige Importanweisungen am Anfang der Datei GraphConsumerWebPart.ts hinzufügen, wie im folgenden Beispiel gezeigt.For this code to work, you need to add some import statements at the beginning of the GraphConsumerWebPart.ts file, as shown in the following example. Beachten Sie den Import für das PropertyPaneChoiceGroup-Steuerelement sowie den Import der ClientMode-Enumeration.Note the import for the PropertyPaneChoiceGroup control, as well as the import of the ClientMode enum.

    import * as React from 'react';
    import * as ReactDom from 'react-dom';
    import { Version } from '@microsoft/sp-core-library';
    import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
    import {
      IPropertyPaneConfiguration,
      PropertyPaneChoiceGroup
    } from '@microsoft/sp-property-pane';
    
    import * as strings from 'GraphConsumerWebPartStrings';
    import GraphConsumer from './components/GraphConsumer';
    import { IGraphConsumerProps } from './components/IGraphConsumerProps';
    import { ClientMode } from './components/ClientMode';
    

Aktualisieren der RessourcenzeichenfolgenUpdate the resource strings

Um die Lösung zu kompilieren, müssen Sie die Datei mystrings.d.ts im Ordner src/webparts/graphConsumer/loc der Lösung aktualisieren.To compile the solution, you need to update the mystrings.d.ts file under the src/webparts/graphConsumer/loc folder of the solution.

  1. Sie müssen die Schnittstelle zur Definition der Ressourcenzeichenfolgen mit dem folgenden Codeauszug neu schreiben.Rewrite the interface that defines the resource strings with the following code.

    declare interface IGraphConsumerWebPartStrings {
      PropertyPaneDescription: string;
      BasicGroupName: string;
      ClientModeLabel: string;
      SearchFor: string;
      SearchForValidationErrorMessage: string;
    }
    
  2. Konfigurieren Sie geeignete Werte für die neu erstellten Ressourcenzeichenfolgen, indem Sie die Datei en-us.js in demselben Ordner aktualisieren.Configure proper values for the newly created resource strings by updating the en-us.js file within the same folder.

    define([], function() {
      return {
        "PropertyPaneDescription": "Description",
        "BasicGroupName": "Group Name",
        "ClientModeLabel": "Client Mode",
        "SearchFor": "Search for",
        "SearchForValidationErrorMessage": "Invalid value for 'Search for' field"
      }
    });
    

Aktualisieren der Formatvorlage für das clientseitige WebpartUpdate the style for the client-side web part

Außerdem müssen Sie die SCSS-Formatvorlagendatei aktualisieren.You also need to update the SCSS style file.

Öffnen Sie dazu die Datei GraphConsumer.module.scss im Ordner src/webparts/graphConsumer/components der Lösung.Open the GraphConsumer.module.scss under the src/webparts/graphConsumer/components folder of the solution. Fügen Sie die folgenden Formatvorlagenklassen direkt nach der .title-Klasse hinzu:Add the following style classes, right after the .title class:

.form {
  @include ms-font-l;
  @include ms-fontColor-white;
}

label {
  @include ms-fontColor-white;
}

Aktualisieren der React-Komponente, die das Webpart rendertUpdate the React component rendering the web part

Jetzt können Sie die React-Komponente GraphConsumer im Ordner src/webparts/graphConsumer/components der Lösung aktualisieren.Now you can update the GraphConsumer React component under the src/webparts/graphConsumer/components folder of the solution.

  1. Aktualisieren Sie die Datei IGraphConsumerProps.ts so, dass sie die von der Webpartimplementierung benötigten benutzerdefinierten Eigenschaften akzeptiert.Update the IGraphConsumerProps.ts file to accept the custom properties required by the web part implementation. Das folgenden Beispiel zeigt den aktualisierten Inhalt der Datei IGraphConsumerProps.ts.The following example shows the updated content of the IGraphConsumerProps.ts file. Beachten Sie den Import der ClientMode-Enumerationsdefinition sowie den Import des WebPartContext-Typs.Notice the import of the ClientMode enum definition, as well as the import of the WebPartContext type. Er wird später verwendet.You will use that later.

    import { WebPartContext } from '@microsoft/sp-webpart-base';
    import { ClientMode } from './ClientMode';
    
    export interface IGraphConsumerProps {
      clientMode: ClientMode;
      context: WebPartContext;
    }
    
  2. Erstellen Sie eine neue Schnittstelle zum Speichern des Zustands der React-Komponente.Create a new interface to hold the React component state. Erstellen Sie eine neue Datei im Ordner src/webparts/graphConsumer/components, und nennen Sie IGraphConsumerState.ts.Create a new file in the src/webparts/graphConsumer/components folder, and call it IGraphConsumerState.ts. Im Folgenden sehen Sie die Schnittstellendefinition.The following is the interface definition.

    import { IUserItem } from './IUserItem';
    
    export interface IGraphConsumerState {
      users: Array<IUserItem>;
      searchFor: string;
    }
    
  3. Definieren Sie die IUserItem-Schnittstelle (in einer Datei namens IUserItem.ts im Ordner src/webparts/graphConsumer/components).Define the IUserItem interface (within a file called IUserItem.ts stored in the src/webparts/graphConsumer/components folder). Diese Schnittstelle wird in die Statusdatei importiert.That interface is imported in the state file. Die Schnittstelle dient zum Definieren der Gliederung der Benutzer, die aus dem aktuellen Mandanten abgerufen und an die DetailsList auf der Benutzeroberfläche gebunden werden.The interface is used to define the outline of the users retrieved from the current tenant and bound to the DetailsList in the UI.

    export interface IUserItem {
      displayName: string;
      mail: string;
      userPrincipalName: string;
    }
    
  4. Aktualisieren Sie die Datei GraphConsumer.tsx.Update the GraphConsumer.tsx file. Fügen Sie zuerst einige Importanweisungen hinzu, um die zuvor definierten Typen zu importieren.First, add some import statements to import the types you defined earlier. Beachten Sie den Import für IGraphConsumerProps, IGraphConsumerState, ClientMode und IUserItem.Notice the import for IGraphConsumerProps, IGraphConsumerState, ClientMode, and IUserItem. Darüber hinaus gibt es einige Importe für die Office UI Fabric-Komponenten, mit denen die Benutzeroberfläche der React-Komponente gerendert wird.There are also some imports for the Office UI Fabric components used to render the UI of the React component.

    import * as React from 'react';
    import styles from './GraphConsumer.module.scss';
    import * as strings from 'GraphConsumerWebPartStrings';
    import { IGraphConsumerProps } from './IGraphConsumerProps';
    import { IGraphConsumerState } from './IGraphConsumerState';
    import { ClientMode } from './ClientMode';
    import { IUserItem } from './IUserItem';
    import { escape } from '@microsoft/sp-lodash-subset';
    
    import {
      autobind,
      PrimaryButton,
      TextField,
      Label,
      DetailsList,
      DetailsListLayoutMode,
      CheckboxVisibility,
      SelectionMode
    } from 'office-ui-fabric-react';
    
    import { AadHttpClient, MSGraphClient } from "@microsoft/sp-http";
    
  5. Definieren Sie nach den Importen die Gliederung der Spalten für die DetailsList-Komponente der Office UI Fabric.After the imports, define the outline of the columns for the DetailsList component of Office UI Fabric.

    // Configure the columns for the DetailsList component
    let _usersListColumns = [
      {
        key: 'displayName',
        name: 'Display name',
        fieldName: 'displayName',
        minWidth: 50,
        maxWidth: 100,
        isResizable: true
      },
      {
        key: 'mail',
        name: 'Mail',
        fieldName: 'mail',
        minWidth: 50,
        maxWidth: 100,
        isResizable: true
      },
      {
        key: 'userPrincipalName',
        name: 'User Principal Name',
        fieldName: 'userPrincipalName',
        minWidth: 100,
        maxWidth: 200,
        isResizable: true
      },
    ];
    

    Dieses Array wird in den Einstellungen der DetailsList-Komponente verwendet, wie Sie in der render()-Methode der React-Komponente sehen können.This array is used in the settings of the DetailsList component, as you can see in the render() method of the React component.

  6. Ersetzen Sie diese Komponente durch folgenden Code.Replace this component with the following code.

    public render(): React.ReactElement<IGraphConsumerProps> {
      const { clientMode } = this.props;
      return (
        <div className={ styles.graphConsumer }>
          <div className={ styles.container }>
            <div className={ styles.row }>
              <div className={ styles.column }>
                <span className={ styles.title }>Search for a user!</span>
                <p className={ styles.form }>
                  <TextField 
                      label={ strings.SearchFor } 
                      required={ true } 
                      value={ this.state.searchFor }
                      onChanged={ this._onSearchForChanged }
                      onGetErrorMessage={ this._getSearchForErrorMessage }
                    />
                </p>
                {
                  (clientMode === ClientMode.aad || clientMode === ClientMode.graph) ?
                    <p className={styles.form}>
                      <PrimaryButton
                        text='Search'
                        title='Search'
                        onClick={this._search}
                      />
                    </p>
                    : <p>Configure client mode by editing web part properties.</p>
                }
                {
                  (this.state.users != null && this.state.users.length > 0) ?
                    <p className={ styles.form }>
                    <DetailsList
                        items={ this.state.users }
                        columns={ _usersListColumns }
                        setKey='set'
                        checkboxVisibility={ CheckboxVisibility.hidden }
                        selectionMode={ SelectionMode.none }
                        layoutMode={ DetailsListLayoutMode.fixedColumns }
                        compact={ true }
                    />
                  </p>
                  : null
                }
              </div>
            </div>
          </div>
        </div>
      );
    }
    
  7. Aktualisieren Sie zudem die Typdeklaration der React-Komponente, und fügen Sie einen Konstruktor hinzu, wie im folgenden Beispiel gezeigt.Update the React component type declaration and add a constructor, as shown in the following example.

    export default class GraphConsumer extends React.Component<IGraphConsumerProps, IGraphConsumerState> {
    
      constructor(props: IGraphConsumerProps, state: IGraphConsumerState) {
        super(props);
    
        // Initialize the state of the component
        this.state = {
          users: [],
          searchFor: ""
        };
      }
    

    Es gibt einige Gültigkeitsprüfungsregeln und zu behandelnde Ereignisse, um in der TextField-Komponente die Suchkriterien zu sammeln.There are some validation rules and handling events for the TextField component to collect the search criteria. Im Folgenden werden die Methoden-Implementierungen gezeigt.The following are the method implementations.

    Fügen Sie diese beiden Methoden am Ende der Klasse GraphConsumer hinzu:Add these two methods to the end of the GraphConsumer class:

    @autobind
    private _onSearchForChanged(newValue: string): void {
    
      // Update the component state accordingly to the current user's input
      this.setState({
        searchFor: newValue,
      });
    }
    
    private _getSearchForErrorMessage(value: string): string {
      // The search for text cannot contain spaces
      return (value == null || value.length == 0 || value.indexOf(" ") < 0)
        ? ''
        : `${strings.SearchForValidationErrorMessage}`;
    }
    

    Die PrimaryButton löst eine _search()-Funktion aus, die bestimmt, welche Clienttechnologie verwendet wird, um Microsoft Graph zu verarbeiten.The PrimaryButton fires a _search() function, which determines what client technology to use to consume Microsoft Graph. Fügen Sie diese Methode am Ende der Klasse GraphConsumer hinzu:Add this method to the end of the GraphConsumer class:

    @autobind
    private _search(): void {
    
      console.log(this.props.clientMode);
    
      // Based on the clientMode value search users
      switch (this.props.clientMode)
      {
        case ClientMode.aad:
          this._searchWithAad();
          break;
        case ClientMode.graph:
          this._searchWithGraph();
          break;
      }
    }
    

Die DetailsList-Komponenteninstanz wird in der render()-Methode gerendert, falls die users-Eigenschaft des Komponentenzustands Elemente enthält.The DetailsList component instance is rendered in the render() method, in case there are items in the users property of the component's state.

Konfigurieren der API-BerechtigungsanforderungenConfigure the API permissions requests

Damit sowohl Microsoft Graph als auch andere Drittanbieter-REST-APIs verwendet werden können, müssen Sie im Manifest der Lösung explizit deklarieren, welche Berechtigungsanforderungen aus Sicht von OAuth bestehen.To consume Microsoft Graph or any other third-party REST API, you need to explicitly declare the permission requirements from an OAuth perspective in the manifest of your solution.

In SharePoint-Framework Version 1.4.1 oder höher können Sie dazu die webApiPermissionRequests-Eigenschaft in package-solution.json im Ordner config der Lösung konfigurieren.In the SharePoint Framework v.1.4.1 or later, you can do that by configuring the webApiPermissionRequests property in the package-solution.json under the config folder of the solution. Im Folgenden sehen Sie einen Beispielauszug der Datei für die aktuelle Lösung.The following example shows an excerpt of that file for the current solution.

Kopieren Sie die Deklaration der webApiPermissionRequests-Eigenschaft.Copy the declaration of the webApiPermissionRequests property.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-api-scopes-tutorial-client-side-solution",
    "id": "841cd609-d821-468d-a6e4-2d207b966cd8",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-api-scopes-tutorial.sppkg"
  }
}

Beachten Sie die webApiPermissionRequests-Eigenschaft, die ein Array von webApiPermissionRequest-Elementen darstellt.Notice the webApiPermissionRequests, which is an array of webApiPermissionRequest items. Jedes Element definiert die Ressource und den Bereich der Berechtigungsanforderung.Each item defines the resource and the scope of the permission request.

Die Ressource kann der Name oder die Objekt-ID (in Azure AD) der Ressource sein, für die Sie die Berechtigungsanforderung konfigurieren möchten.The resource can be the name or the ObjectId (in Azure AD) of the resource for which you want to configure the permission request. Für Microsoft Graph lautet der Name Microsoft Graph.For Microsoft Graph, the name is Microsoft Graph. Die ObjectId ist nicht eindeutig und variiert je nach Mandant.The ObjectId is not unique and varies on a per tenant basis.

Der Bereich kann der Name der Berechtigung oder die eindeutige ID der Berechtigung sein.The scope can be the name of the permission, or the unique ID of that permission. Den Berechtigungsnamen finden Sie in der API-Dokumentation.You can get the permission name from the API documentation. Die Berechtigungs-ID finden Sie in der API-Manifestdatei.You can get the permission ID from the API manifest file.

Hinweis

Eine Liste der Berechtigungen, die in Microsoft Graph zur Verfügung stehen, finden Sie unter Referenz zu Microsoft Graph-Berechtigungen.For a list of the permissions that are available in Microsoft Graph, see Microsoft Graph permissions reference.

Standardmäßig werden dem Dienstprinzipal keine expliziten Berechtigungen zum Zugriff auf Microsoft Graph erteilt.By default, the service principal has no explicit permissions granted to access Microsoft Graph. Wenn Sie jedoch ein Zugriffstoken für Microsoft Graph anfordern, erhalten Sie ein Token mit der user_impersonation-Berechtigung, die Sie zum Lesen von Informationen über Benutzer (User.Read.All) verwenden können.However, if you request an access token for Microsoft Graph, you get a token with the user_impersonation permission that you can use to read information about the users (User.Read.All). Sie können zusätzliche Berechtigungen von Mandantenadministratoren anfordern.You can request additional permissions to be granted by tenant administrators. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit durch Azure AD gesicherten APIs in SharePoint-Framework-Lösungen.For more information, see Connect to Azure AD-secured APIs in SharePoint Framework solutions.

Für die Suche nach Benutzern und zum Abrufen ihrer displayName, mail und userPrincipalName-Angaben genügt die Berechtigung User.ReadBasic.All.The User.ReadBasic.All permission is sufficient for searching for users and getting their displayName, mail, and userPrincipalName.

Wenn Sie Ihre Lösung packen und bereitstellen, müssen Sie (oder ein Administrator) die erforderlichen Berechtigungen für Ihre Lösung gewähren.When you package and deploy your solution, you (or an admin) will have to grant the requested permissions to your solution. Einzelheiten hierzu finden Sie unter Bereitstellen der Lösung und Gewähren von Berechtigungen.For details, see Deploy the solution and grant permissions.

Nutzen von Microsoft GraphConsume Microsoft Graph

Sie können jetzt die Methoden zur Nutzung von Microsoft Graph implementieren.You can now implement the methods to consume the Microsoft Graph. Sie haben zwei Möglichkeiten:You have two options:

  • Verwenden des AadHttpClient-ClientobjektsUse the AadHttpClient client object
  • Verwenden des MSGraphClient-ClientobjektsUse the MSGraphClient client object

Das AadHttpClient-Clientobjekt eignet sich für die Verarbeitung einer beliebigen REST-API.The AadHttpClient client object is useful for consuming any REST API. Daher können Sie hiermit Microsoft Graph- oder eine beliebige andere REST-API von einem Drittanbieter (oder Erstanbieter) nutzen.You can use it to consume Microsoft Graph or any other third-party (or first-party) REST API.

Das MSGraphClient-Clientobjekt kann nur Microsoft Graph verarbeiten.The MSGraphClient client object can consume the Microsoft Graph only. Es verwendet intern das AadHttpClient-Clientobjekt und unterstützt die Fluent-Syntax des Microsoft Graph-SDK.Internally it uses the AadHttpClient client object and supports the fluent syntax of the Microsoft Graph SDK.

Verwenden von AadHttpClientUsing AadHttpClient

Um eine REST-API mithilfe des AadHttpClient-Clientobjekts zu nutzen, erstellen Sie eine neue Instanz des Typs AadHttpClient, indem Sie die context.aadHttpClientFactory.getClient()-Methode aufrufen und den URI des Zieldiensts angeben.To consume any REST API using the AadHttpClient client object, create a new instance of the AadHttpClient type by calling the context.aadHttpClientFactory.getClient() method and providing the URI of the target service.

Das erstellte Objekt stellt Methoden für die folgenden Anforderungen bereit:The object created provides methods to make the following requests:

  • get: führt eine HTTP GET-Anforderung ausget: makes an HTTP GET request
  • post: führt eine HTTP POST-Anforderung auspost: makes an HTTP POST request
  • fetch: stellt alle anderen Arten von HTTP-Anforderung, basierend auf den angegebenen HttpClientConfiguration- und IHttpClientOptions-Argumenten.fetch: makes any other kind of HTTP request, based on the HttpClientConfiguration and IHttpClientOptions arguments provided.

Alle diese Methoden das asynchrone Entwicklungsmodell von JavaScript/TypeScript unterstützen, können Sie ihre Ergebnisse mit Zusagen behandeln.Because all these methods support the asynchronous development model of JavaScript/TypeScript, you can handle their result with promises.

Das folgende Beispiel zeigt die _searchWithAad()-Methode für die Beispiellösung.The following example shows the _searchWithAad() method of the sample solution.

private _searchWithAad(): void {

  // Log the current operation
  console.log("Using _searchWithAad() method");

  // Using Graph here, but any 1st or 3rd party REST API that requires Azure AD auth can be used here.
  this.props.context.aadHttpClientFactory
    .getClient('https://graph.microsoft.com')
    .then((client: AadHttpClient) => {
      // Search for the users with givenName, surname, or displayName equal to the searchFor value
      return client
        .get(
          `https://graph.microsoft.com/v1.0/users?$select=displayName,mail,userPrincipalName&$filter=(givenName%20eq%20'${escape(this.state.searchFor)}')%20or%20(surname%20eq%20'${escape(this.state.searchFor)}')%20or%20(displayName%20eq%20'${escape(this.state.searchFor)}')`,
          AadHttpClient.configurations.v1
        );
    })
    .then(response => {
      return response.json();
    })
    .then(json => {

      // Prepare the output array
      var users: Array<IUserItem> = new Array<IUserItem>();

      // Log the result in the console for testing purposes
      console.log(json);

      // Map the JSON response to the output array
      json.value.map((item: any) => {
        users.push( {
          displayName: item.displayName,
          mail: item.mail,
          userPrincipalName: item.userPrincipalName,
        });
      });

      // Update the component state accordingly to the result
      this.setState(
        {
          users: users,
        }
      );
    })
    .catch(error => {
      console.error(error);
    });
}

Die get()-Methode ruft die URL der OData-Anforderung als Eingabeargument ab.The get() method gets the URL of the OData request as the input argument. Eine erfolgreiche Anforderung gibt in der Antwort ein JSON-Objekt zurück.A successful request returns a JSON object with the response.

Verwenden von MSGraphClientUsing MSGraphClient

Wenn Sie Microsoft Graph als Ziel verwenden, können Sie das MSGraphClient-Clientobjekt nutzen, das eine flüssigere Syntax bereitstellt.If you are targeting Microsoft Graph, you can use the MSGraphClient client object, which provides a more fluent syntax.

Das folgende Beispiel zeigt die Implementierung der _searchWithAad()-Methode für die Beispiellösung.The following example shows the implementation of the _searchWithGraph() method of the sample solution.

private _searchWithGraph(): void {

  // Log the current operation
  console.log("Using _searchWithGraph() method");

  this.props.context.msGraphClientFactory
    .getClient()
    .then((client: MSGraphClient): void => {
      // From https://github.com/microsoftgraph/msgraph-sdk-javascript sample
      client
        .api("users")
        .version("v1.0")
        .select("displayName,mail,userPrincipalName")
        .filter(`(givenName eq '${escape(this.state.searchFor)}') or (surname eq '${escape(this.state.searchFor)}') or (displayName eq '${escape(this.state.searchFor)}')`)
        .get((err, res) => {  

          if (err) {
            console.error(err);
            return;
          }

          // Prepare the output array
          var users: Array<IUserItem> = new Array<IUserItem>();

          // Map the JSON response to the output array
          res.value.map((item: any) => {
            users.push( { 
              displayName: item.displayName,
              mail: item.mail,
              userPrincipalName: item.userPrincipalName,
            });
          });

          // Update the component state accordingly to the result
          this.setState(
            {
              users: users,
            }
          );
        });
    });
}

Sie erhalten eine Instanz des Typs MSGraphClient, indem Sie die context.msGraphClientFactory.getClient()-Methode aufrufen.You get an instance of the MSGraphClient type by calling the context.msGraphClientFactory.getClient() method.

Sie verwenden dann die Fluent-API des Microsoft Graph-SDK, um die OData-Abfrage zu definieren, die für den Microsoft Graph-Zielendpunkt ausgeführt wird.You then use the fluent API of the Microsoft Graph SDK to define the OData query that runs against the target Microsoft Graph endpoint.

Das Ergebnis ist eine JSON-Antwort, die Sie decodieren und dem typisierten Ergebnis zuordnen müssen.The result is a JSON response that you have to decode and map to the typed result.

Hinweis

Sie können einen vollständig typisierten Ansatz unter Nutzung der Microsoft Graph-TypeScript-Typen verwenden.You can use a fully typed approach by using the Microsoft Graph TypeScript types.

Bereitstellen der Lösung und Gewähren von BerechtigungenDeploy the solution and grant permissions

Jetzt sind Sie bereit, die Lösung zu erstellen, zu bündeln, zu packen und bereitzustellen.You're now ready to build, bundle, package, and deploy the solution.

  1. Führen Sie die gulp-Befehle aus, um sicherzustellen, dass die Lösung korrekt erstellt wird.Run the gulp commands to verify that the solution builds correctly.

    gulp build
    
  2. Führen Sie den folgenden Befehl aus, um die Lösung zu bündeln und zu packen.Use the following command to bundle and package the solution.

    gulp bundle
    gulp package-solution
    
  3. Navigieren Sie zum App-Katalog Ihres Zielmandanten, und laden Sie das Lösungspaket hoch.Browse to the app catalog of your target tenant and upload the solution package. Sie finden das Lösungspaket im Ordner sharepoint/solution der Lösung.You can find the solution package under the sharepoint/solution folder of your solution. Es ist die .sppkg-Datei.It is the .sppkg file. Nachdem Sie das Lösungspaket hochgeladen haben, erhalten Sie vom App-Katalog eine Eingabeaufforderung in Form eines Dialogfelds, das folgendem Screenshot ähnelt.After you upload the solution package, the app catalog prompts you with a dialog box, similar to the one shown in the following screenshot.

    Screenshot der App-Katalog-UI beim Hochladen der Paketlösung

    Eine Meldung im unteren Bereich des Bildschirms besagt, dass für das Lösungspaket Berechtigungen genehmigt werden müssen.A message in the lower part of the screen tells you that the solution package requires permissions approval. Dies liegt an der webApiPermissionRequests-Eigenschaft in der Datei package-solution.json.This is because of the webApiPermissionRequests property in the package-solution.json file.

  4. Öffnen Sie das SharePoint Admin Center für Ihren Mandanten, und wählen Sie in der rechten oberen Ecke des Bildschirms Vorschau testen aus.Open the SharePoint Admin Center of your tenant, and in the upper-right corner of the screen, choose Try the preview.

    Screenshot des Links „Neues SharePoint Admin Center testen“

  5. Wählen Sie im neuen Admin Center im linken Schnellstartmenü das Menüelement API-Verwaltung aus.In the new Admin Center, in the left quick launch menu, choose the API management menu item. Die Seite sollte nun etwa wie folgt aussehen.You will see a page similar to the following.

    Screenshot der Seite „WebApiPermission-Verwaltung“

    Auf dieser Seite können Sie (oder ein anderer Administrator Ihres SharePoint Online-Mandanten) alle ausstehenden Berechtigungsanforderungen genehmigen oder verweigern.Using this page, you (or any other admin of your SharePoint Online tenant) can approve or deny any pending permission request. Beachten Sie, dass Sie hier nicht erkennen können, welches Lösungspaket welche Berechtigung anfordert, da die Berechtigungen auf Mandantenebene und für eine eindeutige Anwendung definiert sind.Note that you don't see which solution package is requesting which permission because the permissions are defined at the tenant level and for a unique application.

    Hinweis

    Weitere Informationen zur internen Funktionsweise der Berechtigungsbereiche auf Mandantenebene finden Sie in den Artikeln im Abschnitt Siehe auch.For more information about how the tenant-level permission scopes work internally, see the articles in the See also section.

  6. Wählen Sie die Berechtigung, die Sie in der Datei package-solution.json Ihrer Lösung angefordert haben, wählen die Option Genehmigen oder Zugriff verweigern, und wählen Sie dann Genehmigen.Choose the permission that you requested in the package-solution.json file of your solution, choose Approve or reject access, and then choose Approve. Im folgenden Screenshot wird der Bereich in der Administrator-Benutzeroberfläche dargestellt.The following screenshot shows the panel in the Admin UI.

    Screenshot der Verwaltungsseite für WebApiPermission während des Genehmigungsprozesses

Und jetzt können Sie loslegen!And you're now ready to go.

Warnung

Wenn Sie bei dem Versuch, die Berechtigung zu genehmigen, eine unerwartete Ausnahme erhalten ([HTTP]:400 - [CorrelationId]), aktualisieren Sie das resource-Attribut in der Datei package-solution.json so, dass der Wert Microsoft.Azure.AgregatorService anstatt Microsoft Graph verwendet wird, wie zu einem früheren Zeitpunkt in diesem Lernprogramm angewiesen.If you are getting an unexpected exception when trying to approve the permission ([HTTP]:400 - [CorrelationId]), update the resource attribute in your package-solution.json to use the value Microsoft.Azure.AgregatorService rather than Microsoft Graph, which was instructed earlier in this tutorial. Lehnen Sie die vorhandene Anforderung ab und aktualisieren Sie das Lösungspaket im App-Katalog mit dem aktualisierten Wert.Reject the existing request and update the solution package in the app catalog with the update value.

Testen der LösungTest the solution

  1. Führen Sie die Lösung mithilfe des folgenden gulp-Befehls aus.Run your solution by using the following gulp command.

    gulp serve --nobrowser
    
  2. Öffnen Sie den Browser, und navigieren Sie zur Seite mit der SharePoint-Framework Workbench, die unter der folgenden URL zu finden ist:Open the browser and go to the following URL to go to the SharePoint Framework Workbench page:

    https://<your-tenant>.sharepoint.com/_layouts/15/Workbench.aspx
    
  3. Fügen Sie das clientseitige Webpart GraphConsumer hinzu, konfigurieren Sie Client Mode, und suchen Sie nach Benutzern.Add the GraphConsumer client-side web part, configure the Client Mode, and search for users.

    Wenn Sie Ihre erste Anforderung vornehmen, wird ein Popupfenster angezeigt und anschließend wieder ausgeblendet.When you make your first request, you will see a pop-up window appear and disappear. Das ist das Anmeldefenster von ADAL JS, das vom SharePoint-Framework intern zum Abrufen des Zugriffstokens von Azure AD mit einem internen OAuth-Fluss verwendet wird.That's the sign-in window used by ADAL JS, which is used internally by the SharePoint Framework to get the access token from Azure AD by using an OAuth implicit flow.

    Screenshot der Benutzeroberfläche der Beispielanwendung

Und das war‘s!And that's it! Sie können jetzt Lösungen auf Unternehmensniveau erstellen, die REST-APIs verwenden, die mithilfe von Azure Active Directory gesichert sind.Now you can build enterprise-level solutions that use Azure AD-secured REST APIs.

Weitere ArtikelSee also