Como autenticar e autorizar as chamadas à API REST do IoT Central

Artigo
03/11/2024

A API REST do IoT Central permite que você desenvolva aplicativos cliente que se integram aos aplicativos do IoT Central. Use a API REST para trabalhar com recursos no aplicativo do IoT Central, como modelos de dispositivo, dispositivos, trabalhos, usuários e funções.

Cada chamada à API REST do IoT Central exige um cabeçalho de autorização que o IoT Central usa para determinar a identidade do chamador e as permissões que ele recebeu no aplicativo.

Este artigo descreve os tipos de token que você pode usar no cabeçalho de autorização e como obtê-los. As entidades de serviço são a abordagem recomendada para o gerenciamento de acesso à API REST do IoT Central.

Tipos de token

Para acessar um aplicativo do IoT Central usando a API REST, você pode usar um:

Token de portador do Microsoft Entra. Um token de portador está associado a uma conta de usuário ou entidade de serviço do Microsoft Entra. O token concede ao chamador as mesmas permissões do usuário ou entidade de serviço no aplicativo do IoT Central.
Token de API do IoT Central. Um token de API está associado a uma função no aplicativo do IoT Central.

Use um token de portador associado à sua conta de usuário enquanto desenvolve e testa a automação e os scripts que usam a API REST. Use um token de portador associado a uma entidade de serviço para automação de produção e scripts. Prefira usar um token de portador a um token de API a fim de reduzir o risco de vazamentos e problemas quando os tokens expirarem.

Para saber mais sobre usuários e funções no IoT Central, confira Gerenciar usuários e funções no aplicativo do IoT Central.

Obter um token de portador

Para obter um token de portador para sua conta de usuário do Microsoft Entra, use os seguintes comandos da CLI do Azure:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Importante

O comando az login é necessário mesmo quando você está usando o Cloud Shell.

A saída JSON do comando anterior se parece com o seguinte exemplo:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

O token de portador é válido por aproximadamente uma hora, após a qual você precisará criar outro.

Para obter um token de portador para uma entidade de serviço, consulte Autenticação da entidade de serviço.

Obter um token de API

Para obter um token de API, use a interface do usuário do IoT Central ou uma chamada à API REST. Os administradores associados à organização raiz e aos usuários atribuídos à função correta podem criar tokens de API.

Dica

As operações de criação e exclusão em tokens de API são registradas no log de auditoria.

Na interface do usuário do IoT Central:

Acesse Permissões e Tokens de API.
Selecione + Novo ou Criar um token de API.
Insira um nome para o token e selecione uma função e organização.
Selecione Gerar.
O IoT Central exibe o token semelhante ao seguinte exemplo:

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

Essa tela é a única vez que você pode ver o token de API, se você o perder, precisará gerar um novo.

Um token de API é válido por aproximadamente um ano. Você pode gerar tokens para funções internas e personalizadas no aplicativo do IoT Central. A organização que você escolhe ao criar o token de API determina a quais dispositivos a API tem acesso. Todos os tokens de API criados antes de adicionar as organizações ao seu aplicativo são associados à organização raiz.

Você poderá excluir tokens de API na interface do usuário do IoT Central se precisar revogar o acesso.

Uso da API REST:

Use a API REST para recuperar uma lista de IDs de função do aplicativo:

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

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

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

Use a API REST para criar um token de API para uma função. Por exemplo, para criar um token de API chamado operator-token para a função de operador:

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

Corpo da solicitação:

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

A resposta ao comando anterior é semelhante ao seguinte JSON:

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

Essa resposta é a única vez que você tem acesso ao token de API, se você o perder, precisará gerar um novo.

Você pode usar a API REST para listar e excluir tokens de API em um aplicativo.

Usar um token de portador

Para usar um token de portador ao fazer uma chamada à API REST, o cabeçalho de autorização é semelhante ao seguinte exemplo:

Authorization: Bearer eyJ0eX...fNQ

Usar um token de API

Para usar um token de API ao fazer uma chamada à API REST, o cabeçalho de autorização deve ser semelhante ao seguinte exemplo:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

Compartilhar via