Entender e chamar métodos diretos do Hub IoT

  • Artigo

O Hub IoT oferece a capacidade de invocar métodos diretos em dispositivos a partir da nuvem. Os métodos diretos representam uma interação entre solicitação e resposta com um dispositivo semelhante a uma chamada HTTP, na qual eles são bem-sucedidos ou falham imediatamente (depois que o tempo limite especificado pelo usuário é atingido). Essa abordagem é útil para cenários em que o curso de ação imediata é diferente dependendo se o dispositivo foi capaz de responder.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Cada método de dispositivo tem como alvo um único dispositivo. Agendar trabalhos em vários dispositivos mostra como oferecer uma maneira de invocar métodos diretos em vários dispositivos e agendar invocação de método para dispositivos desconectados.

Qualquer pessoa com permissões de conectar serviço no Hub IoT pode invocar um método em um dispositivo.

Os métodos diretos seguem um padrão de solicitação e resposta e se destinam a comunicações que exigem confirmação imediata de seus resultados. Por exemplo, controle interativo do dispositivo, como ativar um ventilador.

Veja as diretrizes de comunicação da nuvem para o dispositivo se está em dúvida entre o uso de propriedades desejadas, métodos diretos ou mensagens da nuvem para o dispositivo.

Ciclo de vida do método

Os métodos diretos são implementados no dispositivo e podem precisar ou não de entradas no conteúdo do método para instanciar corretamente. Você invoca um método direto por meio de um URI voltado para serviços ({iot hub}/twins/{device id}/methods/). Um dispositivo recebe métodos diretos por meio de um tópico MQTT específico do dispositivo ($iothub/methods/POST/{method name}/) ou de links do AMQP (as propriedades de aplicativo IoThub-methodname e IoThub-status).

Observação

Quando você invoca um método direto em um dispositivo, os valores e nomes de propriedade só podem conter caracteres alfanuméricos imprimíveis US-ASCII, exceto pelo seguinte conjunto: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Os métodos diretos são síncronos e obtêm êxito ou falham após o tempo limite (padrão: 30 segundos; configurável entre 5 e 300 segundos). Os métodos diretos são úteis em cenários interativos em que você deseja que um dispositivo atue somente, e somente se, o dispositivo estiver online e recebendo comandos. Por exemplo, ativar a luz de um telefone. Nesses cenários, você deseja ver uma falha ou êxito imediatamente, para que o serviço de nuvem possa atuar quanto ao resultado o mais rápido possível. O dispositivo pode retornar algum corpo de mensagem como resultado do método, mas não é obrigatório que o método faça isso. Não há nenhuma garantia quanto à ordenação ou semântica de simultaneidade nas chamadas de método.

Os métodos diretos servem somente para HTTPS do lado da nuvem, e MQTT, AMQP, MQTT sobre WebSockets, ou AMQP sobre WebSockets do lado do dispositivo.

A carga das solicitações e respostas do método é um documento JSON de até 128 KB.

Invocar um método direto de um aplicativo back-end

Para invocar um método direto de um aplicativo de back-end, use a API REST do método Invoke device ou seu equivalente em um dos SDKs do serviço de Hub IoT.

Invocação de método

As invocações de método direto em um dispositivo são chamadas HTTPS, compostas pelos itens a seguir:

  • O URI de Solicitação específico para o dispositivo em conjunto com a versão da API:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • A método POST

  • Cabeçalhos que contêm a autorização, o tipo de conteúdo e a codificação de conteúdo.

  • Um corpo JSON transparente no seguinte formato:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

O valor fornecido como responseTimeoutInSeconds na solicitação é a quantidade de tempo que o serviço do Hub IoT deve aguardar para a conclusão de uma execução de método direto em um dispositivo. Defina esse tempo limite como a duração mínima do tempo de execução esperado de um método direto por um dispositivo. Se o tempo limite não for fornecido, o valor padrão de 30 segundos será usado. Os valores mínimo e máximo para responseTimeoutInSeconds são 5 e 300 segundos, respectivamente.

O valor fornecido como connectTimeoutInSeconds na solicitação é a quantidade de tempo na invocação de um método direto que o serviço do Hub IoT deve aguardar para que um dispositivo desconectado fique online. O valor padrão é 0, significando que os dispositivos já devem estar online na invocação de um método direto. O valor máximo de connectTimeoutInSeconds é 300 segundos.

Exemplo

Este exemplo permitirá que você inicie com segurança uma solicitação para invocar um método direto em um dispositivo IoT registrado para um hub IoT do Azure.

Para começar, use a extensão do Microsoft Azure IoT para a CLI do Azure para criar um SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Em seguida, substitua o cabeçalho de autorização pelo SharedAccessSignature recém-gerado e, em seguida, modifique os parâmetros iothubName, deviceIdmethodName e payload para corresponder à sua implementação no comando de exemplo curl abaixo.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Execute o comando modificado para invocar o método direto especificado. As solicitações bem-sucedidas retornarão um código de status HTTP 200.

Observação

O exemplo acima demonstra como invocar um método direto em um dispositivo. Caso você queira invocar um método direto em um módulo do IoT Edge, seria necessário modificar a solicitação de URL, conforme mostrado abaixo:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Resposta

O aplicativo de back-end recebe uma resposta que é composta pelos itens a seguir:

  • Código de Status HTTP:

    • 200 indica a execução bem-sucedida do método direto;
    • 404 indica que a identidade do dispositivo é inválida ou que o dispositivo não estava online após a invocação de um método direto e para connectTimeoutInSeconds em seguida (use a mensagem de erro apresentada para reconhecer a causa raiz);
    • 504 indica tempo limite de gateway causado pelo dispositivo não responder a uma chamada de método direta em responseTimeoutInSeconds.

  • Cabeçalhos que contêm a ID da solicitação, o tipo de conteúdo e a codificação de conteúdo.

  • Um corpo JSON no seguinte formato:

    {
    "status" : 201,
    "payload" : {...}
}

    status e payload são fornecidos pelo dispositivo e usados para responder com o código de status e a resposta do método.

Invocação de método para módulos do Azure IoT Edge

Há suporte para invocar os métodos diretos em um módulo na API REST do método Invoke module ou seu equivalente em um dos SDKs do serviço de Hub IoT.

O moduleId é passado juntamente com o deviceId no URI de solicitação ao usar a API REST ou como parâmetro ao usar um SDK de serviço. Por exemplo, https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. O corpo da solicitação e a resposta são semelhantes aos dos métodos diretos invocados no dispositivo.

Tratar um método direto em um dispositivo

Em um dispositivo IoT, os métodos diretos podem ser recebidos por MQTT, AMQP ou qualquer um desses protocolos por WebSockets. Os SDKs do dispositivo de Hub IoT ajudam você a receber e responder a métodos diretos nos dispositivos, sem a necessidade de se preocupar com os detalhes do protocolo subjacente.

MQTT

A seção a seguir é para o protocolo MQTT. Para saber mais sobre como usar o protocolo MQTT diretamente com o Hub IoT, confira Suporte ao protocolo MQTT.

Invocação de método

Os dispositivos recebem solicitações de método direto sobre o tópico MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. No entanto, o request id é gerado pelo Hub IoT e não pode ser divulgado com antecedência. Portanto, assine o $iothub/methods/POST/# e filtre as mensagens entregues de acordo com os nomes de método compatíveis com o dispositivo. (Você usará o request id para responder.)

O corpo que o dispositivo recebe está no seguinte formato:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

As solicitações de método são QoS 0.

Resposta

O dispositivo envia as respostas para $iothub/methods/res/{status}/?$rid={request id}, em que:

  • A propriedade status é o status de execução fornecido pelo dispositivo da execução do método.

  • A propriedade $rid é a ID de solicitação de invocação do método recebida do Hub IoT. A ID da solicitação é um valor formatado em hexadecimal.

O corpo é definido pelo dispositivo e pode ter qualquer status.

AMQP

A seção a seguir é para o protocolo AMQP. Para saber mais sobre como usar o protocolo AMQP diretamente com o Hub IoT, confira Suporte ao protocolo AMQP.

Invocação de método

O dispositivo recebe solicitações de método direto criando um link de recebimento no endereço amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

A mensagem do AMQP chega ao link de recebimento que representa a solicitação do método. Ele contém as seções a seguir:

  • A propriedade de ID de correlação, que contém uma ID de solicitação que deve ser passada de volta com a resposta do método correspondente.

  • Uma propriedade de aplicativo chamada IoThub-methodname, que contém o nome do método que está sendo invocado.

  • O corpo da mensagem do AMQP que contém a carga do método como JSON.

Resposta

O dispositivo cria um link de envio para retornar a resposta do método no endereço amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

A resposta do método é retornada no link de envio e é estruturada da seguinte forma:

  • A propriedade de ID de correlação, que contém a ID da solicitação passada na mensagem de solicitação do método.

  • Uma propriedade de aplicativo chamada IoThub-status, que contém o status do método fornecido pelo usuário.

  • O corpo da mensagem do AMQP que contém a resposta do método como JSON.

Material de referência adicional

Outros tópicos de referência no Guia do desenvolvedor do Hub IoT incluem:

Próximas etapas

Agora que você aprendeu a usar métodos diretos, pode ser interessante ler o seguinte artigo do Guia do Desenvolvedor do Hub IoT:

Se você quiser experimentar alguns dos conceitos descritos neste artigo, talvez se interesse pelo seguinte tutorial de Hub IoT: