Freigeben über

Senden von Anforderungen an die Azure Digital Twins-APIs mithilfe von Visual Studio

  • Artikel

Visual Studio 2022 unterstützt .http-Dateien, mit denen HTTP-Anforderungen strukturiert, gespeichert und direkt von der Anwendung aus gesendet werden können. Diese Funktionalität von Visual Studio ist eine Möglichkeit, HTTP-Anforderungen zu erstellen und an die REST-APIs von Azure Digital Twins zu übermitteln. In diesem Artikel wird beschrieben, wie Sie eine .http-Datei in Visual Studio einrichten, die mit den Azure Digital Twins-APIs interagieren kann.

Dieser Artikel enthält Informationen zu den folgenden Schritten:

  1. Richten Sie ein Visual Studio-Projekt und eine .http-Datei mit Variablen ein, die Ihre Azure Digital Twins-Instanz darstellen.
  2. Verwenden Sie die Azure CLI, um ein Bearertoken abzurufen, das Sie für API-Anforderungen in Visual Studio verwenden können.
  3. Verwenden Sie die Dokumentation zur REST-API von Azure Digital Twins als Ressource, um Anforderungen in der .http-Datei zu erstellen und an die Azure Digital Twins-APIs zu senden.

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 Anweisungen für beide API-Gruppen.

Weitere Informationen zur Unterstützung der .http-Datei in Visual Studio finden Sie unter Verwenden von HTTP-Dateien in Visual Studio 2022.

Voraussetzungen

Um mit Visual Studio Anforderungen an die Azure Digital Twins-APIs zu stellen, müssen Sie eine Azure Digital Twins-Instanz einrichten und Visual Studio 2022 herunterladen. In diesem Abschnitt werden diese Schritte erläutert.

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.

Visual Studio 2022 herunterladen

Laden Sie als Nächstes Visual Studio 2022 herunter. Stellen Sie sicher, dass die Workload ASP.NET und Webentwicklung in Ihrer Installation enthalten ist.

Einrichten eines Visual Studio-Projekts

In diesem Abschnitt richten Sie das Projekt in Visual Studio ein, das zum Erstellen von HTTP-Anforderungen verwendet wird.

Öffnen Sie Visual Studio auf Ihrem Computer, und erstellen Sie ein neues Projekt. Verwenden Sie die Projektvorlage ASP.NET Core leer.

Screenshot einer Projektvorlage des Typs „ASP.NET Core leer“ in Visual Studio

Befolgen Sie die Anweisungen unter Erstellen einer HTTP-Datei, um eine neue .http-Datei in Ihrem Projekt zu erstellen.

Variablen hinzufügen

Fügen Sie als Nächstes einige Variablen am Anfang Ihrer .http-Datei hinzu, die zum Herstellen einer Verbindung mit Ihrer Azure Digital Twins-Ressource verwendet werden.

Die erforderlichen Variablen hängen von den verwendeten APIs ab. Verwenden Sie daher die unten aufgeführten Registerkarten, um zwischen den APIs der Datenebene und denen der Steuerungsebene auszuwählen.

Fügen Sie die folgenden Variablen für Anforderungen der Datenebene hinzu. Es gibt einen Platzhalter für den Hostnamen Ihrer Azure Digital Twins-Instanz (endet auf digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Hinzufügen des Bearertokens

Nachdem Sie die Azure Digital Twins-Instanz und Visual Studio eingerichtet haben, müssen Sie ein Bearertoken abrufen, das von HTTP-Anforderungen zur Autorisierung bei 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 auf diese Weise 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 richtigen Anmeldeinformationen bei Azure angemeldet sind, indem Sie diesen 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 unten aufgeführten 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 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 von accessToken aus dem Ergebnis. Dieser Wert ist Ihr Tokenwert, den Sie in Visual Studio einfügen, um Ihre Anforderungen zu autorisieren.

    Screenshot: Konsole mit dem Ergebnis des Befehls „az account get-access-token“. Ein Beispielwert ist im accessToken-Feld hervorgehoben.

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.

Hinzufügen eines Tokens zur .http-Datei

Fügen Sie in Ihrer .http-Datei in Visual Studio eine weitere Variable hinzu, die den Wert Ihres Tokens enthält.

@token=<paste-data-plane-token>

Ihre Variablen sollten nun in etwa wie folgt aussehen:

Screenshot der Datenebenenvariablen, einschließlich eines Tokens.

Hinzufügen von Anforderungen

Nachdem Sie .http-Datei eingerichtet haben, können Sie den Azure Digital Twin-APIs Anforderungen hinzufügen.

Öffnen Sie zunächst die REST-API-Referenz für Azure Digital Twins. Diese Dokumentation enthält Details zu allen Vorgängen, die von den APIs abgedeckt werden. Navigieren Sie zur Referenzseite der Anforderung, die Sie ausführen möchten.

In diesem Artikel wird die DigitalTwins-Update-API der Datenebene als Beispiel verwendet.

  1. Fügen Sie eine Anforderungsvorlage hinzu: Kopieren Sie die HTTP-Anforderung aus der Referenzdokumentation.

    Screenshot der HTTP-Anforderung in der Dokumentation zur Digital Twins-API.

    Fügen Sie die Anforderung in der .http-Datei in Visual Studio in eine neue Zeile unter den Variablen ein.

  2. Fügen Sie Parameter hinzu: Sehen Sie im Abschnitt URI-Parameter der Referenzdokumentation nach, welche Parameterwerte von der Anforderung benötigt werden. Sie können einige durch die Variablen ersetzen, die Sie zuvor erstellt haben, und andere Parameterwerte nach Bedarf ausfüllen. Um auf eine Variable zu verweisen, umschließen Sie den Variablennamen in doppelten geschweiften Klammern wie in {{variable}}. Weitere Informationen finden Sie unter Variablen.

    Hinweis

    Für Anforderungen der Datenebene ist digitaltwins-hostname ebenfalls ein Parameter. Ersetzen Sie ihn durch {{hostName}}, um den Wert der Hostnamenvariable zu verwenden.

    So sieht dieser Schritt in einer Beispielanforderung aus:

    Screenshot der Anforderung mit Parametern in Visual Studio.

  3. Fügen Sie eine Autorisierung hinzu: Fügen Sie den genauen Wortlaut der folgenden Zeile direkt unterhalb der Anforderung hinzu, um die Authentifizierung mit Ihrer Bearertokenvariable anzugeben.

    Authorization: Bearer {{token}}

    So sieht dieser Schritt in einer Beispielanforderung aus:

    Screenshot der Anforderung mit Autorisierungszeile in Visual Studio.

  4. Fügen Sie zusätzliche Header hinzu: Sehen Sie im Abschnitt Anforderungsheader der Referenzdokumentation nach, welche Headerwerte für die Anforderung zulässig sind. Sie sollten auch herkömmliche HTTP-Header wie Content-Type einfügen. Fügen Sie jeden Header in einer eigenen Zeile im Format HeaderName: Value hinzu. Weitere Informationen finden Sie unter Anforderungsheader.

    So sieht dieser Schritt in einer Beispielanforderung aus:

    Screenshot der Anforderung mit einem anderen Header in Visual Studio.

  5. Fügen Sie Text hinzu: Sehen Sie im Abschnitt Anforderungstext der Referenzdokumentation nach, welche Informationen möglicherweise im Anforderungstext erforderlich sind. Fügen Sie den Anforderungstext nach einer leeren Zeile ein. Weitere Informationen finden Sie unter Anforderungstext.

    So sieht dieser Schritt in einer Beispielanforderung aus: Screenshot der Anforderung mit einem Textkörper in Visual Studio.

  6. Wenn die Anforderung fertig ist, wählen Sie über der Anforderung Anforderung senden aus, um sie zu senden.

    Screenshot von „Anforderung senden“ in Visual Studio.

In Visual Studio wird ein Bereich mit den Antwortdetails angezeigt. Sehen Sie im Abschnitt Antworten der Referenzdokumentation nach, um den Statuscode und alle Daten im Antworttext zu interpretieren.

Screenshot der Antwort in Visual Studio.

Hinzufügen zusätzlicher Anforderungen

Um der .http-Datei weitere Anforderungen hinzuzufügen, listen Sie sie mit ### als Trennzeichen auf.

Screenshot mehrerer Anforderungen in einer Datei in Visual Studio.

Nächste Schritte

Weitere Informationen zum Senden von Anforderungen mit .http-Dateien in Visual Studio, einschließlich Syntaxdetails und erweiterten Szenarios, finden Sie unter Verwenden von HTTP-Dateien in Visual Studio 2022.

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