Azure Digital Twins 用に Postman を構成する方法How to configure Postman for Azure Digital Twins

この記事では、Azure Digital Twins Management API を操作およびテストするために、Postman REST クライアントを構成する方法について説明します。This article describes how to configure the Postman REST client to interact with and test the Azure Digital Twins Management APIs. 具体的には、次の項目について説明します。Specifically, it describes:

  • OAuth 2.0 の暗黙的な許可フローを使用するように Azure Active Directory アプリケーションを構成する方法。How to configure an Azure Active Directory application to use the OAuth 2.0 implicit grant flow.
  • Management API に対してトークンを使用する HTTP 要求を行うように Postman REST クライアントを使用する方法。How to use the Postman REST client to make token-bearing HTTP requests to your Management APIs.
  • Postman を使用し、管理 API にマルチパートの POST 要求を行う方法。How to use Postman to make multipart POST requests to your Management APIs.

Postman の概要Postman summary

ローカル テスト環境を準備するには、Postman などの REST クライアント ツールを使用して Azure Digital Twins を開始します。Get started on Azure Digital Twins by using a REST client tool such as Postman to prepare your local testing environment. Postman クライアントは、複雑な HTTP 要求を簡単に作成するのに役立ちます。The Postman client helps to quickly create complex HTTP requests. Postman クライアントのデスクトップ バージョンをダウンロードするには、www.getpostman.com/apps にアクセスします。Download the desktop version of the Postman client by going to www.getpostman.com/apps.

Postman は、便利なデスクトップとプラグイン ベースの GUI に重要な HTTP 要求機能を配置する REST テスト ツールです。Postman is a REST testing tool that locates key HTTP request functionalities into a useful desktop and plugin-based GUI.

ソリューション開発者は、Postman クライアントを使用して、HTTP 要求の種類 (POSTGETUPDATEPATCHDELETE)、呼び出す API エンドポイント、SSL の使用を指定できます。Through the Postman client, solutions developers can specify the kind of HTTP request (POST, GET, UPDATE, PATCH, and DELETE), API endpoint to call, and use of SSL. また、Postman では、HTTP 要求ヘッダー、パラメーター、フォーム データ、本文の追加もサポートされています。Postman also supports adding HTTP request headers, parameters, form-data, and bodies.

OAuth 2.0 の暗黙的な許可フローを使用するように Azure Active Directory を構成するConfigure Azure Active Directory to use the OAuth 2.0 implicit grant flow

OAuth 2.0 の暗黙的な許可フローを使用するように Azure Active Directory アプリを構成します。Configure your Azure Active Directory app to use the OAuth 2.0 implicit grant flow.

  1. アプリの登録の [API アクセス許可] ウィンドウを開きます。Open the API permissions pane for your app registration. [アクセス許可の追加] ボタンを選択します。Select Add a permission button. [API アクセス許可の要求] ウィンドウで、 [所属する組織で使用している API] タブを選択し、以下を探します:In the Request API permissions pane, select the APIs my organization uses tab, and then search for:

    1. Azure Digital TwinsAzure Digital Twins. Azure Digital Twins API を選択します。Select the Azure Digital Twins API.

      API または Azure Digital Twins を検索するSearch API or Azure Digital Twins

    2. または、Azure Smart Spaces Service を検索します。Alternatively, search for Azure Smart Spaces Service. Azure Smart Spaces Service API を選択します。Select the Azure Smart Spaces Service API.

      Azure Smart Spaces の API を検索するSearch API for Azure Smart Spaces

    重要

    表示される Azure AD API の名前と ID は、テナントによって異なります。The Azure AD API name and ID that will appear depends on your tenant:

    • テスト テナントと顧客アカウントでは、Azure Digital Twins を検索する必要があります。Test tenant and customer accounts should search for Azure Digital Twins.
    • 他の Microsoft アカウントでは、Azure Smart Spaces Service を検索する必要があります。Other Microsoft accounts should search for Azure Smart Spaces Service.
  2. 選択された API は、同じ [API アクセス許可の要求] ウィンドウに Azure Digital Twins と表示されます。The selected API shows up as Azure Digital Twins in the same Request API permissions pane. [Read (1)](読み取り (1)) ドロップ ダウンを選択し、 [Read.Write] チェック ボックスをオンにします。Select the Read (1) drop down, and then select Read.Write checkbox. [アクセス許可の追加] ボタンを選択しますSelect the Add permissions button.

    API のアクセス許可を追加するAdd API permissions

  3. 組織の設定によっては、この API への管理者アクセスを許可するために追加の手順を実行する必要があります。Depending on your organization's settings, you might need to take additional steps to grant admin access to this API. 詳細については、管理者にお問い合わせください。Contact your administrator for more information. 管理者アクセスが承認されると、 [API アクセス許可] ウィンドウの [管理者の同意が必要] 列に API の次のような内容が表示されます。Once the admin access is approved, the ADMIN CONSENT REQUIRED column in the API permissions pane will show similar to the following for your APIs:

    API のアクセス許可を追加するAdd API permissions

  4. [マニフェスト] を選択して、アプリのアプリケーション マニフェストを開きます。Select Manifest to open the application manifest for your app. oauth2AllowImplicitFlowtrue に設定します。Set oauth2AllowImplicitFlow to true.

    Azure Active Directory の暗黙のフローAzure Active Directory implicit flow

  5. [応答 URL]https://www.getpostman.com/oauth2/callback に構成します。Configure a Reply URL to https://www.getpostman.com/oauth2/callback.

    Azure Active Directory の応答 URLAzure Active Directory Reply URL

  6. Azure Active Directory アプリのアプリケーション ID をコピーして保管します。Copy and keep the Application ID of your Azure Active Directory app. これは後述する手順で使用されます。It's used in the steps that follow.

    Azure Active Directory のアプリケーション IDAzure Active Directory application ID

OAuth 2.0 トークンを取得するObtain an OAuth 2.0 token

次の例では、YOUR_MANAGEMENT_API_URL は Digital Twins API の URI を参照しています。In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
NameName 置換後の文字列Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure Digital Twins インスタンスの名前The name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION インスタンスをホストするリージョンThe region your instance is hosted on

Postman をセットアップし、Azure Active Directory トークンを取得するように構成します。Set up and configure Postman to obtain an Azure Active Directory token. その後、取得したトークンを使用し、Azure Digital Twins に対して認証済みの HTTP 要求を行います。Afterwards, make an authenticated HTTP request to Azure Digital Twins using the acquired token:

  1. www.getpostman.com に移動してアプリをダウンロードします。Go to www.getpostman.com to download the app.

  2. [承認 URL] が正しいことを検証します。Verify that your Authorization URL is correct. 次のような形式になっている必要があります。It should take the format:

    https://login.microsoftonline.com/YOUR_AZURE_TENANT.onmicrosoft.com/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0
    
    NameName 置換後の文字列Replace with Example
    YOUR_AZURE_TENANTYOUR_AZURE_TENANT テナントまたは組織の名前The name of your tenant or organization microsoft
  3. [承認] タブを選択し、 [OAuth 2.0] を選択して [Get New Access Token](新しいアクセス トークンの取得) を選択します。Select the Authorization tab, select OAuth 2.0, and then select Get New Access Token.

    フィールドField Value
    付与タイプGrant Type Implicit
    コールバック URLCallback URL https://www.getpostman.com/oauth2/callback
    認証 URLAuth URL ステップ 2承認 URL を使用しますUse the Authorization URL from step 2
    クライアント IDClient ID 前のセクションで作成または再利用した Azure Active Directory アプリのアプリケーション ID を使用しますUse the Application ID for the Azure Active Directory app that was created or reused from the previous section
    Scope (スコープ)Scope 空白Leave blank
    StateState 空白Leave blank
    クライアント認証Client Authentication Send as Basic Auth header
  4. クライアントは次のようになります。The client should now appear as:

    Postman クライアントの例Postman client example

  5. [Request Token](要求トークン) を選択します。Select Request Token.

    ヒント

    「OAuth 2 couldn’t be completed」(OAuth 2 を完了できませんでした) というエラー メッセージを受け取った場合は、次の操作を試してください。If you receive the error message "OAuth 2 couldn’t be completed," try the following:

    • Postman を閉じて再起動し、もう一度実行する。Close Postman, and reopen it and try again.
  6. 下へスクロールし、 [Use Token](トークンの使用) を選択します。Scroll down, and select Use Token.

マルチパートの POST 要求を行うMake a multipart POST request

前の手順を完了したら、認証済み HTTP マルチパート POST 要求を行うように Postman を設定します。After completing the previous steps, configure Postman to make an authenticated HTTP multipart POST request:

  1. [ヘッダー] タブで、値が multipart/mixed の HTTP 要求ヘッダー キー [Content-Type] を追加します。Under the Header tab, add an HTTP request header key Content-Type with value multipart/mixed.

    コンテンツの種類 multipart/mixedContent type multipart/mixed

  2. テキストではないデータをシリアル化し、ファイルを生成します。Serialize non-text data into files. JSON データは JSON ファイルとして保存されます。JSON data would be saved as a JSON file.

  3. [Body](本文) タブで、form-data を選択します。Under the Body tab, select form-data.

  4. キー名を割り当て、file を選択することによって、各ファイルを追加します。Add each file by assigning a key name, selecting file.

  5. 次に、 [ファイルの選択] ボタンで各ファイルを選択します。Then, select each file through the Choose File button.

    Postman クライアントの例Postman client example

    注意

    • Postman クライアントでは、Content-Type または Content-Disposition をマルチパートに手動で割り当てる必要がありません。The Postman client does not require that multipart chunks have a manually assigned Content-Type or Content-Disposition.
    • これらのヘッダーをパートごとに指定する必要がありません。You do not need to specify those headers for each part.
    • 要求全体に multipart/mixed か別の適切な Content-Type を選択する必要がありません。You must select multipart/mixed or another appropriate Content-Type for the entire request.
  6. 最後に、 [送信] を選択し、マルチパート HTTP POST 要求を送信します。Lastly, select Send to submit your multipart HTTP POST request.

次の手順Next steps