Verwenden von Postman mit Microsoft Graph Connectors-API
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.All
wird 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.All
wird 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:
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.
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.
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 deny
zu konvertieren. Deny
hat 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.