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

  • [アーティクル]

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 を使用する場合:

  1. [アクセス許可] > [API トークン] に移動します。

  2. [+ 新規] または [API トークンの作成] を選択します。

  3. トークンの名前を入力し、ロールと組織を選択します。

  4. [Generate] \(生成) を選択します。

  5. 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 を使用する場合:

  1. 次の 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"
    }
  ]
}

  2. 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