IoT Central REST API を使用して組織を管理する方法

[アーティクル]
10/22/2024

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 RREST API を使用して、IoT Central アプリケーションで組織を管理できます。

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

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

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

組織の REST API

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

アプリケーションに組織を追加する
ID で組織を取得する
アプリケーション内の組織を更新する
アプリケーション内の組織のリストを取得する
アプリケーション内の組織を削除する

組織を作成する

この REST API を使用すると、お使いの IoT Central アプリケーション内で組織を作成できます。お使いのアプリケーション内で組織を作成するには、次の要求を使用します。

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

organizationId - 組織の一意の ID

次の例は、IoT Central アプリケーションに組織を追加する要求本文を示しています。

{
  "displayName": "Seattle",
}

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

@displayName: 組織の表示名。

要求本文には、いくつかの省略可能なフィールドがあります。

@parent: 組織の親の ID。

親を指定しない場合、組織には既定のトップレベルの組織がその親として取得されます。

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

{
  "id": "seattle",
  "displayName": "Seattle"
}

階層を持つ組織を作成できます。たとえば、親組織を持つ販売組織を作成できます。

次の例は、IoT Central アプリケーションに組織を追加する要求本文を示しています。

{
  "displayName": "Sales",
  "parent":"seattle"
}

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

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

組織を取得する

お使いのアプリケーションから個々の組織の詳細を取得するには、次の要求を使用します。

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

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

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

組織の更新

お使いのアプリケーションで組織の詳細を更新するには、次の要求を使用します。

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

次の例は、組織の親を更新する要求本文を示しています。

{
  "parent": "washington"
}

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

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

組織を一覧表示する

アプリケーションから組織のリストを取得するには、次の要求を使用します。

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

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

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

Washington、Redmond、Bellevue の組織では、アプリケーションの既定の最上位の組織が自動的に親になります。

組織を削除する

組織を削除するには、次の要求を使用します。

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

組織の使用

組織を使用して、アプリケーション内のリソースへのアクセスを管理します。

ロールの管理

REST API を使用すると、お使いの IoT Central アプリケーション内で定義されているロールのリストを表示できます。お使いのアプリケーションからアプリケーションロールおよび組織ロールの ID のリストを取得するには、次の要求を使用します。詳細については、IoT Central 組織を管理する方法に関する記事を参照してください。

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

この要求に対する応答は次の例のようになります。これにはアプリケーションロールと組織ロールの ID が含まれます。

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

組織階層内のノードにアタッチされる API トークンを作成する

次の要求を使用して、アプリケーション内の組織階層内のノードにアタッチされる API トークンを作成します。

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

tokenId - トークンの一意の ID

次の例は、IoT Central アプリケーションで seattle 組織の API トークンを作成する要求本文を示しています。

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

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

名前	説明
role	組織のロールの 1 つの ID
組織	組織の ID

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

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

ユーザーを組織階層内のノードに関連付ける

次の要求を使用して、ユーザーを作成してアプリケーション内の組織階層内のノードに関連付けます。 ID とメールアドレスは、アプリケーション内で一意である必要があります。

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

次の要求本文では、role は組織の役割の ID であり、organization は組織の ID です。

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

この要求に対する応答は、次の例のようになります。ロールの値により、ユーザーが関連付けられているロールが特定されます。

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

デバイスを追加して組織に関連付ける

次の要求を使用して、新しいデバイスを組織に関連付けます

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

次の例では、デバイステンプレートのデバイスを追加する要求本文を示しています。 template 詳細は、IoT Central アプリケーション UI の [デバイステンプレート] ページから取得できます。

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

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

@displayName: デバイスの表示名。
@enabled: このオブジェクトがインターフェイスであることを宣言します。
@etag: デバイスの更新で競合を防ぐために使用される ETag。
simulated: デバイスはシミュレートされていますか?
template : デバイスのデバイステンプレートの定義。
organizations : デバイスが属している組織 ID のリスト。現時点では、デバイスを 1 つの組織にのみ関連付けることができます。

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

デバイスグループを追加して組織に関連付ける

次の要求を使用して、新しいデバイスグループを作成し、組織に関連付けます。

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

デバイスグループを作成するときに、グループに追加するデバイスを選択する filter を定義します。 filter は、デバイステンプレートと、一致するプロパティを識別します。次の例では、provisioned プロパティが true である dtmi:modelDefinition:dtdlv2 テンプレートに関連付けられているすべてのデバイスを含むデバイスグループを作成します。

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

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

@displayName: デバイスグループの表示名。
@filter: このグループに含める必要があるデバイスを定義するクエリ。
description: デバイスグループの簡単な概要。
organizations : デバイスが属している組織 ID のリスト。現時点では、デバイスを 1 つの組織にのみ関連付けることができます。

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

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

次のステップ

REST API を使用して組織を管理する方法を学習したので、推奨される次のステップは「IoT Central REST API を使用してデータエクスポートを管理する方法」です。

次の方法で共有

IoT Central REST API を使用して組織を管理する方法

組織の REST API

組織を作成する

組織を取得する

組織の更新

組織を一覧表示する

組織を削除する

組織の使用

ロールの管理

組織階層内のノードにアタッチされる API トークンを作成する

ユーザーを組織階層内のノードに関連付ける

デバイスを追加して組織に関連付ける

デバイスグループを追加して組織に関連付ける

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT Central REST API を使用して組織を管理する方法

組織の REST API

組織を作成する

組織を取得する

組織の更新

組織を一覧表示する

組織を削除する

組織の使用

ロールの管理

組織階層内のノードにアタッチされる API トークンを作成する

ユーザーを組織階層内のノードに関連付ける

デバイスを追加して組織に関連付ける

デバイス グループを追加して組織に関連付ける

次のステップ

フィードバック

その他のリソース

デバイスグループを追加して組織に関連付ける