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

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

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

前提条件

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

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

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

Azure CLI

Azure CLI を使用して REST API 呼び出しを行い、一部の 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 を実行します。

REST API を承認する

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

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

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

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

accessToken の値を書き留めておきます。このチュートリアルで後ほど使用します。

リソース グループを作成する

Azure CLI を使用して、このチュートリアルで作成する IoT Central アプリケーションを含むリソース グループを作成します。

az group create --name iot-central-rest-tutorial --location eastus

IoT Central アプリケーションを作成する

次のコマンドを使用して、このチュートリアルで使用するランダムな名前を持つ IoT Central アプリケーションを生成します。

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

アプリケーション名を書き留めておきます。このチュートリアルで後ほど使用します。

API トークンを作成する

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

Azure CLI を使用して operator-token というオペレーター トークンを作成するには、次のコマンドを実行します。 ロール GUID は、すべての IoT Central アプリケーションのオペレーター ロールの ID です。

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

コマンドから返されたオペレーター トークンを書き留めておきます。このチュートリアルで後ほど使用します。 このトークンは SharedAccessSignature sr=2... のようになります。

Azure CLI を使用して admin-token という管理者トークンを作成するには、次のコマンドを実行します。 ロール GUID は、すべての IoT Central アプリケーションの管理者ロールの ID です。

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

コマンドから返された管理者トークンを書き留めておきます。このチュートリアルで後ほど使用します。 このトークンは SharedAccessSignature sr=2... のようになります。

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

デバイスの登録

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

コマンドから返された idScope と primaryKey の値を書き留めておきます。このチュートリアルで後ほど使用します。

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

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

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

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

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

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

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

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

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

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

コマンドから返された template の値を書き留めておきます。このチュートリアルで後ほど使用します。

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

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

このチュートリアルで使った IoT Central アプリケーションを使い終えたら、削除することができます。

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial