Como utilizar a API REST do IoT Central para gerir utilizadores e funções

Artigo
10/27/2023

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 usuários e funçõ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.

Nota

As operações em usuários e funções são registradas no log de auditoria 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.

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Para saber como gerenciar usuários e funções usando a interface do usuário do IoT Central, consulte Gerenciar usuários e funções em seu aplicativo do IoT Central.

Gerir funções

A API REST permite listar as funções definidas em seu aplicativo IoT Central. Use a seguinte solicitação para recuperar uma lista de IDs de função do seu aplicativo:

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 três funções internas e uma função personalizada:

{
  "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": "16f8533f-6b82-478f-8ba8-7e676b541b1b",
      "displayName": "Example custom role"
    }
  ]
}

Nota

Este comando mostra apenas funções associadas a um aplicativo e não a uma função personalizada no nível da organização.

Gerir utilizadores

A API REST permite:

Listar os usuários em um aplicativo
Recuperar os detalhes de um usuário individual
Criar um utilizador
Modificar um utilizador
Eliminar um utilizador

Listar utilizadores

Use a seguinte solicitação para recuperar uma lista de usuários do seu aplicativo:

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

A resposta a essa solicitação se parece com o exemplo a seguir. Os valores de função identificam o ID de função ao qual o usuário está associado:

{
  "value": [
    {
      "id": "91907508-04fe-4349-91b5-b872f3055a95",
      "type": "email",
      "roles": [
        {
          "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
        }
      ],
      "email": "user1@contoso.com"
    },
    {
      "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
      "type": "email",
      "roles": [
        {
          "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
        }
      ],
      "email": "user2@contoso.com"
    },
    {
      "id": "3ab9375e-d2d9-42da-b419-6ae86a938321",
      "type": "email",
      "roles": [
        {
          "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
        }
      ],
      "email": "user3@contoso.com"
    },
    {
      "id": "fc5a250b-83fb-433d-892c-e0a144f68c2b",
      "type": "email",
      "roles": [
        {
          "role": "16f8533f-6b82-478f-8ba8-7e676b541b1b"
        }
      ],
      "email": "user4@contoso.com"
    }
  ]
}

Obter um utilizador

Use a seguinte solicitação para recuperar detalhes de um usuário individual do seu aplicativo:

GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-07-31

A resposta a essa solicitação se parece com o exemplo a seguir. O valor da função identifica o ID da função ao qual o usuário está associado:

{
  "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user2@contoso.com"
}

Criar um utilizador

Use a solicitação a seguir para criar um usuário 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 seguinte corpo de solicitação, o role valor é para a função de operador recuperada anteriormente:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "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": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

Você também pode adicionar um usuário principal de serviço que seja útil se precisar usar a autenticação da entidade de serviço para chamadas de API REST. Para saber mais, consulte Adicionar ou atualizar um usuário principal de serviço.

Alterar a função de um utilizador

Use a solicitação a seguir para alterar a função atribuída ao usuário. Este exemplo usa a ID da função de construtor recuperada anteriormente:

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

Corpo do pedido. O valor é para a função de construtor recuperada anteriormente:

{
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

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

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ],
  "email": "user5@contoso.com"
}

Eliminar um utilizador

Use a seguinte solicitação para excluir um usuário:

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

Próximos passos

Agora que você aprendeu como gerenciar usuários e funções com a API REST, uma próxima etapa sugerida é Como usar a API REST do IoT Central para gerenciar organizações.