Использование 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, присоединенного к узлу в иерархии организации

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

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

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

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

Кері байланыс

Қосымша ресурстар