チュートリアル: REST API を使用して Azure IoT Central アプリケーションを管理する

  • [アーティクル]

このチュートリアルでは、Azure IoT Central REST API を使用して、IoT Central アプリケーションの作成と操作を行う方法について説明します。 このチュートリアルでは、クイックスタートで Web UI を使って行った手順の多くを、REST API を使って行います。 これらの手順には、IoT デバイスとしてのスマートフォンでの、IoT Central に接続するアプリの使用が含まれます。

このチュートリアルでは、以下の内容を学習します。

  • REST API を承認します。
  • IoT Central アプリケーションを作成します。
  • アプリケーションにデバイスを追加します。
  • デバイスのクエリと制御を行います。
  • データ エクスポートを設定します。
  • アプリケーションを削除します。

前提条件

このチュートリアルを完了するには、以下が必要になります。

  • 有効な Azure サブスクリプション Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

  • 公式アプリ ストアのどれかから無料のアプリをインストールできる Android または iOS 搭載のスマートフォン。

Azure CLI

Azure CLI を使って、一部の REST API が承認に使用するベアラー トークンを生成します。

  • Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

  • CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

    • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

    • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

    • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

postman

このチュートリアルでは、REST API の呼び出しに Postman を使います。 Postman をダウンロードしてインストールしたくない場合は、オンライン バージョンを使用できます。 無料版の Postman を使って、チュートリアルのすべての手順を完了できます。

このチュートリアルでは、手順を完了するのに役立ついくつかのスクリプトを含む定義済みの Postman コレクションを使います。

Postman コレクションのインポート

コレクションをインポートするには、Postman を開いて、[インポート] を選びます。 [インポート] ダイアログで [リンク] を選び、次の URL に貼り付けて、[続行] を選択します。

ワークスペースに IoT Central REST チュートリアルのコレクションが含まれるようになります。 このコレクションには、チュートリアルで使うすべての API が含まれています。

このコレクションでは、変数を使って REST API の呼び出しがパラメーター化されています。 変数を表示するには、IoT Central REST チュートリアルの横にある [...] を選んで、[編集] を選びます。 次に、[変数] を選びます。 変数の多くは、API を呼び出すと自動的に設定されるか、値が事前に設定されています。

REST API を承認する

REST API を使う前に、承認を構成する必要があります。 このチュートリアルでの REST API の呼び出しでは、次の 3 つの承認の種類のいずれかを使います。

  • https://management.azure.com へのアクセスを承認するベアラー トークン。 IoT Central アプリケーションを作成および削除するときは、このベアラー トークンを使います。 IoT Central アプリケーションは Azure リソースです。
  • https://apps.azureiotcentral.com へのアクセスを承認するベアラー トークン。 IoT Central アプリケーションで API トークンを作成するには、このベアラー トークンを使います。
  • IoT Central アプリケーションの機能へのアクセスを承認する管理者およびオペレーター API トークン。 このチュートリアルでのほとんどの API 呼び出しには、これらのトークンを使います。 これらのトークンでは、特定の 1 つの IoT Central アプリケーションへのアクセスのみが承認されます。

Postman コレクション内の次の変数に値を割り当てます。

  • bearerToken: 次の Azure CLI コマンドを実行して、https://management.azure.com へのアクセスを承認するベアラー トークンを生成します。

    az login
az account get-access-token --resource https://management.azure.com

    ヒント

    Cloud Shell を使っている場合でも、az login の実行が必要になる場合があります。

    コレクション変数で bearerToken の [現在の値] 列に accessToken の値をコピーします。

  • bearerTokenApp: 次の Azure CLI コマンドを実行して、https://apps.azureiotcentral.com へのアクセスを承認するベアラー トークンを生成します。

    az account get-access-token --resource https://apps.azureiotcentral.com

    ヒント

    シェルの新しいインスタンスを開始した場合は、もう一度 az login を実行します。

    コレクション変数で bearerTokenApp の [現在の値] 列に accessToken の値をコピーします。

  • subscriptionId: サブスクリプション ID は、前の 2 つのコマンドからの出力に含まれていました。 コレクション変数で subscriptionId の [現在の値] 列に subscription の値をコピーします。

Screenshot that shows the variables set manually in the Postman collection.

Postman コレクションに対する変更を必ず保存してください。

Note

ベアラー トークンは 1 時間で期限が切れます。

アプリケーションの作成

IoT Central アプリケーションを作成して管理するには、コントロール プレーン要求を使います。 このチュートリアルで使うアプリケーションを作成するには、次の PUT 要求を使用します。 この要求では、ベアラー トークンを使って承認が行われ、ランダムなアプリケーション名が生成されます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Create an IoT central application (IoT Central アプリケーションを作成する) 要求を選びます。
  2. [Send] を選択します。
  3. 要求が成功したことを確認します。 失敗した場合は、Postman コレクションに bearerToken および subscriptionId 変数の値を入力したことを確認します。
  4. [Visualize] (表示) を選んで、新しい IoT Central アプリケーションの URL を表示します。 このチュートリアルで後ほど必要になるので、この URL を記録しておきます。

Screenshot that shows the Visualize tab with the application URL in Postman.

API トークンを作成する

IoT Central アプリケーションでアプリケーション API トークンを作成するには、次のデータ プレーン要求を使います。 このチュートリアルの一部の要求では、API トークンと管理者アクセス許可が必要ですが、ほとんどの場合は、オペレーターのアクセス許可を使用できます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Create an operator token (オペレーター トークンを作成する) 要求を選びます。
  2. [Send] を選択します。
  3. Postman で、IoT Central REST チュートリアル コレクションを開き、Create an admin token (管理者トークンを作成する) 要求を選びます。
  4. [Send] を選択します。

IoT Central アプリケーションでこれらのトークンを表示する場合は、アプリケーションを開き、[セキュリティ] > [アクセス許可] > [API トークン] に移動します。

Note

Postman のスクリプトにより、これらの API トークンがコレクション変数のリストに自動的に追加されます。

デバイスの登録

接続する前に、デバイスを IoT Central に登録する必要があります。 アプリケーションにデバイスを登録し、デバイスの資格情報を取得するには、次の要求を使います。 最初の要求では、デバイス ID が phone-001 であるデバイスが作成されます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Add a device (デバイスを追加する) 要求を選びます。
  2. [Send] を選択します。 応答で、デバイスがプロビジョニングされていないことに注意してください。
  3. Postman で、IoT Central REST チュートリアル コレクションを開き、Get device credentials (デバイスの資格情報を取得する) 要求を選びます。
  4. [Send] を選択します。
  5. [Visualize] (表示) タブに、デバイスが接続できるために必要な ID スコープと主キーの値が表示されます。

デバイスをプロビジョニングして接続する

スマートフォンでデバイスの資格情報を手動で入力する必要がないようにするには、IoT Central によって生成された QR コードを使用できます。 この QR コードには、デバイス ID、ID スコープ、主キーがエンコードされています。 QR コードを表示するには:

  1. 前に記録したアプリケーションの URL を使って、IoT Central アプリケーションを開きます。
  2. IoT Central アプリケーションで、[デバイス] > [My phone app] (自分の電話アプリ) > [接続] > [QR コード] に移動します。 デバイスが接続されるまで、このページを開いたままにします。

Screenshot that shows the QR code you use to connect the device.

セットアップを簡単にするため、この記事では、IoT デバイスとして IoT プラグ アンド プレイ スマートフォン アプリを使います。 このアプリで、スマートフォンのセンサーから収集されたテレメトリを送信し、IoT Central から呼び出されたコマンドに応答して、プロパティ値を IoT Central に報告します。

次のアプリ ストアのいずれかから、お使いのスマートフォンにアプリをインストールします。

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

IoT プラグ アンド プレイ アプリを IoT Central アプリケーションに接続するには:

  1. スマートフォンで IoT PnP アプリを開きます。

  2. ようこそのページで、 [Scan QR code](QR コードのスキャン) を選択します。 スマートフォンのカメラで QR コードをポイントします。 その後、接続が確立されるまで数秒間待ちます。

  3. アプリのテレメトリのページで、アプリから IoT Central に送信されているデータを確認できます。 ログのページで、デバイスが接続中であることと、いくつかの初期化メッセージを確認できます。

デバイスがプロビジョニングされたことを確認するには、次の REST API を使用できます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Get a device (デバイスを取得する) 要求を選びます。
  2. [Send] を選択します。 応答で、デバイスがプロビジョニングされたことに注意してください。 IoT Central により、デバイスによって送信されたモデル ID に基づいて、デバイス テンプレートもデバイスに割り当てられています。

REST API を使って、アプリケーションでデバイス テンプレートを管理できます。 たとえば、アプリケーションでデバイス テンプレートを表示するには、次のようにします。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、List device templates (デバイス テンプレートの一覧を表示する) 要求を選びます。
  2. [Send] を選択します。

デバイスのクエリと制御を行う

REST API を使って、デバイスからのテレメトリのクエリを実行できます。 次の要求からは、特定のデバイス テンプレート ID を共有するすべてのデバイスからの加速度計データが返されます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Run a query (クエリを実行する) 要求を選びます。
  2. [Send] を選択します。

REST API を使って、デバイスのプロパティを読み取り、設定することができます。 次の要求では、デバイスで実装されているデバイス情報コンポーネントからすべてのプロパティ値が返されます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Get properties from a component (コンポーネントからプロパティを取得する) 要求を選びます。
  2. [Send] を選択します。

REST API を使ってデバイスのコマンドを呼び出すことができます。 次の要求は、スマートフォンのライトを 2 回、3 秒間だけオンにするコマンドを呼び出します。 コマンドを実行するには、IoT プラグ アンド プレイ アプリが表示された状態でスマートフォンの画面がオンになっている必要があります。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Call command (コマンドを呼び出す) 要求を選びます。
  2. [Send] を選択します。

テレメトリのエクスポート

REST API を使って、IoT Central アプリケーションを構成および管理できます。 次の手順では、テレメトリ値を Webhook に送信するようにデータ エクスポートを構成する方法を示します。 セットアップを簡単にするため、この記事では宛先として RequestBin Webhook を使います。 RequestBin は Microsoft 以外のサービスです。

データ エクスポート先のテスト エンドポイントを作成するには:

  1. RequestBin に移動します。
  2. [Create a RequestBin] (RequestBin の作成) を選びます。
  3. 使用可能ないずれかの方法でサインインします。
  4. RequestBin エンドポイントの URL をコピーします。
  5. Postman で IoT Central REST チュートリアル コレクションを開き、コレクション変数に移動します。
  6. コレクション変数で webHookURL の [現在の値] 列に RequestBin エンドポイントの URL を貼り付けます。
  7. 変更を保存します。

REST API を使って IoT Central アプリケーションでエクスポート先を構成するには:

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Create a webhook export destination (Webhook のエクスポート先を作成する) 要求を選びます。
  2. [Send] を選択します。

REST API を使って IoT Central アプリケーションでエクスポート定義を構成するには:

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Create a telemetry export definition (テレメトリ エクスポート定義を作成する) 要求を選びます。
  2. [Send] を選択します。 状態が [Not started] (未開始) になっていることに注意してください。

エクスポートが始まるまで数分かかる場合があります。 REST API を使ってエクスポートの状態を調べるには:

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Get an export by ID (ID でエクスポートを取得する) 要求を選びます。
  2. [Send] を選択します。 状態が [正常] である場合、IoT Central は Webhook にテレメトリを送信しています。

画面がオンで、IoT プラグ アンド プレイ アプリが表示されているのでない限り、スマートフォンのアプリはテレメトリを送信しません。

スマートフォン アプリがテレメトリを送信している場合は、RequestBin に移動してエクスポートされたテレメトリを表示します。

リソースをクリーンアップする

このチュートリアルで使った IoT Central アプリケーションを完了した場合は、REST API を使って削除できます。

  1. Postman で、IoT Central REST チュートリアル コレクションを開き、Delete an IoT central application (IoT Central アプリケーションを削除する) 要求を選びます。
  2. [Send] を選択します。

ヒント

この要求では、チュートリアルの開始時に生成したベアラー トークンを使います。 ベアラー トークンは 1 時間で期限が切れます。 https://apps.azureiotcentral.com へのアクセスを承認する新しいベアラー トークンを生成することが必要な場合があります。

次の手順

一連の IoT Central チュートリアルを続行し、IoT Central ソリューションの構築方法の詳細を確認するには、次のページを参照してください。

ゲートウェイ デバイス テンプレートを作成する