如何使用 IoT Central REST API 來管理組織

發行項
10/27/2023

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以使用 REST API 來管理 IoT Central 應用程式中的組織。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入瞭解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考檔，請參閱 Azure IoT Central REST API 參考。

若要深入瞭解 IoT Central 應用程式中的組織，請參閱管理 IoT Central 組織。

提示

您可以使用 Postman 來試用本文中所述的 REST API 呼叫。下載 IoT Central Postman 集合，並將其匯入 Postman。在集合中，您必須設定變數，例如您的應用程式子域和系統管理權杖。

組織 REST API

IoT Central REST API \(英文\) 可讓您：

將組織新增至您的應用程式
依識別碼取得組織
更新應用程式中的組織
取得應用程式中的組織清單
刪除應用程式中的組織

建立組織

REST API 可讓您在 IoT Central 應用程式中建立組織。使用下列要求在應用程式中建立組織：

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

organizationId - 組織的唯一識別碼

下列範例顯示將組織新增至 IoT Central 應用程式的要求本文。

{
  "displayName": "Seattle",
}

要求本文有一些必要欄位：

@displayName：顯示組織的名稱。

要求本文有一些選擇性欄位：

@parent：組織的父系識別碼。

如果您未指定父代，則組織會取得預設最上層組織作為其父代。

此要求的回應看起來像下列範例：

{
  "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"
        }
    ]
}

華盛頓、雷德蒙德和 Bellevue 組織會自動將應用程式的預設最上層組織作為其父系。

刪除組織

使用下列要求來刪除組織：

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

使用組織

使用組織來管理應用程式中資源的存取權。

管理角色

REST API 可讓您列出 IoT Central 應用程式中定義的角色。使用下列要求，從您的應用程式擷取應用程式角色和組織角色識別碼的清單。若要深入瞭解，請參閱如何管理 IoT Central 組織：

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

此要求的回應看起來像下列範例，其中包含應用程式角色和組織角色識別碼。

{
    "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 - 權杖的唯一識別碼

下列範例示範在 IoT Central 應用程式中為西雅圖 組織建立 API 權杖 的要求本文。

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

要求本文有一些必要欄位：

名稱	描述
角色 (role)	其中一個組織角色的識別碼
組織	組織的識別碼

此要求的回應看起來像下列範例：

{
    "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"
}

將使用者與組織階層中的節點產生關聯

使用下列要求來建立使用者，並將使用者與應用程式中組織階層中的節點產生關聯。識別碼和電子郵件在應用程式中必須是唯一的：

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

在下列要求主體中， role 是其中一個組織角色的識別碼，而 organization 是組織的識別碼

{
  "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

下列範例顯示新增裝置範本之裝置的要求本文。您可以從 IoT Central 應用程式 UI 中的裝置範本頁面取得 template 詳細資料。

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

要求本文有一些必要欄位：

@displayName：裝置的顯示名稱。
@enabled：宣告這個物件是介面。
@etag：用來防止裝置更新衝突的 ETag。
simulated：裝置是否模擬？
template ：裝置的裝置範本定義。
organizations ：裝置所屬的組織識別碼清單。目前，您只能將裝置與單一組織產生關聯。

此要求的回應看起來像下列範例：

{
    "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會識別要比對的裝置範本和任何屬性。下列範例會建立裝置群組，其中包含與屬性為 true 之 dtmi:modelDefinition:dtdlv2 範本 provisioned 相關聯的所有裝置。

{
  "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": "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 權杖

將使用者與組織階層中的節點產生關聯

將裝置新增並關聯至組織

將裝置群組新增並關聯至組織

下一步

其他資源