你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 来管理组织

项目
10/22/2024

通过 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 组织。

组织 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	其中一个组织角色的 ID
organization	组织的 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

下面的示例演示了为设备模板添加设备的请求正文。可从 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 列表。目前，只能将一台设备与单个组织关联。

对此请求的响应如以下示例所示：

{
    "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 列表。目前，只能将一台设备与单个组织关联。

对此请求的响应如以下示例所示：

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

将用户与组织层次结构中的节点关联

添加设备并将其与组织关联

添加设备组并将其与组织关联

后续步骤

反馈

其他资源