Использование REST API IoT Central для управления организациями

Статья
10/22/2024

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Rest API можно использовать для управления организациями в приложении IoT Central.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Дополнительные сведения о организациях в приложении IoT Central см. в статье "Управление организациями IoT Central".

REST API организаций

С помощью REST API IoT Central вы можете:

Добавление организации в приложение
Получение организации по идентификатору
Обновление организации в приложении
Получение списка организаций в приложении
Удаление организации в приложении

Создание организаций

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

Организации Вашингтон, Редмонд и Белвью автоматически имеют организацию верхнего уровня приложения по умолчанию в качестве родителя.

Удаление организации

Используйте следующий запрос для удаления организации:

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 — уникальный идентификатор маркера

В следующем примере показан текст запроса, создающий маркер API для организации сиэтла в приложении IoT Central.

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

Текст запроса содержит некоторые обязательные поля:

Имя	Описание
роль	Идентификатор одной из ролей организации
organization	Идентификатор организации

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

В следующем примере показан текст запроса, добавляющий устройство для шаблона устройства. Сведения можно получить template на странице шаблонов устройств в пользовательском интерфейсе приложения IoT Central.

{
    "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, предлагаемым шагом является использование REST API IoT Central для управления экспортом данных.

Поделиться через

Использование REST API IoT Central для управления организациями

REST API организаций

Создание организаций

Добавление организации

Обновление организации

Список организаций

Удаление организации

Использование организаций

Управление ролями

Создание маркера API, присоединенного к узлу в иерархии организации

Связывание пользователя с узлом в иерархии организации

Добавление и связывание устройства с организацией

Добавление и связывание группы устройств с организацией

Следующие шаги

Обратная связь

Дополнительные ресурсы