Como usar a API REST do IoT Central para gerenciar organizações

Artigo
10/22/2024

A API REST do IoT Central permite que você desenvolva aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para gerenciar organizações no aplicativo IoT Central.

Cada chamada à API REST do IoT Central exige um cabeçalho de autorização. Para saber mais, confira Como autenticar e autorizar chamadas à API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, confira Referência da API REST do Azure IoT Central.

Para saber mais sobre as organizações no IoT Central Application, confira Gerenciar organizações do IoT Central.

API REST de organizações

A API REST do IoT Central permite:

Adicionar uma organização ao aplicativo
Obter uma organização por ID
Atualizar uma organização no aplicativo
Obter uma lista das organizações no aplicativo
Excluir uma organização no aplicativo

Criar organizações

A API REST permite criar organizações no aplicativo IoT Central. Use a seguinte solicitação para criar uma organização no aplicativo:

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

organizationId - ID exclusiva da organização

O exemplo a seguir mostra um corpo de solicitação que adiciona uma organização a um aplicativo IoT Central.

{
  "displayName": "Seattle",
}

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: nome de exibição da organização.

O corpo da solicitação tem alguns campos opcionais:

@parent: ID do pai da organização.

Se você não especificar um pai, a organização receberá a designação da organização de nível superior padrão como pai.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "seattle",
  "displayName": "Seattle"
}

Você pode criar uma organização com hierarquia, por exemplo, é possível criar uma organização de vendas com uma organização pai.

O exemplo a seguir mostra um corpo de solicitação que adiciona uma organização a um aplicativo IoT Central.

{
  "displayName": "Sales",
  "parent":"seattle"
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

Obter uma organização

Use a solicitação a seguir para recuperar detalhes de uma organização individual no aplicativo:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

Atualizar uma organização

Use a seguinte solicitação para atualizar os detalhes de uma organização no aplicativo:

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

O exemplo a seguir apresenta um corpo de solicitação que atualiza o pai da organização:

{
  "parent": "washington"
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

Listar organizações

Use a seguinte solicitação para recuperar uma lista de organizações no aplicativo:

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

A resposta a essa solicitação é parecida com o exemplo a seguir.

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

As organizações Washington, Redmond e Bellevue recebem automaticamente como pai a organização de nível superior padrão do aplicativo.

Excluir uma organização

Use a seguinte solicitação para excluir uma organização:

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

Usar organizações

Use as organizações para gerenciar o acesso aos recursos no seu aplicativo.

Gerenciar funções

A API REST permite listar as funções definidas em seu aplicativo IoT Central. Use a solicitação a seguir para recuperar uma lista de IDs de função de aplicativo e de função de organização do seu aplicativo. Para saber mais, consulte Como gerenciar as organizações do IoT Central:

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

A resposta a essa solicitação se parece com o exemplo a seguir, que inclui as IDs da função de aplicativo e da função de organização.

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

Criar um token de API anexado a um nó em uma hierarquia da organização

Use a seguinte solicitação para criar um token de API anexado a um nó em uma hierarquia da organização no seu aplicativo:

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

tokenId – ID exclusiva do token

O exemplo a seguir mostra um corpo de solicitação que cria um token de API para a organização seattle em um aplicativo do IoT Central.

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

O corpo da solicitação tem alguns campos obrigatórios:

Nome	Descrição
role	ID de uma das funções da organização
organization	ID da organização

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Associar um usuário a um nó em uma hierarquia de organização

Use a solicitação a seguir para criar e associar um usuário a um nó em uma hierarquia de organização em seu aplicativo. A ID e o email precisam ser exclusivos no aplicativo:

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

No corpo da solicitação a seguir, role é a ID de uma das funções da organização e organization é a ID da organização

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

A resposta a essa solicitação é parecida com o exemplo a seguir. O valor de função identifica à qual função o usuário está associado:

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

Adicionar e associar um dispositivo a uma organização

Use a solicitação a seguir para associar um novo dispositivo a uma organização

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

O exemplo a seguir mostra um corpo da solicitação que adiciona um dispositivo para um modelo de dispositivo. Você pode obter os detalhes template na página de modelos de dispositivo na interface do usuário do aplicativo do IoT Central.

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

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: nome de exibição do dispositivo.
@enabled: declara que esse objeto é uma interface.
@etag: ETag usada para evitar conflitos em atualizações de dispositivo.
simulated: O dispositivo é simulado?
template: a definição de modelo de dispositivo para o dispositivo.
organizations: lista de IDs de organização das quais o dispositivo faz parte. Atualmente, você só pode associar um dispositivo a uma organização.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

Adicionar e associar um grupo de dispositivos a uma organização

Use a solicitação a seguir para criar e associar um novo grupo de dispositivos a uma organização.

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

Ao criar um grupo de dispositivos, você define um filter que seleciona os dispositivos a serem adicionados ao grupo. Um filter identifica um modelo de dispositivo e qualquer propriedade a ser correspondente. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao modelo de dtmi:modelDefinition:dtdlv2 em que a propriedade provisioned é verdadeira.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

O corpo da solicitação tem alguns campos obrigatórios:

@displayName: nome de exibição do grupo de dispositivos.
@filter: consulta que definine quais dispositivos devem estar nesse grupo.
description: resumo curto do grupo de dispositivos.
organizations: lista de IDs de organização das quais o dispositivo faz parte. Atualmente, você só pode associar um dispositivo a uma organização.

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Próximas etapas

Agora que você aprendeu a gerenciar organizações com a API REST, uma próxima etapa sugerida é Como usar a API REST do IoT Central para gerenciar exportações de dados.

Compartilhar via

Como usar a API REST do IoT Central para gerenciar organizações

API REST de organizações

Criar organizações

Obter uma organização

Atualizar uma organização

Listar organizações

Excluir uma organização

Usar organizações

Gerenciar funções

Criar um token de API anexado a um nó em uma hierarquia da organização

Associar um usuário a um nó em uma hierarquia de organização

Adicionar e associar um dispositivo a uma organização

Adicionar e associar um grupo de dispositivos a uma organização

Próximas etapas

Comentários

Recursos adicionais