HUB IOT REST

  • Artigo

As APIs REST para Hub IoT oferecem acesso programático ao dispositivo, mensagens e serviços de trabalho, bem como ao fornecedor de recursos, em Hub IoT. Pode aceder aos serviços de mensagens a partir de um serviço IoT em execução no Azure ou diretamente através da Internet a partir de qualquer aplicação que possa enviar um pedido HTTPS e receber uma resposta HTTPS.

Serviço

  • Utilize esta API para gerir Hub IoT dispositivos duplos. Pode obter e atualizar as propriedades do dispositivo duplo e invocar métodos diretos nos dispositivos.
  • Utilize estas APIs para gerir identidades de dispositivos no registo de identidades de um hub IoT.
  • Utilize estas API para gerir Tarefas no Hub IoT. Pode agendar, cancelar ou obter um trabalho.

Todas as operações de tarefa estão em conformidade com a especificação do protocolo HTTP/1.1 e cada operação devolve um x-ms-request-id cabeçalho que pode ser utilizado para obter informações sobre o pedido. Deve certificar-se de que os pedidos efetuados a estes recursos estão protegidos. Para obter mais informações, consulte Hub IoT Guia do Programador – Segurança para obter as especificações sobre como criar tokens de segurança.

Mensagens de Dispositivo

Utilize estas APIs a partir de um dispositivo para enviar mensagens do dispositivo para a cloud para um hub IoT e receber mensagens da cloud para o dispositivo a partir de um hub IoT. Todas as operações de tarefas estão em conformidade com a especificação do protocolo HTTP/1.1. Deve certificar-se de que os pedidos efetuados a estes recursos estão protegidos. Para obter mais informações, consulte Hub IoT Guia do Programador – Segurança para obter informações específicas sobre como criar tokens de segurança.

Fornecedor de Recursos

Utilize estas APIs para gerir a implementação dos seus recursos Hub IoT. Para obter informações sobre como proteger estes pedidos, veja Referência da API REST do Azure.

Parâmetros e cabeçalhos comuns

As seguintes informações são comuns a todas as tarefas relacionadas com Hub IoT:

  • Substitua {api-version} por "2018-06-30" no URI.

  • Substitua {subscription-id} pelo identificador de subscrição no URI.

  • Substitua {resourceGroupName} pelo nome do grupo de recursos que contém (ou irá conter) o hub IoT.

  • Substitua {IoTHubName} pelo nome do seu hub IoT.

  • Defina o cabeçalho Tipo de Conteúdo como aplicação/json.

  • Defina o cabeçalho autorização para um token de SAS criado conforme especificado na secção tokens de segurança de Utilizar tokens de segurança Hub IoT.

  • O cabeçalho Etag é devolvido em todos os pedidos no âmbito de uma única identidade de dispositivo, de acordo com RFC7232.

  • Todas as operações PUT/PATCH requerem a especificação dos seguintes cabeçalhos: If-Match = [*|<etag from get>]

  • As operações DELETE podem incluir o seguinte cabeçalho: If-Match = [*|<etag from get>]

O comportamento dos ETags pode ser visto abaixo:

PUT O recurso não existe O recurso existe
If-Match = "" /ausente 201 Criado 200 OK
If-Match = "*" Falha na Pré-condição 412 200 OK
If-Match = "xyz" Falha na Pré-condição 412 Falha na Pré-condição 200 OK/412
If-None-Match = "*" 201 Criado Falha na Pré-condição 412
DELETE O recurso não existe O recurso existe
If-Match = "" /ausente 204 Sem Conteúdo 200 OK
If-Match = "*" 204 Sem Conteúdo 200 OK
If-Match = "xyz" 204 Sem Conteúdo Falha na Pré-condição 200 OK/412

Para chamadas assíncronas:

  • PUT responde com 201 Criado com Azure-AsyncOperation cabeçalho para quaisquer operações assíncronas. Todas as operações síncronas (atualizações) devolvem 200 OK.

  • DELETE devolve 202 Aceite com cabeçalhos de Localização e Retry-After, bem como Azure-AsyncOperation cabeçalho para recursos que existem.

  • O cabeçalho de localização contém URL para o resultado da operação

  • Retry-After cabeçalho contém o intervalo de repetição adequado em segundos

  • Azure-AsyncOperation cabeçalho contém URL para o estado do resultado da operação Assíncrona

  • Após a conclusão, o URL get to the operation result gera exatamente o mesmo resultado que se a operação original tivesse sido concluída de forma síncrona