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

Artigo
10/22/2024

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

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

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

Para saber mais sobre organizações no Aplicativo IoT Central, consulte Gerenciar organizações do IoT Central.

API REST das organizações

A API REST do IoT Central permite:

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

Criar organizações

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

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

organizationId - ID exclusivo da organização

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

{
  "displayName": "Seattle",
}

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

@displayName: Nome para 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 obterá a organização de nível superior padrão como pai.

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Você pode criar uma organização com hierarquia, por exemplo, você pode 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 do IoT Central.

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Obter uma organização

Use a seguinte solicitação para recuperar detalhes de uma organização individual do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Atualizar uma organização

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

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

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

{
  "parent": "washington"
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Listar organizações

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

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

A resposta a essa solicitação se parece 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 têm automaticamente a organização de nível superior padrão do aplicativo como pai.

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

Organizações de uso

Use organizações para gerenciar o acesso a recursos em seu aplicativo.

Gerir 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 da organização do seu aplicativo. Para saber mais, consulte Como gerenciar 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 de função de aplicativo e de função da 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 Criar um token de API anexado a um nó em uma hierarquia da organização em seu aplicativo:

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

tokenId - ID exclusivo 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 IoT Central.

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

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

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
    "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 da organização

Use a solicitação a seguir para criar e associar um usuário a um nó em uma hierarquia da organização em seu aplicativo. O ID e o e-mail devem 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, o é a role 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 se parece com o exemplo a seguir. O valor da função identifica a 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 seguinte solicitação 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 de solicitação que adiciona um dispositivo para um modelo de dispositivo. Você pode obter os template detalhes na página de modelos de dispositivo na interface do usuário do aplicativo 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 este objeto é uma interface.
@etag: ETag usado para evitar conflitos em atualizações de dispositivos.
simulated: O dispositivo é simulado?
template : A definição de modelo de dispositivo para o dispositivo.
organizations : Lista de IDs da organização da qual o dispositivo faz parte. Atualmente, você só pode associar um dispositivo a uma única organização.

A resposta a essa solicitação se parece com o exemplo a seguir:

{
    "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. A filter identifica um modelo de dispositivo e todas as propriedades a serem correspondidas. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao dtmi:modelDefinition:dtdlv2 modelo onde a provisioned propriedade é true.

{
  "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 para exibição do grupo de dispositivos.
@filter: Consulta definindo quais dispositivos devem estar neste grupo.
description: Breve resumo do grupo de dispositivos.
organizations : Lista de IDs da organização da qual o dispositivo faz parte. Atualmente, você só pode associar um dispositivo a uma única organização.

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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óximos passos

Agora que você aprendeu como 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.

Partilhar via

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

API REST das organizações

Criar organizações

Obter uma organização

Atualizar uma organização

Listar organizações

Excluir uma organização

Organizações de uso

Gerir 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 da organização

Adicionar e associar um dispositivo a uma organização

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

Próximos passos

Comentários

Recursos adicionais