Partilhar via

Compreender e invocar métodos diretos do Hub IoT

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.

Observação

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 e o tamanho certos 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 orientações 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 IoThub-methodname e IoThub-status do aplicativo).

Observação

Quando se invoca um método direto num dispositivo, os nomes e valores de propriedade só podem conter caracteres alfanuméricos imprimíveis US-ASCII, exceto os do 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 nem qualquer semântica de concorrência nas 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 uma aplicação back-end

Para invocar um método direto de uma aplicação back-end, use a API REST 'Devices - Invoke Method' ou o seu equivalente em um dos SDKs de serviços do IoT Hub.

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 do 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 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 um valor de 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 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 predefinido é 0, o que significa que os dispositivos já têm de 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 Assinatura de Acesso Partilhado.

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 , deviceId, methodName, e para payload corresponder à sua implementação no comando de exemplo curl a seguir.

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.

Observação

O exemplo anterior 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 no exemplo a seguir:

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

Resposta

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 durante a invocação de um método direto e para connectTimeoutInSeconds posteriormente (use a mensagem de erro fornecida para entender a causa raiz);
    • 504 indica um timeout do gateway quando o dispositivo não responde a uma chamada de método direta no 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 com o formato seguinte:

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

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

Invocação de métodos para os módulos do IoT Edge

Para invocar um método direto em um módulo, use a API REST Modules - Invoke Method ou seu equivalente em um dos SDKs de serviço do Hub IoT.

O moduleId é passado junto com o deviceId no URI de 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.

Gerir um método direto num 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 Comunicar-se com um hub IoT usando o 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, não pode ser conhecido antecipadamente porque o Hub IoT request id o gera, portanto, inscreva-se em $iothub/methods/POST/# e, em seguida, filtre as mensagens entregues com base nos nomes de método suportados pelo seu dispositivo. (Você usa o conteúdo gerado 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 respostas para $iothub/methods/res/{status}/?$rid={request id}, onde:

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

  • A propriedade $rid é 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 dispositivo ajusta o corpo e pode ter qualquer estado.

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 Comunicar-se com seu hub IoT usando o 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 em formato 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 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 contendo a resposta do método no formato JSON.

Próximos passos

Agora que você sabe como usar métodos diretos, pode estar interessado nos seguintes artigos do guia do desenvolvedor do Hub IoT: