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

發行項
10/22/2024

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 參考。

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

組織 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"
        }
    ]
}

Washington、Redmond 和 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 應用程式中為seattle 組織建立一個 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 會識別裝置範本和要比對的任何屬性。以下範例會建立包含與 dtmi:modelDefinition:dtdlv2 範本相關聯的所有裝置的裝置群組，其中 provisioned 屬性為 true。

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

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

新增裝置，並建立裝置與組織間的關聯

新增裝置群組，並建立與組織間的關聯

下一步

意見反應

其他資源