REST do Hub IoT

  • Artigo

As APIs REST para Hub IoT oferecem acesso programático aos serviços de dispositivo, mensagens e trabalho, bem como ao provedor de recursos, em Hub IoT. Você pode acessar os serviços de mensagem desde um serviço IoT executando no Azure ou diretamente pela Internet de qualquer aplicativo que possa enviar uma solicitação HTTPS e receber uma resposta HTTPS.

Serviço

  • Use essa API para gerenciar Hub IoT dispositivos gêmeos. Você pode recuperar e atualizar as propriedades do dispositivo gêmeo e invocar métodos diretos em dispositivos.
  • Use essas APIs para gerenciar identidades de dispositivo no registro de identidade de um hub IoT.
  • Use essas API para gerenciar trabalhos em Hub IoT. Você 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 retorna um x-ms-request-id cabeçalho que pode ser usado para obter informações sobre a solicitação. Você deve verificar se as solicitações feitas a esses recursos são seguras. Para obter mais informações, consulte Hub IoT Guia do Desenvolvedor – Segurança para as especificações sobre como criar tokens de segurança.

Mensagens do dispositivo

Use essas APIs de um dispositivo para enviar mensagens do dispositivo para a nuvem para um hub IoT e receber mensagens de nuvem para dispositivo de um hub IoT. Todas as operações da tarefa estão em conformidade com a especificação do protocolo HTTP/1.1. Você deve verificar se as solicitações feitas a esses recursos são seguras. Para obter mais informações, consulte Hub IoT Developer Guide – Segurança para obter informações específicas sobre como criar tokens de segurança.

Provedor de recursos

Use essas APIs para gerenciar a implantação de seus recursos de Hub IoT. Para obter informações sobre como proteger essas solicitações, consulte 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 a Hub IoT:

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

  • Substitua {subscription-id} pelo identificador de sua assinatura no URI.

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

  • Substitua {IoTHubName} pelo nome do hub IoT.

  • Defina o cabeçalho Content-Type como application/json.

  • Defina o cabeçalho autorização como um token SAS criado conforme especificado na seção tokens de segurança de Usando tokens de segurança Hub IoT.

  • O cabeçalho Etag é retornado em todas as solicitações com escopo para uma única identidade de dispositivo, de acordo com RFC7232.

  • Todas as operações PUT/PATCH exigem que os seguintes cabeçalhos sejam especificados: If-Match = [*|<etag from get>]

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

O comportamento das ETags pode ser visto abaixo:

PUT O recurso não existe O recurso existe
If-Match = "" / absent 201 Criado 200 OK
If-Match = "*" 412 Falha na Pré-condição 200 OK
If-Match = "xyz" 412 Falha na Pré-condição Falha na pré-condição 200 OK/412
If-None-Match = "*" 201 Criado 412 Falha na Pré-condição
Delete (excluir) O recurso não existe O recurso existe
If-Match = "" / absent 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 todas as operações assíncronas. Todas as operações síncronas (atualizações) retornam 200 OK.

  • DELETE retorna 202 Cabeçalhos aceitos com Localização e Retry-After, bem como Azure-AsyncOperation cabeçalho para recursos existentes.

  • 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 apropriado em segundos

  • Azure-AsyncOperation cabeçalho contém URL para o resultado da operação assíncrona status

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