IoTHubDeviceClient Classe
Um cliente de dispositivo assíncrono que se conecta a uma instância Hub IoT do Azure.
Inicializador para um IoTHubDeviceClient.
Esse inicializador não deve ser chamado diretamente. Em vez disso, use um dos métodos de classe '>>create_from_<<' para criar uma instância
- Herança
-
azure.iot.device.iothub.aio.async_clients.GenericIoTHubClientIoTHubDeviceClientazure.iot.device.iothub.abstract_clients.AbstractIoTHubDeviceClientIoTHubDeviceClient
Construtor
IoTHubDeviceClient(mqtt_pipeline, http_pipeline)Parâmetros
- mqtt_pipeline
- <xref:azure.iot.device.iothub.pipeline.MQTTPipeline>
O pipeline usado para se conectar ao ponto de extremidade do IoTHub.
- http_pipeline
Métodos
| connect |
Conecta o cliente a um Hub IoT do Azure ou a uma instância do Hub IoT Edge do Azure. O destino é escolhido com base nas credenciais passadas por meio do parâmetro auth_provider que foi fornecido quando esse objeto foi inicializado. |
| create_from_connection_string |
Instancie o cliente de um dispositivo IoTHub ou uma cadeia de conexão de módulo. |
| create_from_sastoken |
Criar uma instância do cliente de uma cadeia de caracteres de token SAS pré-criada |
| create_from_symmetric_key |
Instancie um cliente usando a autenticação de chave simétrica. |
| create_from_x509_certificate |
Instancie um cliente usando a autenticação de certificado X509. |
| disconnect |
Desconecte o cliente do Hub IoT do Azure ou da instância do Hub IoT Edge do Azure. É recomendável que você certifique-se de chamar essa corrotina quando terminar completamente com a instância do cliente. |
| get_storage_info_for_blob |
Envia uma solicitação POST por HTTP para um ponto de extremidade do IoTHub que retornará informações para carregamento por meio da Conta de Armazenamento do Azure vinculada ao IoTHub ao qual seu dispositivo está conectado. |
| get_twin |
Obtém o dispositivo ou módulo gêmeo do Hub IoT do Azure ou do serviço hub IoT Edge do Azure. |
| notify_blob_upload_status |
Quando o carregamento é concluído, o dispositivo envia uma solicitação POST para o ponto de extremidade Hub IoT com informações sobre o status de uma tentativa de upload para blob. Isso é usado por Hub IoT para notificar os clientes ouvintes. |
| patch_twin_reported_properties |
Atualize as propriedades relatadas com o serviço Hub IoT do Azure ou Hub IoT Edge do Azure. Se o serviço retornar um erro na operação de patch, essa função gerará o erro apropriado. |
| receive_message |
Receba uma mensagem que foi enviada do Hub IoT do Azure. Se nenhuma mensagem ainda estiver disponível, aguardará até que um item esteja disponível. Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_message_received para definir um manipulador |
| receive_method_request |
Receba uma solicitação de método por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure. Se nenhuma solicitação de método ainda estiver disponível, aguardará até que ela esteja disponível. Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_method_request_received para definir um manipulador |
| receive_twin_desired_properties_patch |
Receba um patch de propriedade desejado por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure. Se nenhuma solicitação de método ainda estiver disponível, aguardará até que ela esteja disponível. Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_twin_desired_properties_patch_received para definir um manipulador |
| send_message |
Envia uma mensagem para o ponto de extremidade de eventos padrão no Hub IoT do Azure ou na instância do Hub IoT Edge do Azure. Se a conexão com o serviço não tiver sido aberta anteriormente por uma chamada para se conectar, essa função abrirá a conexão antes de enviar o evento. |
| send_method_response |
Envie uma resposta a uma solicitação de método por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure. Se a conexão com o serviço não tiver sido aberta anteriormente por uma chamada para se conectar, essa função abrirá a conexão antes de enviar o evento. |
| shutdown |
Desligue o cliente para uma saída normal. Depois que esse método for chamado, todas as tentativas em outras chamadas de cliente resultarão na geração de um ClientError |
| update_sastoken |
Atualize o Token SAS do cliente usado para autenticação e, em seguida, reautorize a conexão. Essa API só poderá ser usada se o cliente tiver sido criado inicialmente com um Token SAS. |
connect
Conecta o cliente a um Hub IoT do Azure ou a uma instância do Hub IoT Edge do Azure.
O destino é escolhido com base nas credenciais passadas por meio do parâmetro auth_provider que foi fornecido quando esse objeto foi inicializado.
async connect()Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
create_from_connection_string
Instancie o cliente de um dispositivo IoTHub ou uma cadeia de conexão de módulo.
create_from_connection_string(connection_string, **kwargs)Parâmetros
- connection_string
- str
A cadeia de conexão para o IoTHub ao qual você deseja se conectar.
- server_verification_cert
- str
Opção de configuração. A cadeia de certificados confiável. Necessário ao usar a conexão a um ponto de extremidade que tenha uma raiz de confiança não padrão, como um gateway de protocolo.
- websockets
- bool
Opção de configuração. O padrão é Falso. Defina como true se estiver usando MQTT em websockets.
Opção de configuração. Pacotes de criptografia para TLS/SSL, como uma cadeia de caracteres em "Formato de lista de criptografia OpenSSL" ou como uma lista de cadeias de caracteres de conjunto de criptografia.
- product_info
- str
Opção de configuração. O padrão é uma cadeia de caracteres vazia. A cadeia de caracteres contém informações arbitrárias do produto que são acrescentadas à cadeia de caracteres do agente do usuário.
- sastoken_ttl
- int
O tempo de vida (em segundos) para o SasToken criado usado para autenticação. O padrão é 3600 segundos (1 hora).
- keep_alive
- int
Período máximo em segundos entre as comunicações com o agente. Se nenhuma outra mensagem estiver sendo trocada, isso controlará a taxa na qual o cliente enviará mensagens de ping ao agente. Se não for fornecido o valor padrão de 60 segundos, será usado.
- auto_connect
- bool
Conecte automaticamente o cliente ao IoTHub quando um método é invocado, o que requer uma conexão a ser estabelecida. (Padrão: True)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma conexão descartada (Padrão: 10)
- ensure_desired_properties
- bool
Verifique se o patch de propriedades desejadas mais recente foi recebido em novas conexões (Default:True)
Retornos
Uma instância de um cliente IoTHub que usa uma cadeia de conexão para autenticação.
Exceções
create_from_sastoken
Criar uma instância do cliente de uma cadeia de caracteres de token SAS pré-criada
create_from_sastoken(sastoken, **kwargs)Parâmetros
- server_verification_cert
- str
Opção de configuração. A cadeia de certificados confiável. Necessário ao usar a conexão a um ponto de extremidade que tenha uma raiz de confiança não padrão, como um gateway de protocolo.
- gateway_hostname
- str
Opção de configuração. O nome do host do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de configuração. O padrão é Falso. Defina como true se estiver usando MQTT em websockets.
Opção de configuração. Pacotes de criptografia para TLS/SSL, como uma cadeia de caracteres em "Formato de lista de criptografia OpenSSL" ou como uma lista de cadeias de caracteres de conjunto de criptografia.
- product_info
- str
Opção de configuração. O padrão é uma cadeia de caracteres vazia. A cadeia de caracteres contém informações arbitrárias do produto que são acrescentadas à cadeia de caracteres do agente do usuário.
- keep_alive
- int
Período máximo em segundos entre as comunicações com o agente. Se nenhuma outra mensagem estiver sendo trocada, isso controlará a taxa na qual o cliente enviará mensagens de ping ao agente. Se não for fornecido o valor padrão de 60 segundos, será usado.
- auto_connect
- bool
Conecte automaticamente o cliente ao IoTHub quando um método é invocado, o que requer uma conexão a ser estabelecida. (Padrão: True)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma conexão descartada (Padrão: 10)
- ensure_desired_properties
- bool
Verifique se o patch de propriedades desejadas mais recente foi recebido em novas conexões (Default:True)
Exceções
create_from_symmetric_key
Instancie um cliente usando a autenticação de chave simétrica.
create_from_symmetric_key(symmetric_key, hostname, device_id, **kwargs)Parâmetros
- symmetric_key
A chave simétrica.
- hostname
- str
Host executando o IotHub. Pode ser encontrado no portal do Azure na guia Visão geral como o nome do host da cadeia de caracteres.
- device_id
A ID do dispositivo
- server_verification_cert
- str
Opção de configuração. A cadeia de certificados confiável. Necessário ao usar a conexão a um ponto de extremidade que tenha uma raiz de confiança não padrão, como um gateway de protocolo.
- gateway_hostname
- str
Opção de configuração. O nome do host do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de configuração. O padrão é Falso. Defina como true se estiver usando MQTT em websockets.
Opção de configuração. Pacotes de criptografia para TLS/SSL, como uma cadeia de caracteres em "Formato de lista de criptografia OpenSSL" ou como uma lista de cadeias de caracteres do conjunto de criptografias.
- product_info
- str
Opção de configuração. O padrão é uma cadeia de caracteres vazia. A cadeia de caracteres contém informações arbitrárias do produto que são acrescentadas à cadeia de caracteres do agente do usuário.
- sastoken_ttl
- int
O tempo de vida (em segundos) para o SasToken criado usado para autenticação. O padrão é 3600 segundos (1 hora)
- keep_alive
- int
Período máximo em segundos entre as comunicações com o agente. Se nenhuma outra mensagem estiver sendo trocada, isso controlará a taxa na qual o cliente enviará mensagens de ping ao agente. Se não for fornecido, o valor padrão de 60 segundos será usado.
- auto_connect
- bool
Conecte automaticamente o cliente ao IoTHub quando um método é invocado, o que exige que uma conexão seja estabelecida. (Padrão: True)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma conexão descartada (Padrão: 10)
- ensure_desired_properties
- bool
Verifique se o patch de propriedades desejadas mais recente foi recebido após novas conexões (Default:True)
Retornos
Uma instância de um cliente IoTHub que usa uma chave simétrica para autenticação.
Exceções
create_from_x509_certificate
Instancie um cliente usando a autenticação de certificado X509.
create_from_x509_certificate(x509, hostname, device_id, **kwargs)Parâmetros
- hostname
- str
Host executando o IotHub. Pode ser encontrado no portal do Azure na guia Visão geral como o nome do host da cadeia de caracteres.
- x509
- X509
O objeto de certificado x509 completo. Para usar o certificado, o objeto de registro precisa conter certificado (o certificado raiz ou um dos certificados de AUTORIDADE de certificação intermediários). Se o certificado vier de um arquivo CER, ele precisará ser codificado em base64.
- server_verification_cert
- str
Opção de configuração. A cadeia de certificados confiáveis. Necessário ao usar a conexão com um ponto de extremidade que tem uma raiz de confiança não padrão, como um gateway de protocolo.
- gateway_hostname
- str
Opção de configuração. O nome do host do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de configuração. O padrão é Falso. Defina como true se estiver usando MQTT em websockets.
Opção de configuração. Pacotes de criptografia para TLS/SSL, como uma cadeia de caracteres em "Formato de lista de criptografia OpenSSL" ou como uma lista de cadeias de caracteres do conjunto de criptografias.
- product_info
- str
Opção de configuração. O padrão é uma cadeia de caracteres vazia. A cadeia de caracteres contém informações arbitrárias do produto que são acrescentadas à cadeia de caracteres do agente do usuário.
- keep_alive
- int
Período máximo em segundos entre as comunicações com o agente. Se nenhuma outra mensagem estiver sendo trocada, isso controlará a taxa na qual o cliente enviará mensagens de ping ao agente. Se não for fornecido, o valor padrão de 60 segundos será usado.
- auto_connect
- bool
Conecte automaticamente o cliente ao IoTHub quando um método é invocado, o que exige que uma conexão seja estabelecida. (Padrão: True)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma conexão descartada (Padrão: 10)
- ensure_desired_properties
- bool
Verifique se o patch de propriedades desejadas mais recente foi recebido após novas conexões (Default:True)
Retornos
Uma instância de um cliente IoTHub que usa um certificado X509 para autenticação.
Exceções
disconnect
Desconecte o cliente do Hub IoT do Azure ou da instância do Hub IoT Edge do Azure.
É recomendável que você certifique-se de chamar essa corrotina quando terminar completamente com a instância do cliente.
async disconnect()Exceções
se houver uma falha inesperada durante a execução.
get_storage_info_for_blob
Envia uma solicitação POST por HTTP para um ponto de extremidade do IoTHub que retornará informações para carregamento por meio da Conta de Armazenamento do Azure vinculada ao IoTHub ao qual seu dispositivo está conectado.
async get_storage_info_for_blob(blob_name)Parâmetros
- blob_name
- str
O nome no formato de cadeia de caracteres do blob que será carregado usando a API de armazenamento. Esse nome será usado para gerar as credenciais adequadas para o Armazenamento e precisa corresponder ao que será usado com o SDK do Armazenamento do Azure para executar o upload do blob.
Retornos
Um objeto semelhante a JSON (dicionário) de Hub IoT que conterá informações relevantes, incluindo: correlationId, hostName, containerName, blobName e sasToken.
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
get_twin
Obtém o dispositivo ou módulo gêmeo do Hub IoT do Azure ou do serviço hub IoT Edge do Azure.
async get_twin()Retornos
Concluir gêmeo como um dict JSON
Tipo de retorno
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a tentativa de conexão atingir o tempo limite
se o cliente não estiver conectado (e não houver nenhuma conexão automática habilitada)
se houver uma falha inesperada durante a execução.
notify_blob_upload_status
Quando o carregamento é concluído, o dispositivo envia uma solicitação POST para o ponto de extremidade Hub IoT com informações sobre o status de uma tentativa de upload para blob. Isso é usado por Hub IoT para notificar os clientes ouvintes.
async notify_blob_upload_status(correlation_id, is_success, status_code, status_description)Parâmetros
- status_code
- int
Um código de status numérico que é o status para o upload do arquivo no armazenamento.
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
patch_twin_reported_properties
Atualize as propriedades relatadas com o serviço Hub IoT do Azure ou Hub IoT Edge do Azure.
Se o serviço retornar um erro na operação de patch, essa função gerará o erro apropriado.
async patch_twin_reported_properties(reported_properties_patch)Parâmetros
- reported_properties_patch
- dict
Patch de Propriedades Relatadas do Gêmeo como um dict JSON
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a tentativa de conexão atingir o tempo limite
se o cliente não estiver conectado (e não houver nenhuma conexão automática habilitada)
se houver uma falha inesperada durante a execução.
receive_message
Receba uma mensagem que foi enviada do Hub IoT do Azure.
Se nenhuma mensagem ainda estiver disponível, aguardará até que um item esteja disponível.
Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_message_received para definir um manipulador
receive_message()Retornos
Mensagem enviada do Hub IoT do Azure.
Tipo de retorno
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
receive_method_request
Receba uma solicitação de método por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure.
Se nenhuma solicitação de método ainda estiver disponível, aguardará até que ela esteja disponível.
Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_method_request_received para definir um manipulador
receive_method_request(method_name=None)Parâmetros
- method_name
- str
Opcionalmente, forneça o nome do método para o qual receber solicitações. Se esse parâmetro não for dado, todos os métodos que ainda não estão sendo especificamente direcionados por uma chamada diferente para receive_method serão recebidos.
Retornos
Objeto MethodRequest que representa a solicitação de método recebida.
Tipo de retorno
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
receive_twin_desired_properties_patch
Receba um patch de propriedade desejado por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure.
Se nenhuma solicitação de método ainda estiver disponível, aguardará até que ela esteja disponível.
Preterido desde a versão 2.3.0: recomendamos que você use a propriedade .on_twin_desired_properties_patch_received para definir um manipulador
receive_twin_desired_properties_patch()Retornos
Patch de Propriedades Desejadas do Gêmeo como um dict JSON
Tipo de retorno
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a conexão atingir o tempo limite.
se houver uma falha inesperada durante a execução.
send_message
Envia uma mensagem para o ponto de extremidade de eventos padrão no Hub IoT do Azure ou na instância do Hub IoT Edge do Azure.
Se a conexão com o serviço não tiver sido aberta anteriormente por uma chamada para se conectar, essa função abrirá a conexão antes de enviar o evento.
async send_message(message)Parâmetros
- message
- Message
A mensagem real a ser enviada. Qualquer coisa passada que não seja uma instância da classe Message será convertida em objeto Message.
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a tentativa de conexão atingir o tempo limite
se o cliente não estiver conectado (e não houver nenhuma conexão automática habilitada)
se houver uma falha inesperada durante a execução.
send_method_response
Envie uma resposta a uma solicitação de método por meio do Hub IoT do Azure ou do Hub IoT Edge do Azure.
Se a conexão com o serviço não tiver sido aberta anteriormente por uma chamada para se conectar, essa função abrirá a conexão antes de enviar o evento.
async send_method_response(method_response)Parâmetros
Exceções
se as credenciais forem inválidas e uma conexão não puder ser estabelecida.
se um estabelecimento de uma conexão resultar em falha.
se a conexão for perdida durante a execução.
se a tentativa de conexão atingir o tempo limite
se o cliente não estiver conectado (e não houver nenhuma conexão automática habilitada)
se houver uma falha inesperada durante a execução.
shutdown
Desligue o cliente para uma saída normal.
Depois que esse método for chamado, todas as tentativas em outras chamadas de cliente resultarão na geração de um ClientError
async shutdown()Exceções
se houver uma falha inesperada durante a execução.
update_sastoken
Atualize o Token SAS do cliente usado para autenticação e, em seguida, reautorize a conexão.
Essa API só poderá ser usada se o cliente tiver sido criado inicialmente com um Token SAS.
async update_sastoken(sastoken)Parâmetros
Exceções
se as credenciais forem inválidas e uma conexão não puder ser restabelecida.
se um restabelecimento da conexão resultar em falha.
se a conexão for perdida durante a execução.
se a tentativa de reautorização atingir o tempo limite.
se o cliente não foi criado inicialmente com um token SAS.
se houver uma falha inesperada durante a execução.
Atributos
connected
Propriedade somente leitura para indicar se o transporte está conectado ou não.
on_background_exception
A função de manipulador ou a corrotina serão chamadas quando ocorrer uma exceção em segundo plano.
A função ou definição de corrotina deve ter um argumento posicional (o objeto de exceção)
on_connection_state_change
A função de manipulador ou a corrotina que será chamada quando o estado da conexão for alterado.
A função ou a definição de corrotina não devem ter argumentos posicionais.
on_message_received
A função de manipulador ou a corrotina que será chamada quando uma mensagem for recebida.
A função ou definição de corrotina deve ter um argumento posicional (o Message objeto)
on_method_request_received
A função de manipulador ou a corrotina que será chamada quando uma solicitação de método for recebida.
Lembre-se de reconhecer a solicitação de método em sua função ou corrotina por meio do uso do método .send_method_response() do cliente.
A função ou definição de corrotina deve ter um argumento posicional (o MethodRequest objeto)
on_new_sastoken_required
A função de manipulador ou a corrotina que será chamada quando o cliente exigir um novo token SAS. Isso acontecerá aproximadamente 2 minutos antes do token SAS expirar. Em plataformas Windows, se o tempo de vida exceder aproximadamente 49 dias, um novo token será necessário após esses 49 dias, independentemente de quanto tempo o tempo de vida da SAS é.
Observe que esse manipulador só é necessário ao usar um cliente criado por meio do método .create_from_sastoken().
O novo token pode ser fornecido em sua função ou corrotina por meio do uso do método .update_sastoken() do cliente.
A função ou a definição de corrotina não devem ter argumentos posicionais.
on_twin_desired_properties_patch_received
A função de manipulador ou a corrotina que será chamada quando um patch de propriedades desejadas de gêmeo for recebido.
A função ou a definição de corrotina devem ter um argumento posicional (o patch gêmeo na forma de um objeto de dicionário JSON)
Azure SDK for Python