Verwenden von Postman mit Microsoft Graph Connectors-API

Artikel
03/15/2023
7 Minuten Lesedauer

Postman ist eine API-Plattform für die Erstellung und Nutzung von APIs. Postman vereinfacht jeden Schritt des API-Lebenszyklus und rationalisiert die Zusammenarbeit, damit Sie schneller bessere APIs erstellen können.

Dieser Artikel beschreibt, wie Sie die Microsoft Graph Connectors API mit Postman verwenden können.

Voraussetzungen

Entweder ein Microsoft-Konto oder ein Geschäfts- oder Schulkonto.
Zugriff auf einen Microsoft 365-Entwicklermandanten. Wenn Sie noch keines haben, können Sie sich für das Microsoft 365-Entwicklerprogramm registrieren, um ein kostenloses Entwicklerabonnement zu erhalten.

Schritt 1: Abzweigen der Microsoft Graph Postman-Sammlung

Um die Postman-Sammlung verwenden zu können, müssen Sie sie in Ihren Postman-Arbeitsbereich forken. Tun Sie dies über einen Webbrowser.

Wechseln Sie zu Postman, und melden Sie sich an. Wenn Sie bereits über ein Postman-Konto verfügen, können Sie sich anmelden.
Navigieren Sie nach der Anmeldung zur folgenden URL: https://www.postman.com/microsoftgraph/workspace/microsoft-graph/collection/455214-085f7047-1bec-4570-9ed0-3a7253be148 und wählen Sie die Microsoft Graph Sammlung aus.
Wählen Sie die drei Punkte rechts und dann Abzweigung erstellen aus.
Geben Sie im sich öffnenden Dialogfeld eine Bezeichnung ein, um Ihre Verzweigung zu identifizieren. Wählen Sie im Dropdownmenü ArbeitsbereichMein Arbeitsbereichaus und wählen Sie dann Fork Collectionaus.
Wechseln Sie zu Arbeitsbereiche>Mein Arbeitsbereich um die von Ihnen erstellte Abzweigung anzuzeigen. Den Ordner Microsoft Graph Connectors finden Sie unter Anwendung.

Schritt 2: Laden Sie den Postman-Agenten herunter (Optional - Nur Postman Webbrowser)

Laden Sie den Postman Desktop-Agent herunter, um diese Postman-Sammlung in Ihrem Webbrowser zu verwenden.

Sie können Postman für das Web aufgrund von CORS-Beschränkungen im Webbrowser nicht ohne dies verwenden: "Die maximale Anzahl von Verbindungs-Ressourcen pro Microsoft 365-Tenant".

Sie benötigen den Agenten nicht, wenn Sie die App „Postman für Windows“ verwenden. Wenn Sie Postman für Windows öffnen, wird diese Sammlung in Ihrem Arbeitsbereich angezeigt.

Schritt 3: Erstellen einer Azure AD-Anwendung

Um diese Sammlung in Ihrem eigenen Entwickler-Tenant zu verwenden, erstellen Sie eine Azure Active Directory (Azure AD)-Anwendung und erteilen ihr die entsprechenden Berechtigungen für die Anfragen, die Sie aufrufen möchten.

Wechseln Sie zu portal.azure.com, und melden Sie sich mit dem Administratorkonto Ihres Entwickler-Mandanten an.
Wählen Sie unter Azure-Dienste die Option Azure Active Directory aus.
Klicken Sie im linken Menü auf App-Registrierungen.
Klicken Sie im horizontalen Menü auf Neue Registrierung.
Legen Sie den Anwendungsnamen auf Parts Inventory fest.
Legen Sie die Umleitungs-URI auf https://oauth.pstmn.io/v1/browser-callback fest.
Wählen Sie Registrieren aus.
Wählen Sie im linken Menü API-Berechtigungen aus.
Wählen Sie im horizontalen Menü Berechtigung> hinzufügendelegierte Microsoft Graph-Berechtigungen> oder Anwendungsberechtigungen aus.
Beginnen Sie mit External der Eingabe, und wählen Sie die delegierten Oder Anwendungsberechtigungen aus, die für die aufgerufene API erforderlich sind. Suchen Sie in der Referenz zu Graphberechtigungen nach Suchberechtigungen, um weitere Informationen zu erhalten.
Wählen Sie Berechtigungen hinzufügen aus.
Wählen Sie im horizontalen MenüAdministratorzustimmung erteilen und dann Jaaus.
Klicken Sie im linken Menü auf Übersicht. Von hier aus können Sie dieAnwendungs-ID (Client) und dieVerzeichnis-ID (Mandant)abrufen. Sie benötigen diese in Schritt 4.
Wählen Sie im linken MenüZertifikate und Geheimnisse aus.
Wählen Sie Neuen geheimen Clientschlüsselaus, geben Sie eine Beschreibung ein und wählen Sie dann Hinzufügen aus. Kopieren Sie den neuen Wert für den geheimen Clientschlüssel; Sie benötigen diesen in Schritt 4.

In der Anwendung sind nun zwei Berechtigungen konfiguriert. ExternalItem.ReadWrite.Allwird als delegierte Berechtigung hinzugefügt. Dies ist eine Berechtigung, die einen angemeldeten Benutzer erfordert. Die Anwendung kann externe Objekte im Namen des Benutzers lesen/schreiben. ExternalItem.ReadWrite.Allwird als Anwendungsberechtigung hinzugefügt, d.h. eine Berechtigung, für die kein angemeldeter Benutzer erforderlich ist. Die Anwendung kann externe Objekte in ihrem eigenen Namen lesen/schreiben.

Schritt 4: Konfigurieren der Authentifizierung

In diesem Schritt richten Sie die Umgebungsvariablen in Postman ein, die Sie zum Abrufen eines Zugriffstokens verwenden.

Wählen Sie die Registerkarte Microsoft Graph und gehen Sie zum Abschnitt Variablen.
Geben Sie im AbschnittVariablendie erforderlichen Informationen an, indem Sie die Informationen aus Schritt 3 verwenden:
- Legen Sie den aktuellen Wert der Mandanten auf den Verzeichnis-ID-Wert (Mandant) aus Schritt 3.15 fest.
- Legen Sie den aktuellen Wert von client_id auf den Anwendungs-ID-Wert (Client) aus Schritt 3.15 fest.
- Legen Sie den aktuellen Wert von client_secret auf den Wert des geheimen Clientschlüssels aus Schritt 3.17 fest.
- Legen Sie den aktuellen Wert von userName auf admin@xxxxxxx.onmicrosoft.com.
- Setzen Sie den Aktuellen Wert des Kennworts auf das Administratorkennwort des Mandanten.
Wählen Sie Speichern / Aktualisieren aus.

Schritt 5: Abrufen eines Authentifizierungstokens

Sie müssen das Zugriffstoken abrufen, da Sie zum ersten Mal eine Anforderung als Anwendungsauthentifizierungsablauf ausführen. Sie können das Zugriffstoken mit der folgenden POST-Anforderung abrufen:

Screenshot des Abschnitts

Das folgende Beispiel zeigt, wie Sie ein Zugriffstoken mit einem gemeinsamen geheimen Schlüssel erhalten:

POST /{{tenant}}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id={{client_id}} 
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default 
&client_secret={{client_secret}} 
&grant_type=client_credentials

Das folgende Beispiel zeigt eine erfolgreiche Antwort:

{ 
    "token_type": "Bearer", 
    "expires_in": 3599, 
    "ext_expires_in": 3599, 
    "access_token": "eyJ0eXAiOiJKV1QiLCJu… " 
}

Hinweis

Sie verwenden hier den Client Credential Flow. Stellen Sie sicher, dass Sie ein App-Zugriffstoken und kein Benutzerzugriffstoken erhalten.

Schritt 6: Erstellen einer neuen Verbindung

Eine Verbindung ist ein logischer Container für Ihre externen Daten, den Sie als einzelne Einheit verwalten können. Wählen Sie einen Verbindungsnamen, eine Beschreibung und eine ID aus. Erhalten Sie die erforderlichen Details vom Administrator, um eine Verbindung zur Datenquelle herzustellen, und stellen Sie einen Mechanismus zur Autorisierung für die Inhaltsquelle bereit, wenn Sie die Verbindung herstellen. Sie können das Microsoft Graph SDK und die APIs verwenden, um Ihr Connector-Setup zu programmieren. Wenn Sie Anmeldeinformationen speichern möchten, können Sie Azure Key Vault verwenden.

POST /external/connections

Nachfolgend sehen Sie ein Beispiel der Anforderung.

POST https://graph.microsoft.com/beta/external/connections 
Content-type: application/json 

{ 
  "id": "contosotasks", 
  "name": "Contoso Tasks", 
  "description": "Connection to index Contoso task management system" 
}

Nachfolgend sehen Sie ein Beispiel der Antwort.

HTTP/1.1 201 Created 
Content-type: application/json 
 
{ 
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#connections/$entity", 
    "id": "contosotasks", 
    "name": "Contoso Tasks", 
    "description": "Connection to index Contoso task management system", 
    "state": null, 
    "configuration": { 
        "authorizedApps": [ 
            "a47b35b7-6271-4e6d-9e27-2450a8b9c6b6" 
        ] 
    } 
}

Im Folgenden sehen Sie einen Screenshot des Abschnitts Verbindung erstellen.

Screenshot des Abschnitts

Schritt 7: Verbindungsschema registrieren

Das Verbindungsschema bestimmt, wie Ihre Inhalte in verschiedenen Microsoft Graph-Anwendungen verwendet werden. Das Schema ist eine flache Liste aller Eigenschaften, die Sie der Verbindung zusammen mit ihren Attributen, Bezeichnungen und Aliasen hinzufügen möchten. Sie müssen das Schema registrieren, bevor Sie Elemente zur Verbindung hinzufügen können.

POST /external/connections/{id}/schema

Nachfolgend sehen Sie ein Beispiel der Anforderung.

POST https://graph.microsoft.com/beta/external/connections/contosotasks/schema 
Content-type: application/json 
Prefer: respond-async 

{ 
  "baseType": "microsoft.graph.externalItem", 
  "properties": [ 
    { 
"name": "title", 
      "type": "String", 
      "isSearchable": "true", 
"isQueryable": "true", 
      "isRetrievable": "true", 
      "labels": [ 
        "title" 
      ] 
    }, 
    { 
"aliases": "creator", 
      "name": "createdBy", 
      "type": "String", 
      "isSearchable": "true", 
"isQueryable": "true", 
      "isRetrievable": "false", 
"isRefinable": "false", 
      "labels": [ 
        "createdBy" 
      ] 
    }, 
    { 
"aliases": "editedDate", 
      "name": "lastEditedDate", 
      "type": "DateTime", 
      "isSearchable": "false", 
"isQueryable": "true", 
      "isRetrievable": "true", 
"isRefinable": "true", 
      "labels": [ 
   "lastModifiedDateTime" 
] 
    } 
  ] 
}

Nachfolgend sehen Sie ein Beispiel der Antwort.

HTTP/1.1 202 Accepted 
Location: https://graph.microsoft.com/beta/external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Hinweis

Das Registrieren des Verbindungsschemas ist ein asynchroner Vorgang. Nehmen Sie daher keine Elemente in die Verbindung auf, bis sich das Verbindungsschema im Status "Abgeschlossen" befindet. Führen Sie die folgende Anforderung aus, um den Status des Verbindungsschemas zu überprüfen:

GET /external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Das Folgende ist ein weiteres Beispiel für eine Anforderung.

Request 
GET https://graph.microsoft.com/beta/external/connections/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Nachfolgend sehen Sie ein Beispiel der Antwort.

HTTP/1.1 200 OK 
Content-type: application/json 

{
    @odata.context":"https://graph.microsoft.com/beta/$metadata#external/connections('coursecatalog')/operations/$entity", 
    "id": "aa9186d2-893c-4361-ca51-431d88fa45d8", 
    "name": "Contoso Tasks", 
    "status": "inprogress", 
    "error": null  
}

Im Folgenden sehen Sie einen Screenshot des Abschnitts Status des Verbindungsvorgangs abrufen.

Screenshot des Abschnitts

Nachdem sich der Status des Verbindungsschemavorgangs von InProgress in Abgeschlossen geändert hat, können Sie Elemente für die Verbindung aufnehmen.

Nachdem sich der Verbindungsstatus von Entwurf zu Bereit geändert hat, können Sie Elemente in die aktuelle Verbindung aufnehmen.

Schritt 8: Hinzufügen eines externen Gruppenmitglieds (optional)

Wenn Ihr externer Dienst Zugriffskontrolllisten (ACLs) verwendet, die nicht zu Azure AD gehören, synchronisieren Sie diese Berechtigungen.

Externe Gruppen (zusammen mit Azure Active Directory-Benutzern und -Gruppen) werden verwendet, um Berechtigungen für externalItems festzulegen, die einer Microsoft Graph-Verbindung hinzugefügt werden. Weitere Informationen finden Sie unter externalGroup.

Nachfolgend ist ein Beispiel einer Anforderung dargestellt.

POST https://graph.microsoft.com/beta/external/connections/contosotasks/groups/31bea3d537902000/members 
Content-Type: application/json 
 
{ 
  "@odata.type": "#microsoft.graph.externalGroupMember", 
  "id": "1431b9c38ee647f6a", 
  "type": "group", 
  "identitySource": "external" 
}

Dies ist ein Beispiel für die Antwort.

HTTP/1.1 201 Created 
Content-Type: application/json 

{ 
  "@odata.type": "#microsoft.graph.externalGroupMember", 
  "id": "14m1b9c38qe647f6a", 
  "type": "group", 
  "identitySource": "external" 
}

Schritt 9: Erfassen von Elementen

Nachdem Sie eine Verbindung hergestellt haben, können Sie Ihre Inhalte hinzufügen. Jedes Element aus Ihrer Datenquelle muss als externalItem in Microsoft Graph mit einer eindeutigen Element-ID dargestellt werden. Diese ID wird verwendet, um das Element in Microsoft Graph zu erstellen, zu aktualisieren oder zu löschen. Sie können den Primärschlüssel aus Ihrer Datenquelle als itemId verwenden oder ihn aus einem oder mehreren Feldern ableiten. Ein externalItem besteht aus drei Schlüsselkomponenten: Zugriffssteuerungsliste, Eigenschaften und Inhalt.

Wenn Sie über Binärdateien verfügen, müssen Sie diese analysieren, um die Metadaten und eine Textversion des Inhalts abzurufen. Wenn Sie Nicht-Text-Inhalte wie eine PDF- oder BMP-Datei haben, müssen Sie die Objektzeichenerkennung verwenden, um Inhalte in Text zu konvertieren.

Sie sind dafür verantwortlich, Ihre Quellberechtigungen in grant oder denyzu konvertieren. Denyhat höheren Vorrang vorgrant.

Nachfolgend ist ein Beispiel für eine Anforderung dargestellt.

PUT https://graph.microsoft.com/beta/external/connections/contosohr/items/TSP228082938 
Content-type: application/json 

{ 
  "@odata.type": "microsoft.graph.externalItem", 
  "acl": [ 
    { 
      "type": "user", 
      "value": "e811976d-83df-4cbd-8b9b-5215b18aa874", 
      "accessType": "grant", 
      "identitySource": "azureActiveDirectory" 
    }, 
    { 
      "type": "group", 
      "value": "14m1b9c38qe647f6a", 
      "accessType": "deny", 
      "identitySource": "external" 
    } 
  ], 
  "properties": { 
    "ticketID": "1158", 
    "priority": 1, 
    "title": "Filter design", 
  }, 
  "content": { 
    "value": "Build filtering capability by...", 
    "type": "text" 
  } 
}

Es folgt ein Beispiel für eine erfolgreiche Antwort.

HTTP/1.1 200 OK

Fehlerbehandlung

Ausführliche Informationen zum Beheben von Fehlern finden Sie unter Microsoft Graph-Autorisierungsfehler.

Siehe auch

Verwenden von Postman mit Microsoft Graph-API

Verwenden von Postman mit Microsoft Graph Connectors-API

Voraussetzungen

Schritt 1: Abzweigen der Microsoft Graph Postman-Sammlung

Schritt 2: Laden Sie den Postman-Agenten herunter (Optional - Nur Postman Webbrowser)

Schritt 3: Erstellen einer Azure AD-Anwendung

Schritt 4: Konfigurieren der Authentifizierung

Schritt 5: Abrufen eines Authentifizierungstokens

Schritt 6: Erstellen einer neuen Verbindung

Schritt 7: Verbindungsschema registrieren

Schritt 8: Hinzufügen eines externen Gruppenmitglieds (optional)

Schritt 9: Erfassen von Elementen

Fehlerbehandlung

Siehe auch

Zusätzliche Ressourcen

Zusätzliche Ressourcen