Como usar a API REST do IoT Central para gerenciar usuários e funções

Artigo
02/08/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 usuários e funções em seu 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.

Observação

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, confira Referência da API REST do Azure IoT Central.

Dica

Você pode usar o Postman para experimentar as chamadas à API REST descritas neste artigo. Baixe a coleção do Postman do IoT Central 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.

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

Observação

Esse comando mostra apenas as funções associadas a um aplicativo e não a uma função personalizada a nível de organização.

Gerenciar usuários

A API REST permite que você:

Liste os usuários em um aplicativo
Recupere os detalhes de um usuário individual
Criar um usuário
Modifique um usuário
Excluir um usuário

Listar usuários

Use a solicitação a seguir 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 é parecida com o exemplo a seguir. Os valores de função identificam a ID da função à 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 usuário

Use a solicitação a seguir 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 é parecida com o exemplo a seguir. O valor de função identifica a ID da função à 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 usuário

Use a solicitação a seguir para criar um usuário 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, o valor role é destinado à função de operador que você recuperou anteriormente:

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

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

Alterar a função de um usuário

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 que você recuperou anteriormente:

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

Corpo da solicitação. O valor é para a função de construtor que você recuperou anteriormente:

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

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

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

Excluir um usuário

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óximas etapas

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