Share via

IoT Central REST API を使用してファイルをアップロードする方法

  • [アーティクル]

IoT Central では、接続されているデバイスからクラウド ストレージにメディアやその他のファイルをアップロードできます。 IoT Central アプリケーションでファイルのアップロード機能を構成してから、デバイスのコードでファイルのアップロードを実装します。 この記事では、次のことについて説明します:

  • REST API を使って、IoT Central アプリケーションでファイル アップロード機能を構成します。
  • サンプル デバイス コードを実行して、ファイルのアップロードをテストします。

IoT Central REST API を使用すると、次のことができます。

  • ファイル アップロード ストレージ アカウントの構成を追加する
  • ファイル アップロード ストレージ アカウントの構成を更新する
  • ファイル アップロード ストレージ アカウントの構成を取得する
  • ファイル アップロード ストレージの構成を削除する

すべての IoT Central REST API 呼び出しに承認ヘッダーが必要です。 詳細については、「IoT Central REST API 呼び出しを認証および承認する方法」を参照してください。

IoT Central REST API のリファレンス ドキュメントについては、「Azure IoT Central REST API リファレンス」をご覧ください。

ヒント

Postman を使用して、この記事で説明されている REST API 呼び出しを試してみることができます。 IoT Central Postman コレクションをダウンロードし、Postman にインポートしてください。 コレクションでは、アプリのサブドメインや管理者トークンなどの変数を設定する必要があります。

IoT Central UI を使用してファイルをアップロードする方法については、ファイルのアップロードを構成する方法に関するページを参照してください。

前提条件

ファイルのアップロードをテストするには、ローカル開発環境に次の前提条件をインストールします。

ファイル アップロード ストレージ アカウントの構成を追加する

ファイル アップロード ストレージ アカウントの構成を追加するには。

ストレージ アカウントの作成

Azure Storage REST API を使うには、management.azure.com リソース用のベアラー トークンが必要です。 ベアラー トークンを取得するには、Azure CLIを使用できます。

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

BLOB 用のストレージ アカウントがない場合は、次の要求を使ってサブスクリプションに作成できます。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01

要求ヘッダーには、次のフィールドがあります。

  • subscriptionId: ターゲット サブスクリプションの ID。
  • resourceGroupName: サブスクリプション内のリソース グループの名前。 名前の大文字と小文字は区別されます。
  • accountName: 指定したリソース グループ内のストレージ アカウントの名前。 ストレージ アカウント名の長さは 3 ～ 24 文字で、数字と小文字のみを使用する必要があります。

要求本文には、次の必須フィールドがあります。

  • kind: ストレージ アカウントの種類
  • location: リソースが存在する地理的な場所
  • sku: SKU 名。
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

コンテナーの作成

ストレージ アカウントに BLOB 用の fileuploads という名前のコンテナーを作成するには、次の要求を使います。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
  • containerName: BLOB コンテナー名は、長さが 3 から 63 文字で、数字、小文字、ダッシュ (-) のみが使われている必要があります。 すべてのダッシュ (-) 文字は、その直前および直後に文字または数字が使用されている必要があります。

次の例のように、この要求で空の要求本文を送信します。

{
}

この要求に対する応答は、次の例のようになります。

{
  "id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
  "name": "fileuploads",
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}

ストレージ アカウント キーの取得

IoT Central でアップロードを構成するときに必要なストレージ アカウント キーを取得するには、次の要求を使います。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01

この要求に対する応答は、次の例のようになります。

{
  "keys": [
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key1",
      "value": "j3UTm**************==",
      "permissions": "FULL"
    },
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key2",
      "value": "Nbs3W**************==",
      "permissions": "FULL"
    }
  ]
}

アップロードの構成を作成する

IoT Central アプリケーションでファイル アップロードの BLOB ストレージ アカウントの構成を作成するには、次の要求を使います。

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

要求本文には次のフィールドが含まれます。

  • account: ファイルのアップロード先のストレージ アカウント名。
  • connectionString: ストレージ アカウントに接続するための接続文字列。 AccountKey の値としては、前の listKeys 要求で取得した value 値の 1 つを使います。
  • container: ストレージ アカウント内のコンテナーの名前。 次の例では、fileuploads という名前を使います。
  • etag: 複数のアップロードでの競合を防ぐ ETag
  • sasTtl: ISO 8601 期間標準。ファイルをアップロードするデバイスの要求が期限切れになるまでの有効な時間。
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

この要求に対する応答は、次の例のようになります。

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

ファイル アップロード ストレージ アカウントの構成を取得する

IoT Central アプリケーションでファイル アップロードの BLOB ストレージ アカウントの構成の詳細を取得するには、次の要求を使います。

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

この要求に対する応答は、次の例のようになります。

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

ファイル アップロード ストレージ アカウントの構成を更新する

IoT Central アプリケーションでファイル アップロードの BLOB ストレージ アカウントの接続文字列を更新するには、次の要求を使用します。

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

この要求に対する応答は、次の例のようになります。


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

ファイル アップロード ストレージ アカウントの構成を削除する

ストレージ アカウントの構成を削除するには、次の要求を使います。

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

ファイルのアップロードをテストする

IoT Central アプリケーションでファイルのアップロードを構成した後は、サンプル コードを使ってそれをテストできます。 ファイル アップロード サンプル リポジトリをまだクローンしていない場合は、次のコマンドを使って、ローカル コンピューター上の適切な場所にそれをクローンし、依存パッケージをインストールします。

git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build

デバイス テンプレートを作成してモデルをインポートする

ファイルのアップロードをテストするには、サンプル デバイス アプリケーションを実行します。 サンプル デバイスで使うデバイス テンプレートを作成します。

  1. IoT Central UI でアプリケーションを開きます。

  2. 左ウィンドウの [Device Templates]\(デバイス テンプレート\) タブに移動し、[+ 新規] を選択します:

  3. テンプレートの種類として [IoT デバイス] を選びます。

  4. ウィザードの [カスタマイズ] ページで、デバイス テンプレートの名前 ("ファイル アップロード デバイス サンプル" など) を入力します。

  5. [Review](レビュー) ページで、 [Create](作成) を選択します。

  6. [モデルのインポート] を選び、前にダウンロードしたリポジトリ内の iotc-file-upload-device\setup フォルダーから FileUploadDeviceDcm.json モデル ファイルをアップロードします。

  7. [発行] を選択して、デバイス テンプレートを発行します。

デバイスを追加する

Azure IoT Central アプリケーションへ新しいデバイスを追加するには、次の操作を実行します。

  1. 左側のウィンドウで [デバイス] を選択します。

  2. 前に作成したファイル アップロード デバイス サンプル デバイス テンプレートを選びます。

  3. [+ 新規] を選んで、[作成] を選びます。

  4. 作成したデバイスを選択し、[接続] を選択します

ID scope、Device ID、Primary key の値をコピーします。 これらの値は、デバイス サンプル コードで使用します。

サンプル コードを実行します。

VS コードでダウンロードした Git リポジトリを開きます。 プロジェクトのルートに ".env" ファイルを作成し、前にコピーした値を追加します。 ファイルは、前に記録した値を含む次のサンプルのようになります。

scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1

VS コードでダウンロードした Git リポジトリを開きます。 F5 キーを押してサンプルを実行およびデバッグします。 ターミナル ウィンドウに、デバイスが登録されて、IoT Central に接続されていることが表示されます。

Starting IoT Central device...
 > Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}

サンプル プロジェクトには、datafile.json という名前のサンプル ファイルが付属しています。 このファイルは、IoT Central アプリケーションで [ファイルのアップロード] コマンドを使用するとアップロードされます。

アップロードをテストするには、アプリケーションを開き、作成したデバイスを選択します。 [コマンド] タブを選ぶと、[実行] という名前のボタンが表示されます。 そのボタンを選ぶと、IoT Central アプリがデバイスでダイレクト メソッドを呼び出してファイルをアップロードします。 このダイレクト メソッドは、/device.ts ファイルのサンプル コードで確認できます。 このメソッドの名前は uploadFileCommand です。

ファイルのアップロードの状態を確認するには、[生データ] タブを選びます。

Screenshot showing the U I of how to verify a file upload.

REST API を呼び出して、ストレージ コンテナーでのファイル アップロードの状態を確認することもできます。

次のステップ

REST API を使ってファイルのアップロードを構成する方法を理解したので、次のステップとしては、IoT Central GUI からデバイス テンプレートを作成する方法をお勧めします。