IoT Central REST API 呼び出しを認証および承認する方法

[アーティクル]
03/01/2024

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。デバイステンプレート、デバイス、ジョブ、ユーザー、ロールなどの IoT Central アプリケーションのリソースを操作するには、REST API を使用します。

すべての IoT Central REST API 呼び出しには、IoT Central が呼び出し元の ID と、アプリケーション内で呼び出し元に付与されるアクセス許可を決定するために使用する Authorization ヘッダーが必要です。

この記事では、Authorization ヘッダーで使用できるトークンの種類と、それらを取得する方法について説明します。サービスプリンシパルは、IoT Central REST API アクセス管理に推奨されるアプローチです。

トークンの種類

REST API を使用して IoT Central アプリケーションにアクセスするには、次の方法を使用できます。

Microsoft Entra ベアラートークン。ベアラートークンは、Microsoft Entra ユーザーアカウントまたはサービスプリンシパルに関連付けられています。このトークンにより、IoT Central アプリケーションでユーザーまたはサービスプリンシパルが持っているのと同じアクセス許可が呼び出し元に付与されます。
IoT Central API トークン。 API トークンは、IoT Central アプリケーションのロールに関連付けられています。

REST API を使うオートメーションやスクリプトを開発およびテストする際には、自分のユーザーアカウントに関連付けされているベアラートークンを使ってください。実稼働のオートメーションやスクリプトには、サービスプリンシパルに関連付けられたベアラートークンを使ってください。 API トークンよりもベアラートークンを優先して使うことで、トークンの有効期限が切れた場合の漏洩や問題のリスクを軽減できます。

IoT Central のユーザーとロールの詳細については、「IoT Central アプリケーションでユーザーとロールを管理する」を参照してください。

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

Microsoft Entra ユーザーアカウントのベアラートークンを取得するには、次の Azure CLI コマンドを使用します:

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

重要

az login コマンドは、Cloud Shell を使用している場合でも必要です。

上のコマンドからの JSON 出力は、次の例のようになります。

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

ベアラートークンの有効期間は約 1 時間です。有効期間を過ぎたら、新しいものを作成する必要があります。

サービスプリンシパルのベアラートークンを取得するには、「サービスプリンシパルの認証」を参照してください。

API トークンを取得する

API トークンを取得するには、IoT Central UI または REST API 呼び出しを使用します。ルート組織に関連付けられている管理者と、適切なロールに割り当てられているユーザーは、API トークンを作成できます。

ヒント

API トークンに対する作成操作と削除操作は、監査ログに記録されます。

IoT Central UI を使用する場合:

[アクセス許可] > [API トークン] に移動します。
[+ 新規] または [API トークンの作成] を選択します。
トークンの名前を入力し、ロールと組織を選択します。
[Generate] \(生成) を選択します。
IoT Central に、次の例のようなトークンが表示されます。

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

API トークンを確認できるのは、この画面が表示されたときだけです。分からなくなった場合は、新しいものを生成する必要があります。

API トークンの有効期間は、約 1 年間です。 IoT Central アプリケーションでは、組み込みとカスタムの両方のロールに対してトークンを生成できます。 API トークンの作成時に選択した組織によって、API がアクセスできるデバイスが決まります。アプリケーションに組織を追加する前に作成された API トークンは、ルート組織に関連付けられています。

アクセスを取り消す必要がある場合は、IoT Central UI で API トークンを削除できます。

REST API を使用する場合:

次の REST API を使用して、アプリケーションからロール ID の一覧を取得します。

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

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

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

REST API を使用して、ロールの API トークンを作成します。たとえば、オペレーターロールに対して operator-token という名前の API トークンを作成するには、次のようにします。
```
PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31
```
要求本文:
```
{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}
```
上記のコマンドに対する応答は、次の JSON のようになります。
```
{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}
```
API トークンには、この応答を通じてのみアクセスできます。これを失った場合は、新しいものを生成する必要があります。

REST API を使用すると、アプリケーションで API トークンを一覧表示したり、削除したりできます。

ベアラートークンを使用する

REST API 呼び出しを行うときにベアラートークンを使用する場合、Authorization ヘッダーは次の例のようになります。

Authorization: Bearer eyJ0eX...fNQ

API トークンを使用する

REST API 呼び出しを行うときに API トークンを使用する場合、Authorization ヘッダーは次の例のようになります。

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

IoT Central REST API 呼び出しを認証および承認する方法

トークンの種類

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

API トークンを取得する

ベアラー トークンを使用する

API トークンを使用する

その他のリソース

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

ベアラートークンを使用する