Visual Studio を使用して Azure Digital Twins API に要求を送信する方法

[アーティクル]
08/15/2024

Visual Studio 2022 では、アプリケーションから HTTP 要求を構造化、格納、および直接送信するために使用できる .http ファイルがサポートされています。 Visual Studio のこの機能を使用することは、HTTP 要求を作成し、Azure Digital Twins REST API に送信する 1 つの方法です。この記事では、Azure Digital Twins API と連動できる .http ファイルを Visual Studio で設定する方法について説明します。

この記事には、次の手順に関する情報が含まれています。

Azure Digital Twins インスタンスを表す変数を使用して、Visual Studio プロジェクトと .http ファイルを設定します。
Azure CLI を使用して、Visual Studio で API 要求を行うために使用するベアラートークンを取得します。
Azure Digital Twins REST API ドキュメントをリソースとして使用して、.http ファイルで要求を作成し、Azure Digital Twins API に送信します。

Azure Digital Twins には、データプレーンとコントロールプレーンで使用できる 2 つの API セットがあります。これらの API セットの相違点について詳しくは、「Azure Digital Twins API および SDK」をご覧ください。この記事には、両方の API セットの手順が含まれています。

Visual Studio での .http ファイルのサポートの詳細については、「Visual Studio 2022 で .http ファイルを使用する」を参照してください。

前提条件

Visual Studio を使用して Azure Digital Twins API に要求を行うには、Azure Digital Twins インスタンスを設定し、Visual Studio 2022 をダウンロードする必要があります。このセクションでは、これらの手順について説明します。

Azure Digital Twins インスタンスを設定する

この記事で Azure Digital Twins を操作するには、まず Azure Digital Twins インスタンスとそれを使用するために必要なアクセス許可が必要です。 Azure Digital Twins インスタンスが既に設定されている場合は、そのインスタンスを使用し、次のセクションに進むことができます。それ以外の場合は、「インスタンスと認証を設定する」の手順に従います。手順には、各ステップを正常に完了したことを確認するために役立つ情報が含まれています。

インスタンスの設定後、インスタンスのホスト名を書き留めておきます。ホスト名は Azure portal で確認できます。

Visual Studio 2022 のダウンロード

次に、Visual Studio 2022 をダウンロードします。 ASP.NET と Web 開発ワークロードをインストールに含めるようにしてください。

Visual Studio プロジェクトを設定する

このセクションでは、HTTP 要求の作成に使用するプロジェクトを Visual Studio で設定します。

コンピューターで Visual Studio を開き、新しいプロジェクトを作成します。 ASP.NET Core Empty プロジェクトテンプレートを使用します。

「.http ファイルを作成する」の手順に従って、プロジェクトに新しい .http ファイルを作成します。

変数の追加

次に、Azure Digital Twins リソースへの接続に使用するためのいくつかの変数を .http ファイルの先頭に追加します。

必要な変数のセットは、使用している API のセットによって異なります。そのため、次のタブを使用して、データプレーン API とコントロールプレーン API のいずれかを選択します。

データプレーン
コントロールプレーン

データプレーン要求の場合は次の変数を追加します。 Azure Digital Twins インスタンスのホスト名には 1 つのプレースホルダーがあります (digitaltwins.azure.net で終わります)。

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

コントロールプレーン要求の場合は次の変数を追加します。リソース値のプレースホルダーが含まれています。

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

ベアラートークンを追加する

Azure Digital Twins インスタンスと Visual Studio プロジェクトを設定したので、次は、HTTP 要求で Azure Digital Twins API に対する認証に使用できるベアラートークンを取得する必要があります。

このトークンを取得する方法は複数あります。この記事では、Azure CLI を使用して Azure アカウントにサインインし、その方法でトークンを取得します。

Azure CLI がローカルにインストールされている場合は、お使いのマシンでコマンドプロンプトを起動して次のコマンドを実行できます。そうでない場合は、ブラウザーで Azure Cloud Shell ウィンドウを開き、そこでコマンドを実行できます。

まず、次のコマンドを実行して、適切な資格情報を使用して Azure にログインしていることを確認します。
```
az login
```
次に、az account get-access-token コマンドを使用して、Azure Digital Twins サービスにアクセスできるベアラートークンを取得します。このコマンドでは、Azure Digital Twins リソースにアクセスできるアクセストークンを取得するために、Azure Digital Twins サービスエンドポイントのリソース ID を渡します。

トークンに必要なコンテキストは、使用している API のセットによって異なります。そのため、次のタブを使用して、データプレーンとコントロールプレーンの API を選択します。
- データプレーン
- コントロールプレーン
データプレーン API を使用して、使用するトークンを取得するには、トークンコンテキストに対して静的な値 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 を使用します。この値は、Azure Digital Twins サービスエンドポイントのリソース ID です。
```
az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0
```
コントロールプレーン API を使用して、使用するトークンを取得するには、トークンコンテキストに対して静的な値 https://management.azure.com/ を使用します。
```
az account get-access-token --resource https://management.azure.com/
```
Note

インスタンスとは異なる Microsoft Entra テナントに属しているサービスプリンシパルまたはユーザーアカウントを使用して Azure Digital Twins インスタンスにアクセスする必要がある場合は、Azure Digital Twins インスタンスの "ホーム" テナントにトークンを要求する必要があります。このプロセスの詳細については、アプリ認証コードの作成に関するページを参照してください。
結果の accessToken の値をコピーします。この値は、要求を承認するために Visual Studio に貼り付けるトークン値です。

ヒント

このトークンは少なくとも 5 分間かつ最大 60 分間有効です。現在のトークンに割り当てられた時間が足りなくなった場合は、このセクションの手順を繰り返して新しいものを取得できます。

`.http` ファイルにトークンを追加する

Visual Studio の .http ファイルで、トークンの値を保持する別の変数を追加します。

データプレーン
コントロールプレーン

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

これで変数は次のようになっているはずです。

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

これで変数は次のようになっているはずです。

要求を追加する

.http ファイルが設定されたので、Azure Digital Twin API への要求を追加できます。

まず、Azure Digital Twins REST API リファレンスを開きます。このドキュメントには、API の対象となるすべての操作の詳細が含まれています。実行する要求のリファレンスページに移動します。

この記事では、データプレーンの DigitalTwins Update API を例として使用します。

要求テンプレートの追加: リファレンスドキュメントに示されている HTTP 要求をコピーします。

Visual Studio で、.http ファイル内の変数の下にある新しい行に要求を貼り付けます。
パラメーターの追加: リファレンスドキュメントの「URI パラメーター」セクションを参照して、要求で必要なパラメーター値を確認します。前に作成した変数の一部をこの変数に置き換え、必要に応じて他のパラメーター値を入力できます。変数を参照するには、{{variable}} のように、変数名を二重中かっこで囲みます。詳細については、「変数」を参照してください。

Note

データプレーン要求の場合、digitaltwins-hostname もパラメーターです。ホスト名変数の値を使用するには、これを {{hostName}} に置き換えます。

この手順が要求の例ではどのように表示されるかを次に示します。
認可の追加: 次の行 (記述されているとおりに) を要求のすぐ下に追加して、ベアラートークン変数による認証を指定します。
```
Authorization: Bearer {{token}}
```
この手順が要求の例ではどのように表示されるかを次に示します。
ヘッダーの追加: リファレンスドキュメントの「要求ヘッダー」セクションを参照して、要求に付随するヘッダー値を確認します。 Content-Type などの従来の HTTP ヘッダーを含めることもできます。 HeaderName: Value の形式で、各ヘッダーを独自の行に追加します。詳細については、「要求ヘッダー」を参照してください。

この手順が要求の例ではどのように表示されるかを次に示します。
本文の追加: リファレンスドキュメントの「要求本文」セクションを参照して、要求に必要な本文情報を確認します。空白行の後に要求本文を追加します。詳細については、「要求本文」を参照してください。

この手順が要求の例ではどのように表示されるかを次に示します:
要求の準備ができたら、要求の上にある [要求の送信] を選択して送信します。