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 abzurufen.

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 davon ab, welche GRUPPE von APIs Sie verwenden. Verwenden Sie daher die folgenden Registerkarten, um zwischen Datenebenen - und Steuerelementebenen-APIs auszuwählen.

    Verwenden Sie zum Abrufen eines Tokens, das mit den Datenebenen-APIs verwendet werden soll, 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 über einen Dienstprinzipal oder ein Benutzerkonto, das zu einem anderen Microsoft Entra-Mandanten gehört, auf Ihre Azure Digital Twins-Instanz zugreifen müssen, müssen Sie ein Token vom "Home"-Mandanten 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 of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

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 mehr als eine Anforderung für die Azure Digital Twins-APIs erstellen möchten, 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 Möglichkeit, mit Azure Digital Twins in Postman zu beginnen, besteht darin, eine vordefinierte Sammlung von Anforderungen für die APIs zu importieren. Führen Sie die folgenden Schritte aus, um eine Sammlung beliebter AZURE Digital Twins-DATENebenen-API-Anforderungen zu importieren, die Beispielanforderungsdaten enthalten.

  1. Wählen Sie im Hauptfenster von Postman die Schaltfläche Import aus. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Wählen Sie im folgenden 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 den Vorgang zu bestätigen.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

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

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Tipp

Um den vollständigen Satz von API-Aufrufen für eine bestimmte Version der Azure Digital Twins-APIs (einschließlich Steuerebene oder Datenebene) zu importieren, können Sie auch Swagger-Dateien als Sammlungen importieren. Links zu den Swagger-Dateien für die Steuerebenen- 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 Aktionsoptionen anzuzeigen. Wählen Sie Bearbeiten.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

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 of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Legen Sie den Typ auf OAuth 2.0 fest, und fügen Sie Ihr Zugriffstoken in das Zugriffstokenfeld ein. Sie müssen das richtige Token für den typ der verwendeten API verwenden, da es unterschiedliche Token für Datenebenen-APIs im Vergleich zu Steuerelementebenen-APIs gibt. Wählen Sie Speichern aus.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Tipp

    Sie können die Tokenfreigabe aktivieren, wenn Sie das Token mit der Anforderung in der Postman-Cloud speichern und Ihr Token möglicherweise 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-Auflistung 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 Auflistung festzulegen:

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

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

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

  4. Wählen Sie Speichern aus.

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 Api zum Hinzufügen von DigitalTwinModels. Auf der Registerkarte "Textkörper " können Sie die JSON-Nutzlast sehen, 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 of Postman. The collection is expanded to show the body tab of a request.

  5. Verwenden Sie die Schaltfläche "Senden ", um die Anforderung auszuführen.

Sie können der Sammlung auch eigene Anforderungen hinzufügen, indem Sie den im Abschnitt "Einzelne Anforderung hinzufügen" beschriebenen Prozess verwenden.

Erstellen Ihrer eigenen Sammlung

Anstatt die vorhandene Sammlung von Azure Digital Twins-APIs zu importieren, können Sie auch ihre eigene Sammlung ganz neu 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 of the main Postman window. The 'New' button is highlighted.

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

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  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 of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

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 of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  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 of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

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 of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

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 of the main Postman window. The 'New' button is highlighted.

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

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  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 of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

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

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

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.

Um mit einer Beispielabfrage fortzufahren, verwendet dieser Artikel die Azure Digital Twins Query-API , 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 POSThttps://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 of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  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 übergeordnetem Element 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 of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of '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 of Postman showing the details of the new request. The Send button is highlighted.

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 of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

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.