Compreender e invocar métodos diretos a partir do Hub IoT

  • Artigo

Os métodos diretos do Hub IoT permitem que você invoque remotamente chamadas em dispositivos a partir da nuvem. Os métodos diretos seguem um padrão de solicitação-resposta e destinam-se a comunicações que exigem confirmação imediata de seu resultado. Por exemplo, controle interativo de um dispositivo, como ligar um ventilador. Essa funcionalidade é útil para cenários em que o curso da ação imediata é diferente, dependendo se o dispositivo foi capaz de responder.

Nota

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

Cada método de dispositivo tem como alvo um único dispositivo. Se você quiser invocar métodos diretos em vários dispositivos ou agendar métodos para dispositivos desconectados, consulte Agendar trabalhos em vários dispositivos.

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

Consulte as diretrizes de comunicação entre a nuvem e o dispositivo em caso de dúvida entre o uso das propriedades desejadas, os métodos diretos ou as mensagens da nuvem para o dispositivo.

Ciclo de vida do método

Os métodos diretos são implementados no dispositivo e podem exigir zero ou mais entradas na carga útil do método para instanciar corretamente. Você invoca um método direto por meio de um URI voltado para o serviço ({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 por meio de links AMQP (as propriedades e IoThub-status do IoThub-methodname aplicativo).

Nota

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

Os métodos diretos são síncronos e são bem-sucedidos ou falham após o período de 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 aja se e somente se o dispositivo estiver online e recebendo comandos. Por exemplo, acender uma luz de um telefone. Nesses cenários, você deseja ver um sucesso ou falha imediata para que o serviço de nuvem possa agir sobre o resultado o mais rápido possível. O dispositivo pode retornar algum corpo de mensagem como resultado do método, mas não é necessário. Não há garantia de ordenação ou qualquer simultaneidade semântica em chamadas de método.

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

A carga útil para solicitações e respostas de 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 back-end, use a API REST do método Invoke device ou seu equivalente em um dos SDKs de serviço do Hub IoT.

Invocação do método

As invocações diretas de método em um dispositivo são chamadas HTTPS compostas pelos seguintes itens:

  • O URI de solicitação específico para o dispositivo junto com a versão da API:

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

  • O 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 a conclusão de uma execução direta do método em um dispositivo. Defina esse tempo limite para ser pelo menos tão longo quanto o 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 são responseTimeoutInSeconds de 5 e 300 segundos, respectivamente.

O valor fornecido como connectTimeoutInSeconds na solicitação é a quantidade de tempo após a 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, o que significa que os dispositivos já devem estar online após a invocação de um método direto. O valor máximo para connectTimeoutInSeconds é de 300 segundos.

Exemplo

Este exemplo inicia uma solicitação para invocar um método direto em um dispositivo IoT registrado em um hub IoT do Azure.

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

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

Em seguida, substitua o cabeçalho Authorization pelo SharedAccessSignature recém-gerado e, em seguida, modifique os iothubNameparâmetros , deviceIdmethodName e para payload 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 direct especificado. As solicitações bem-sucedidas retornam um código de status HTTP 200.

Nota

O exemplo acima demonstra invocar um método direto em um dispositivo. Se você quiser invocar um método direto em um Módulo IoT Edge, modifique a solicitação de url para incluir /modules/<moduleName> conforme mostrado abaixo:

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

Response

O aplicativo back-end recebe uma resposta composta pelos seguintes itens:

  • Código de status HTTP:

    • 200 indica a execução bem-sucedida do método direto;
    • 404 indica que o ID do dispositivo é inválido ou que o dispositivo não estava online após a invocação de um método direto e para connectTimeoutInSeconds depois disso (use a mensagem de erro acompanhada para entender a causa raiz);
    • 504 indica o tempo limite do gateway causado pelo dispositivo não responder a uma chamada de método direta dentro do 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" : {...}
}

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

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

A invocação de métodos diretos em um módulo é suportada pela API REST do método Invoke module ou seu equivalente em um dos SDKs de serviço do Hub IoT.

O moduleId é passado junto com o deviceId URI da solicitação ao usar a API REST ou como um 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 métodos diretos invocados no dispositivo.

Manipular um método direto em um dispositivo

Em um dispositivo IoT, métodos diretos podem ser recebidos por MQTT, AMQP ou qualquer um desses protocolos por WebSockets. Os SDKs de dispositivo do Hub IoT ajudam você a receber e responder a métodos diretos em dispositivos sem ter que 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, consulte Suporte ao protocolo MQTT.

Invocação do método

Os dispositivos recebem solicitações diretas de método no 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 conhecido com antecedência, portanto, inscreva-se e filtre $iothub/methods/POST/# as mensagens entregues com base nos nomes de método suportados pelo seu 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.

Response

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

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

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

O corpo é definido pelo dispositivo e pode ser 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, consulte Suporte ao protocolo AMQP.

Invocação do 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 AMQP chega no link de recebimento que representa a solicitação de método. Contém as seguintes secções:

  • A propriedade 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 AMQP que contém a carga útil do método como JSON.

Response

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 ID de correlação, que contém a ID de 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 AMQP que contém a resposta do método como JSON.

Próximos passos

Agora que você aprendeu a usar métodos diretos, pode estar interessado no seguinte artigo do guia do desenvolvedor do Hub IoT: