Teilen über

Senden von Anforderungen an die Azure Digital Twins-APIs mithilfe von Postman

  • Artikel

Postman ist ein REST-Testtool, das wichtige HTTP-Anforderungsfunktionen in einer desktop- und pluginbasierten grafischen Benutzeroberfläche bietet. Sie können es zum Erstellen von HTTP-Anforderungen verwenden und diese an die REST-APIs von Azure Digital Twins übermitteln. In diesem Artikel wird beschrieben, wie Sie den Postman-REST-Client für die Interaktion mit den Azure Digital Twins-APIs konfigurieren. Diese Informationen gelten speziell für den Azure Digital Twins-Dienst.

Dieser Artikel enthält Informationen zu den folgenden Schritten:

  1. Verwenden Sie die Azure CLI, um ein Bearertoken zu erhalten, das Sie für API-Anforderungen in Postman verwenden können.
  2. Richten Sie eine Postman-Sammlung ein, und konfigurieren Sie den Postman-REST-Client, um das Bearertoken für die Authentifizierung zu verwenden. Beim Einrichten der Sammlung können Sie eine der folgenden Optionen auswählen:
    1. Importieren einer vorgefertigte Sammlung von Azure Digital Twins-API-Anforderungen.
    2. Erstellen Ihrer von Grund auf neuen eigenen Sammlung.
  3. Hinzufügen von Anforderungen zu Ihrer konfigurierten Sammlung und Senden dieser an die Azure Digital Twins-APIs.

Azure Digital Twins bietet zwei Sätze von APIs, mit denen Sie arbeiten können: Datenebene und Steuerungsebene. Weitere Informationen zu den Unterschieden zwischen diesen APIs finden Sie unter Azure Digital Twins-APIs und -SDKs. Dieser Artikel enthält Informationen für beide API-Sätze.

Voraussetzungen

Sie müssen eine Azure Digital Twins-Instanz einrichten und Postman herunterladen, um Postman weiterhin für den Zugriff auf die Azure Digital Twins-APIs zu verwenden. Im restlichen Teil dieses Abschnitts werden diese Schritte beschrieben.

Einrichten einer Azure Digital Twins-Instanz

Damit Sie in diesem Artikel mit Azure Digital Twins arbeiten können, benötigen Sie eine Azure Digital Twins-Instanz und die erforderlichen Berechtigungen, um sie zu verwenden. Wenn Sie über eine bereits eingerichtete Azure Digital Twins-Instanz verfügen, können Sie diese nutzen und zum nächsten Abschnitt springen. Befolgen Sie andernfalls die Anleitung unter Einrichten einer Instanz und der Authentifizierung. Die Anweisungen enthalten Informationen, mit denen Sie überprüfen können, ob jeder Schritt erfolgreich abgeschlossen wurde.

Notieren Sie sich nach dem Einrichten Ihrer Instanz den Hostnamen der Instanz. Sie finden den Hostnamen im Azure-Portal.

Herunterladen von Postman

Als Nächstes laden Sie die Desktopversion des Postman-Clients herunter.

Abrufen des Bearertokens

Nachdem Sie Postman und die Azure Digital Twins-Instanz eingerichtet haben, müssen Sie ein Bearertoken abrufen, das von Postman-Anforderungen zur Autorisierung mit den Azure Digital Twins-APIs verwendet werden kann.

Es gibt mehrere Möglichkeiten, dieses Token abzurufen. In diesem Artikel wird die Azure CLI verwendet, um sich bei Ihrem Azure-Konto anzumelden und ein Token zu erhalten.

Wenn Sie eine Azure CLI lokal installiert haben, können Sie eine Eingabeaufforderung auf Ihrem Computer starten, um die folgenden Befehle auszuführen. Andernfalls können Sie ein Azure Cloud Shell-Fenster im Browser öffnen und dort die Befehle ausführen.

  1. Stellen Sie zunächst sicher, dass Sie mit den entsprechenden Anmeldeinformationen bei Azure angemeldet sind, indem Sie den folgenden Befehl ausführen:

    az login

  2. Verwenden Sie als Nächstes den Befehl az account get-access-token, um ein Bearertoken mit Zugriff auf den Azure Digital Twins-Dienst abzurufen. In diesem Befehl übergeben Sie die Ressourcen-ID für den Azure Digital Twins-Dienstendpunkt, um ein Zugriffstoken zu erhalten, das auf Azure Digital Twins-Ressourcen zugreifen kann.

    Der erforderliche Kontext für das Token hängt vom verwendeten API-Satz ab. Verwenden Sie daher die folgenden Registerkarten, um zwischen den APIs der Datenebene und denen der Steuerungsebene auszuwählen.

    Um ein Token für die APIs der Datenebene abzurufen, verwenden Sie den folgenden statischen Wert für den Tokenkontext: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Dieser Wert ist die Ressourcen-ID für den Azure Digital Twins-Dienstendpunkt.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Hinweis

    Wenn Sie mit einem Dienstprinzipal oder Benutzerkonto, der bzw. das zu einem anderen Microsoft Entra-Mandanten als dem der Instanz gehört, auf Ihre Azure Digital Twins-Instanz zugreifen müssen, müssen Sie ein Token vom Basismandanten der Azure Digital Twins-Instanz anfordern. Weitere Informationen zu diesem Prozess finden Sie unter Schreiben von Authentifizierungscode für die Client-App.

  3. Kopieren Sie den Wert accessToken in das Ergebnis, und speichern Sie ihn für die Verwendung im nächsten Abschnitt. Dieser Wert ist Ihr Tokenwert, den Sie dem Postman-Tool bereitstellen, um Ihre Anforderungen zu autorisieren.

    Screenshot: Konsole mit dem Ergebnis des Befehls „az account get-access-token“. Das accessToken-Feld mit hervorgehobener Beispielwert

Tipp

Dieses Token ist für mindestens 5 Minuten und höchstens 60 Minuten gültig. Wenn die für das aktuelle Token zugewiesene Zeit abgelaufen ist, können Sie die Schritte in diesem Abschnitt wiederholen, um ein neues Token zu erhalten.

Als Nächstes richten Sie Postman so ein, dass dieses Token für API-Anforderungen an Azure Digital Twins verwendet wird.

Informationen zu Postman-Sammlungen

Anforderungen in Postman werden in Sammlungen (Gruppen von Anforderungen) gespeichert. Wenn Sie eine Sammlung erstellen, um Ihre Anforderungen zu gruppieren, können Sie allgemeine Einstellungen auf viele Anforderungen gleichzeitig anwenden. Allgemeine Einstellungen können die Autorisierung erheblich vereinfachen, wenn Sie planen, mehrere Anforderungen für die Azure Digital Twins-APIs zu erstellen, da Sie diese Details nur einmal für die gesamte Sammlung konfigurieren müssen.

Wenn Sie mit Azure Digital Twins arbeiten, können Sie zunächst eine vorgefertigte Sammlung aller Azure Digital Twins-Anforderungen importieren. Sie können diese Sammlung importieren, wenn Sie die APIs erkunden und schnell ein Projekt mit Anforderungsbeispielen einrichten möchten.

Alternativ dazu können Sie auch ganz von vorn beginnen, indem Sie eine eigene leere Sammlung erstellen und sie mit einzelnen Anforderungen auffüllen, die nur die benötigten APIs aufrufen.

In den folgenden Abschnitten werden beide Vorgehensweisen beschrieben. Der weitere Verlauf dieses Artikels bezieht sich auf Ihre lokale Postman-Anwendung. Öffnen Sie daher jetzt die Postman-Anwendung auf Ihrem Computer.

Importieren einer Sammlung von Azure Digital Twins-APIs

Eine schnelle Einstiegsmöglichkeit für Azure Digital Twins in Postman besteht darin, eine vorgefertigte Sammlung von Anforderungen für die APIs zu importieren. Führen Sie die folgenden Schritte aus, um eine Sammlung beliebter Datenebenen-API-Anforderungen für Azure Digital Twins zu importieren, die Beispielanforderungsdaten enthalten.

  1. Wählen Sie im Hauptfenster von Postman die Schaltfläche Import aus. Screenshot eines neu geöffneten Postman-Fensters. Die Schaltfläche „Import“ ist hervorgehoben.

  2. Wählen Sie im nachfolgenden Fenster Importieren die Option Link aus, und geben Sie die folgende URL ein: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Wählen Sie dann Importieren aus, um zu bestätigen.

    Screenshot des Postman-Fensters „Import“, das die als Sammlung zu importierende Datei und die Schaltfläche „Import“ zeigt.

Die neu importierte Sammlung kann jetzt in der Hauptansicht von Postman auf der Registerkarte „Collections“ (Sammlungen) angezeigt werden.

Screenshot des Hauptfensters von Postman. Die neu importierte Sammlung wird auf der Registerkarte „Collections“ (Sammlungen) hervorgehoben.

Tipp

Um den vollständigen API-Aufrufssatz für eine bestimmte Version der Azure Digital Twins-APIs zu importieren – einschließlich denen Steuerungsebene oder Datenebene –, können Sie auch Swagger-Dateien als Sammlungen importieren. Links zu den Swagger-Dateien für die Steuerungsebenen- und Datenebenen-APIs finden Sie unter Azure Digital Twins-APIs und -SDKs.

Fahren Sie anschließend mit dem nächsten Abschnitt fort, um der Sammlung ein Bearertoken für die Autorisierung hinzuzufügen und es mit ihrer Azure Digital Twins-Instanz zu verbinden.

Konfigurieren der Autorisierung

Bearbeiten Sie als Nächstes die erstellte Sammlung, um einige Zugriffsdetails zu konfigurieren. Markieren Sie die von Ihnen erstellte Sammlung, und wählen Sie das Symbol Weitere Aktionen anzeigen aus, um die Optionen anzuzeigen. Wählen Sie Bearbeiten aus.

Screenshot von Postman. Das Symbol „Weitere Aktionen anzeigen“ für die importierte Sammlung ist hervorgehoben, und in den Optionen ist „Edit“ (Bearbeiten) markiert.

Gehen Sie folgendermaßen vor, um der Sammlung ein Bearertoken für die Autorisierung hinzuzufügen. Verwenden Sie den Tokenwert, den Sie im Abschnitt Abrufen des Bearertokens abgerufen haben, um ihn für alle API-Anforderungen in der Sammlung zu verwenden.

  1. Stellen Sie im Dialogfeld für Ihre Sammlung sicher, dass Sie sich auf der Registerkarte Authorization (Autorisierung) befinden.

    Screenshot des Bearbeitungsdialogfelds der importierten Sammlung in Postman mit der Registerkarte „Authorization“ (Autorisierung).

  2. Legen Sie den Typ auf OAuth 2.0 fest, und fügen Sie Ihr Zugriffstoken in das Feld „Zugriffstoken“ ein. Sie müssen das richtige Token für den verwendeten API-Typ nutzen, da es unterschiedliche Token für Datenebenen-APIs bzw. Steuerungsebene-APIs gibt. Wählen Sie Speichern.

    Screenshot des Postman-Bearbeitungsdialogfelds für die importierte Sammlung auf der Registerkarte „Authorization“ (Autorisierung). Der Typ lautet „OAuth 2.0“, und das Feld „Access Token“ (Zugriffstoken) ist hervorgehoben.

    Tipp

    Sie können die Tokenfreigabe aktivieren, wenn Sie das Token mit der Anforderung in der Postman-Cloud speichern und Ihr Token eventuell für andere freigeben möchten.

Andere Konfiguration

Sie können die Sammlung ganz einfach mit Ihren Azure Digital Twins-Ressourcen verbinden, indem Sie einige Variablen festlegen, die mit der Sammlung bereitgestellt werden. Wenn viele Anforderungen in einer Sammlung denselben Wert erfordern (z. B. den Hostnamen Ihrer Azure Digital Twins-Instanz), können Sie den Wert in einer Variablen speichern, die für jede Anforderung in der Sammlung gilt. Die Azure Digital Twins-Sammlung enthält vordefinierte Variablen, die Sie auf Sammlungsebene festlegen können.

  1. Wechseln Sie im Bearbeitungsdialogfeld für Ihre Sammlung zur Registerkarte Variables (Variablen).

  2. Verwenden Sie die folgende Tabelle, um die Werte der Variablen in der Sammlung festzulegen:

    Variable APIs Beschreibung
    digitaltwins-hostname Datenebene Der Hostname Ihrer Azure Digital Twins-Instanz Sie finden diesen Wert auf der Übersicht für Ihre Instanz im Portal.
    subscriptionId Steuerungsebene die Azure-Abonnement-ID
    digitalTwinInstance Steuerungsebene Der Name Ihrer Azure Digital Twins-Instanz

    Screenshot des Bearbeitungsdialogfelds der importierten Sammlung in Postman mit der Registerkarte „Variables“ (Variablen). Das Feld CURRENT VALUE (AKTUELLER WERT) ist hervorgehoben.

  3. Wenn Ihre Sammlung zusätzliche Variablen umfasst, füllen Sie auch diese Werte aus, und speichern Sie sie.

  4. Wählen Sie Speichern.

Nach Durchführung der obigen Schritte haben Sie die Konfiguration der Sammlung abgeschlossen. Wenn Sie möchten, können Sie die Bearbeitungsregisterkarte für die Sammlung schließen.

Erkunden von Anforderungen

Sehen Sie sich als Nächstes die Anforderungen in der Azure Digital Twins-API-Sammlung an. Sie können die Sammlung erweitern, um die vorab erstellten Anforderungen (nach Kategorie des Vorgangs sortiert) anzuzeigen.

Für unterschiedliche Anforderungen sind unterschiedliche Informationen zu Ihrer Instanz und den zugehörigen Daten erforderlich. Wenn Sie alle Informationen anzeigen möchten, die zum Erstellen einer bestimmten Anforderung erforderlich sind, suchen Sie in der Referenzdokumentation zur REST-API für Azure Digital Twins nach den Anforderungsdetails.

Mithilfe der folgenden Schritte können Sie die Details einer Anforderung in der Postman-Sammlung bearbeiten:

  1. Wählen Sie sie aus der Liste aus, um die bearbeitbaren Details zu öffnen.

  2. Die meisten Anforderungen in der Beispielsammlung sind vorkonfiguriert, um ausgeführt zu werden, ohne weitere Änderungen vorzunehmen.

  3. Der folgende Screenshot zeigt die DigitalTwinModels Add-API. Auf der Registerkarte Text sehen Sie die JSON-Nutzdaten, die das hinzuzufügende neue Modell definiert:

  4. Geben Sie Werte für die Variablen ein, die auf der Registerkarte Params (Parameter) unter Path Variables (Pfadvariablen) aufgelistet sind.

    Screenshot von Postman Die Sammlung wird erweitert, um die Registerkarte „Text“ einer Anforderung anzuzeigen.

  5. Verwenden Sie zum Ausführen der Anforderung die Schaltfläche Senden.

Mithilfe der im Abschnitt Hinzufügen einer eigenen Anforderung beschriebenen Vorgehensweise können Sie der Sammlung auch eigene Anforderungen hinzufügen.

Erstellen Ihrer eigenen Sammlung

Statt die vorhandene Sammlung an Azure Digital Twins-APIs zu importieren, können Sie auch eine eigene Sammlung erstellen. Anschließend können Sie sie gemäß der Referenzdokumentation zur REST-API für Azure Digital Twins mit eigenen Anforderungen auffüllen.

Postman-Sammlung erstellen

  1. Um eine Sammlung zu erstellen, wählen Sie im Hauptfenster von Postman die Schaltfläche New aus.

    Screenshot des Hauptfensters von Postman. Die Schaltfläche „New“ (Neu) ist hervorgehoben.

    Wählen Sie einen Typ für Collection (Sammlung) aus.

    Screenshot des Dialogfelds „Create New“ (Neu erstellen) in Postman. Die Option „Collection“ (Sammlung) ist hervorgehoben.

  2. Eine Registerkarte wird geöffnet. Füllen Sie die Details für die neue Sammlung aus. Wählen Sie das Bearbeitungssymbol neben dem Standardnamen der Sammlung (New Collection, neue Sammlung) aus, um ihn durch einen eigenen Namen zu ersetzen.

    Screenshot des Bearbeitungsdialogfelds der neuen Sammlung in Postman. Das Bearbeitungssymbol neben dem Namen „New Collection“ (Neue Sammlung) ist hervorgehoben.

Fahren Sie anschließend mit dem nächsten Abschnitt fort, um der Sammlung ein Bearertoken für die Autorisierung hinzuzufügen.

Konfigurieren der Autorisierung

Gehen Sie folgendermaßen vor, um der Sammlung ein Bearertoken für die Autorisierung hinzuzufügen. Verwenden Sie den Tokenwert, den Sie im Abschnitt Abrufen des Bearertokens abgerufen haben, um ihn für alle API-Anforderungen in der Sammlung zu verwenden.

  1. Wechseln Sie im Bearbeitungsdialogfeld für Ihre neue Sammlung zur Registerkarte Authorization (Autorisierung).

    Screenshot des Bearbeitungsdialogfelds der neuen Sammlung in Postman mit der Registerkarte „Authorization“ (Autorisierung).

  2. Legen Sie den Typ auf OAuth 2.0 fest, fügen Sie das Zugriffstoken im Feld „Access Token“ (Zugriffstoken) ein, und klicken Sie auf Save (Speichern).

    Screenshot des Postman-Bearbeitungsdialogfelds für die neue Sammlung auf der Registerkarte „Authorization“ (Autorisierung). Der Typ lautet „OAuth 2.0“, und das Feld „Access Token“ (Zugriffstoken) ist hervorgehoben.

Nach Durchführung der obigen Schritte haben Sie die Konfiguration der Sammlung abgeschlossen. Wenn Sie möchten, können Sie die Bearbeitungsregisterkarte für die neue Sammlung schließen.

Die neue Sammlung wird in der Hauptansicht von Postman auf der Registerkarte „Collections“ (Sammlungen) angezeigt.

Screenshot des Hauptfensters von Postman. Die neu erstellte benutzerdefinierte Sammlung wird auf der Registerkarte „Collections“ (Sammlungen) hervorgehoben.

Hinzufügen einer eigenen Anforderung

Nachdem Sie Ihre Sammlung eingerichtet haben, können Sie den Azure Digital Twin-APIs Ihre eigenen Anforderungen hinzufügen.

  1. Verwenden Sie noch einmal die Schaltfläche New (Neu), um eine Anforderung zu erstellen.

    Screenshot des Hauptfensters von Postman. Die Schaltfläche „New“ (Neu) ist hervorgehoben.

    Wählen Sie einen Typ für Request (Anforderung) aus.

    Screenshot des Dialogfelds „Create New“ (Neu erstellen) in Postman. Die Option „Request“ (Anforderung) ist hervorgehoben.

  2. Mit dieser Aktion wird das Fenster SAVE REQUEST (ANFORDERUNG SPEICHERN) geöffnet, in dem Sie einen Namen und eine optionale Beschreibung für die Anforderung eingeben können. Zudem können Sie die Sammlung auswählen, zu der sie gehört. Geben Sie die Informationen ein, und speichern Sie die Anforderung in der Sammlung, die Sie zuvor erstellt haben.

Screenshot des Fensters „Save request“ (Anforderung speichern) in Postman mit den beschriebenen Feldern. Die Schaltfläche „Save to Azure Digital Twins collection“ (In Azure Digital Twins-Sammlung speichern) ist hervorgehoben.

Nun können Sie die Anforderung in der Sammlung anzeigen und diese auswählen, um die bearbeitbaren Details aufzurufen.

Screenshot von Postman. Die Azure Digital Twins-Sammlung ist erweitert und zeigt die Details der Anforderung an.

Festlegen von Anforderungsdetails

Sie benötigen die URL der API und die dafür erforderlichen Informationen, um eine Postman-Anforderung in einer der Azure Digital Twins-APIs zu stellen. Diese Informationen finden Sie in der Referenzdokumentation für die REST-APIs von Azure Digital Twins.

In diesem Artikel wird die Abfrage-API und die Azure Digital Twins-Abfrage-API für eine Beispielabfrage verwendet, um alle digitalen Zwillinge in einer Instanz abzufragen.

  1. Die URL und den Typ der Anforderung erhalten Sie in der Referenzdokumentation. Für die Abfrage-API ist dies derzeit POST https://digitaltwins-host-name/query?api-version=2020-10-31.

  2. Legen Sie in Postman den Typ für die Anforderung fest, und geben Sie die Anforderungs-URL ein. Füllen Sie dabei die Platzhalter in der URL nach Bedarf aus. Verwenden Sie den Hostnamen der Instanz aus dem Abschnitt Voraussetzungen.

    Screenshot der Details der neuen Anforderung in Postman. Die Abfrage-URL aus der Referenzdokumentation wurde im Feld für die Anforderungs-URL eingegeben.

  3. Überprüfen Sie, ob die Parameter, die für die Anforderung auf der Registerkarte Parameter angezeigt werden, den in der Referenzdokumentation beschriebenen Parametern entsprechen. Für diese Anforderung in Postman wurde der Parameter api-version automatisch aufgefüllt, als die Anforderungs-URL im vorherigen Schritt eingegeben wurde. Bei der Abfrage-API ist dies der einzige erforderliche Parameter, sodass dieser Schritt erledigt ist.

  4. Legen Sie auf der Registerkarte Autorisierung den Typ auf Authentifizierung von der übergeordneten Instanz erben fest. Dies gibt an, dass für diese Anforderung die Autorisierung verwendet wird, die Sie zuvor für die gesamte Sammlung eingerichtet haben.

  5. Überprüfen Sie, ob die Header, die für die Anforderung auf der Registerkarte Header angezeigt werden, den in der Referenzdokumentation beschriebenen entsprechen. Für diese Anforderung wurden mehrere Header automatisch ausgefüllt. Bei der Abfrage-API ist keine der Headeroptionen erforderlich, sodass dieser Schritt erledigt ist.

  6. Überprüfen Sie, ob der Textkörper, der für die Anforderung in der Registerkarte Textkörper angezeigt wird, den in der Referenzdokumentation beschriebenen Anforderungen entspricht. Für die Abfrage-API ist ein JSON-Textkörper erforderlich, um den Abfragetext bereitzustellen. Nachfolgend sehen Sie einen Beispieltextkörper für diese Anforderung, die alle digitalen Zwillinge in der Instanz abfragt:

    Screenshot der Details der neuen Anforderung in Postman mit der Registerkarte „Body“ (Textkörper). Diese enthält einen unformatierten JSON-Textkörper mit der Abfrage „SELECT * FROM DIGITALTWINS“.

    Weitere Informationen zum Erstellen von Azure Digital Twins-Abfragen finden Sie unter Abfragen des Zwillingsdiagramms von Azure Digital Twins.

  7. Überprüfen Sie die Referenzdokumentation für alle anderen Felder, die möglicherweise für den Typ der Anforderung erforderlich sind. Bei der Abfrage-API sind nun alle Anforderungen in der Postman-Anforderung erfüllt, sodass dieser Schritt erledigt ist.

  8. Verwenden Sie die Schaltfläche Senden, um die abgeschlossene Anforderung zu senden. Screenshot von Postman mit den Details der neuen Anforderung. Die Schaltfläche „Send“ (Senden) ist hervorgehoben.

Nachdem die Anforderung gesendet wurde, werden die Antwortinformationen im Postman-Fenster unterhalb der Anforderung angezeigt. Sie können den Statuscode der Antwort und jeden Textkörper anzeigen.

Screenshot der gesendeten Anforderung in Postman. Unterhalb der Anforderungsdetails wird die Antwort angezeigt. Der Status lautet „200 OK“, und der Textkörper zeigt die Abfrageergebnisse an.

Sie können auch die Antwort mit den erwarteten Antwortdaten vergleichen, die in der Referenzdokumentation angegeben sind, um das Ergebnis zu überprüfen oder weitere Informationen zu auftretenden Fehlern zu erhalten.

Nächste Schritte

Weitere Informationen zu Digital Twins-APIs finden Sie unter Azure Digital Twins-APIs und -SDKs oder in der Referenzdokumentation für die REST-APIs.