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

  • [アーティクル]

Postman は、デスクトップとプラグイン ベースの GUI に重要な HTTP 要求機能を提供する REST テスト ツールです。 これを使用して HTTP 要求を作成し、Azure Digital Twins REST API に送信できます。 この記事では、Azure Digital Twins API を操作するために、Postman REST クライアントを構成する方法について説明します。 この情報は、Azure Digital Twins サービスに固有のものです。

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

  1. Azure CLI を使用して、Postman で API 要求を行うために使用するベアラー トークンを取得します。
  2. Postman コレクションを設定し、ベアラー トークンを使用して認証するように Postman REST クライアントを構成します。 コレクションを設定するときに、次のいずれかのオプションを選択できます。
    1. Azure Digital Twins API 要求の事前構築済みコレクションをインポートします。
    2. 独自のコレクションを最初から作成します。
  3. 構成されたコレクションに要求の追加を行い、Azure Digital Twins API に送信します。

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

前提条件

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

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

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

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

Postman をダウンロードします

次に、デスクトップ バージョンの Postman クライアントをダウンロードします。

ベアラー トークンを取得する

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

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

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

  1. まず、次のコマンドを実行して、適切な資格情報を使用して Azure にログインしていることを確認します。

    az login

  2. 次に、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

    注意

    インスタンスとは異なる Azure Active Directory テナントに属しているサービス プリンシパルまたはユーザー アカウントを使用して Azure Digital Twins インスタンスにアクセスする必要がある場合は、Azure Digital Twins インスタンスの "ホーム" テナントからのトークンを要求する必要があります。 このプロセスの詳細については、アプリ認証コードの作成に関するページを参照してください。

  3. 結果の accessToken の値をコピーし、次のセクションで使用するために保存します。 この値は、要求を承認するために Postman に提供するトークン値です。

    az account get-access-token コマンドの結果を示すコンソールのスクリーンショット。サンプル値が強調表示された accessToken フィールド。

ヒント

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

次に、このトークンを使用して Azure Digital Twins に API 要求を行うように Postman を設定します。

Postman コレクションについて

Postman の要求はコレクション (要求のグループ) に保存されます。 コレクションを作成して要求をグループ化すると、多くの要求に共通の設定を一度に適用できます。 共通の設定を使用すると、Azure Digital Twins API に対して複数の要求を作成する予定の場合、承認が大幅に簡素化されます。コレクション全体に対してこれらの詳細を 1 回構成するだけで済むので、

Azure Digital Twins を使用する場合は、すべての Azure Digital Twins 要求の事前構築済みコレクションをインポートすることで開始できます。 API を調び、要求の例を使用してプロジェクトをすばやく設定する場合は、このコレクションをインポートできます。

または、最初から開始することにし、独自の空のコレクションを作成して必要な API のみを呼び出す個々の要求を設定することもできます。

以降のセクションでは、これらの両方の手順について説明します。 この記事の以降のセクションは、ローカルの Postman アプリケーション内で実行するため、お使いのコンピューターで Postman アプリケーションを開いてください。

Azure Digital Twins API のコレクションをインポートする

Postman で Azure Digital Twins を使い始める簡単な方法は、API の要求の事前構築済みのコレクションをインポートすることです。 サンプル要求データを含む一般的な Azure Digital Twins データ プレーン API 要求のコレクションをインポートするには、次の手順に従います。

  1. メインの Postman ウィンドウで、 [インポート] ボタンを選択します。 新しく開かれた Postman ウィンドウのスクリーンショット。[インポート] ボタンが強調表示されています。

  2. 次の [インポート] ウィンドウで、[リンク] を選択し、次の URL を入力します。 https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json 次に、[ インポート ] を選択して確認します。

    Postman の [インポート] ウィンドウのスクリーンショット。コレクションとしてインポートするファイルと [インポート] ボタンが表示されています。

新しくインポートされたコレクションが、メインの Postman ビューの [コレクション] タブで確認できるようになりました。

Postman のメイン ウィンドウのスクリーンショット。新しくインポートされたコレクションが [コレクション] タブで強調表示されています。

ヒント

特定のバージョンの Azure Digital Twins API (コントロール プレーンやデータ プレーンを含む) の API 呼び出しの完全なセットをインポートするには、Swagger ファイルをコレクションとしてインポートすることもできます。 コントロール プレーン API とデータ プレーン API の Swagger ファイルへのリンクについては、「 Azure Digital Twins API と SDK」を参照してください。

次のセクションに進んで、承認のためにベアラー トークンをコレクションに追加し、それを Azure Digital Twins インスタンスに接続します。

承認を構成する

次に、アクセスの詳細を構成するために、作成したコレクションを編集します。 作成したコレクションを強調表示し、[ その他のアクションを表示 ] アイコンを選択してアクション オプションを表示します。 [編集] を選択します。

Postman のスクリーンショット。インポートされたコレクションの [View more actions]\(その他のアクションを表示\) アイコンが強調表示され、[編集] がオプションで強調表示されます。

承認のためにベアラー トークンをコレクションに追加するには、次の手順に従います。 「ベアラー トークンを取得する」セクションで収集したトークンの値を、コレクション内のすべての API 要求に使用します。

  1. コレクションの編集ダイアログで、 [承認] タブが表示されていることを確認します。

    Postman のインポートされたコレクションの編集ダイアログのスクリーンショット。[承認] タブが表示されています。

  2. [種類] を [OAuth 2.0 ] に設定し、[アクセス トークン] ボックスにアクセス トークンを貼り付けます。 データ プレーン API とコントロール プレーン API には異なるトークンがあるため、使用している API の種類に正しいトークンを使用する必要があります。 [保存] を選択します。

    Postman のインポートされたコレクションの編集ダイアログの [承認] タブのスクリーンショット。種類は

    ヒント

    Postman クラウドで要求にトークンを格納し、トークンを他のユーザーと共有する場合は、トークン共有を有効にすることを選択できます。

その他の構成

コレクションに用意されている変数を設定することで、コレクションを Azure Digital Twins リソースに簡単に接続できます。 コレクション内の多くの要求に同じ値 (Azure Digital Twins インスタンスのホスト名など) が必要な場合は、コレクション内のすべての要求に適用される変数に値を格納できます。 Azure Digital Twins コレクションには、コレクション レベルで設定できる事前に作成された変数が付属しています。

  1. コレクションの編集ダイアログで、 [変数] タブに移動します。

  2. 次の表を使用して、コレクション内の変数の値を設定します。

    変数 API セット 説明
    digitaltwins-hostname データ プレーン Azure Digital Twins インスタンスのホスト名。 この値は、ポータルのインスタンスの概要ページで確認できます。
    subscriptionId コントロール プレーン Azure のサブスクリプション ID。
    digitalTwinInstance コントロール プレーン Azure Digital Twins インスタンスの名前。

    [変数] タブが表示されている、Postman のインポートされたコレクションの編集ダイアログのスクリーンショット。[CURRENT VALUE] フィールドが強調表示されています。

  3. コレクションに余分な変数が含まれている場合は、それらの値も入力して保存します。

  4. [保存] を選択します。

上記の手順を完了すると、コレクションの構成が完了します。 必要に応じて、コレクションの編集タブを閉じることができます。

要求を調べる

次に、Azure Digital Twins API コレクション内の要求を調べます。 コレクションを展開して、事前に作成された要求 (操作のカテゴリ別に並べ替えられたもの) を表示することができます。

異なる要求には、インスタンスとそのデータに関する異なる情報が必要になります。 特定の要求を作成するために必要なすべての情報を表示するには、「Azure Digital Twins の REST API リファレンス ドキュメント」で要求の詳細を参照してください。

Postman コレクションの要求の詳細を編集するには、次の手順を実行します。

  1. 編集可能な詳細情報を取得するには、一覧から選択します。

  2. サンプル コレクション内の要求のほとんどは、それ以上変更を加えずに実行するように事前に構成されています。

  3. 次のスクリーンショットは、 DigitalTwinModels Add API を 示しています。 [ 本文 ] タブには、追加する新しいモデルを定義する JSON ペイロードが表示されます。

  4. [パス変数] の [パラメーター] タブに一覧表示されている変数の値を入力します。

    Postman のスクリーンショット。コレクションが展開され、要求の [本文] タブが表示されます。

  5. 要求を実行するには、[ 送信 ] ボタンを使用します。

「個々の要求を追加する」セクションで説明されているプロセスを使用して、独自の 要求をコレクションに追加 することもできます。

独自のコレクションを作成する

Azure Digital Twins API の既存のコレクションをインポートする代わりに、独自のコレクションを最初から作成することもできます。 その後、「Azure Digital Twins の REST API リファレンス ドキュメント」を使用して、個々の要求を設定できます。

Postman Collection の作成

  1. コレクションを作成するには、メインの Postman ウィンドウで [新規] ボタンを選びます。

    Postman のメイン ウィンドウのスクリーンショット。[新規] ボタンが強調表示されています。

    [コレクション] の種類を選択します。

    Postman の [新規作成] ダイアログのスクリーンショット。[コレクション] オプションが強調表示されています。

  2. タブが開きます。 新しいコレクションの詳細を入力します。 コレクションの既定の名前 ("新しいコレクション") の横にある [編集] アイコンを選択して、独自に選択した名前に置き換えます。

    Postman の新しいコレクションの編集ダイアログのスクリーンショット。

続けて次のセクションに進んで、認証のためのベアラー トークンをコレクションに追加します。

承認を構成する

承認のためにベアラー トークンをコレクションに追加するには、次の手順に従います。 「ベアラー トークンを取得する」セクションで収集したトークンの値を、コレクション内のすべての API 要求に使用します。

  1. 新しいコレクションの編集ダイアログで、 [承認] タブに移動します。

    [承認] タブが表示された、Postman の新しいコレクションの編集ダイアログのスクリーンショット。

  2. [種類] を [OAuth 2.0] に設定し、[アクセス トークン] ボックスにアクセス トークンを貼り付け、 [保存] を選択します。

    Postman の [承認] タブの新しいコレクションの編集ダイアログのスクリーンショット。種類は

上記の手順を完了すると、コレクションの構成が完了します。 必要に応じて、新しいコレクションの編集タブを閉じることができます。

新しくインポートされたコレクションが、Postman のメイン ビューの [コレクション] タブで確認できるようになりました。

Postman のメイン ウィンドウのスクリーンショット。新しく作成したカスタム コレクションが [コレクション] タブで強調表示されています。

個々の要求を追加する

コレクションが設定されたので、独自の要求を Azure Digital Twisn API に追加できます。

  1. 要求を作成するには、 [新規] ボタンを再度使用します。

    Postman のメイン ウィンドウのスクリーンショット。[新規] ボタンが強調表示されています。

    [要求] の種類を選択します。

    Postman の [新規作成] ダイアログのスクリーンショット。[要求] オプションが強調表示されています。

  2. この操作により、[要求の保存] ウィンドウが開き、そこで要求の名前を入力し、必要に応じて説明を入力して、保存先のコレクションを選択できます。 詳細を入力し、前の手順で作成したコレクションに要求を保存します。

説明されているフィールドを示す Postman の [要求の保存] ウィンドウのスクリーンショット。[Save to Azure Digital Twins collection]\(Azure Digital Twins コレクションに保存\) ボタンが強調表示されています。

これで、コレクションに要求が表示され、それを選択して編集可能な詳細を取得できるようになりました。

Postman のスクリーンショット。Azure Digital Twins コレクションが展開され、要求の詳細が表示されます。

要求の詳細を設定する

Azure Digital Twins API のいずれかに対する Postman 要求を行うには、API の URL と、どのような詳細が必要かについての情報が必要です。 この情報については、Azure Digital Twins REST API のリファレンス ドキュメントを参照してください。

クエリの例を続行するために、この記事では Azure Digital Twins クエリ API を使用して、インスタンス内のすべてのデジタル ツインに対してクエリを実行します。

  1. リファレンス ドキュメントから要求 URL と種類を取得します。 クエリ API の場合、現在これは POST です。

  2. Postman で要求の種類を設定し、要求 URL を入力します。必要に応じて URL のプレースホルダーに入力します。 「前提条件」セクションで入手したインスタンスのホスト名を使います。

    Postman の新しい要求の詳細のスクリーンショット。リファレンス ドキュメントからのクエリ URL が要求 URL のボックスに入力されています。

  3. [Params](パラメーター) タブで、要求に対して表示されているパラメーターが、リファレンス ドキュメントに記載されているものと一致していることを確認します。 Postman でのこの要求には、前の手順で要求 URL を入力したときに、api-version パラメーターが自動的に入力されました。 クエリ API については、これが唯一の必須パラメーターであるため、この手順は完了です。

  4. [Authorization](認証) タブで、 [Type](種類) を [Inherit auth from parent](親から認証を継承) に設定します。 これは、この要求で、コレクション全体に対して以前に設定した承認が使用されることを示します。

  5. [Header](ヘッダー) タブに表示されている要求のヘッダーが、リファレンス ドキュメントに記載されているものと一致していることを確認します。 この要求には複数のヘッダーが自動的に入力されています。 クエリ API の場合、ヘッダー オプションはどれも必要ないため、この手順は完了です。

  6. [Body](本文) タブに表示されている要求の本文が、リファレンス ドキュメントに記載されているニーズに一致していることを確認します。 クエリ API には、クエリ テキストを指定する JSON 本文が必要です。 インスタンス内のすべてのデジタル ツインのクエリを実行するこの要求の本文の例を次に示します。

    Postman の新しい要求の詳細に [Body] タブがあるスクリーンショット。それには、

    Azure Digital Twins クエリの作成の詳細については、ツイン グラフに対するクエリの実行に関するページを参照してください。

  7. 要求の種類に応じて必要になる場合があるその他のフィールドについては、リファレンス ドキュメントを参照してください。 クエリ API については、Postman 要求ですべての要件が満たされたので、この手順は完了です。

  8. [Send](送信) ボタンを使用して、完成した要求を送信します。 新しい要求の詳細を示す Postman のスクリーンショット。[送信] ボタンが強調表示されています。

要求の送信後、Postman ウィンドウで要求の下に応答の詳細が表示されます。 応答の状態コードと本文のテキストを確認できます。

Postman で送信された要求のスクリーンショット。要求の詳細の下に、応答が表示されます。状態は 200 OK で、本文はクエリの結果を示します。

また、応答と、リファレンス ドキュメントに示されている予想される応答データを比較して、結果を確認したり、発生したエラーの詳細を確認したりすることもできます。

次のステップ

Digital Twins API の詳細については、「Azure Digital Twins の API および SDK」をご覧になるか、REST API のリファレンス ドキュメントをご覧ください。