IoTHubDeviceClient Classe
Um cliente de dispositivo assíncrono que se liga a uma instância Hub IoT do Azure.
Inicializador de um IoTHubDeviceClient.
Este inicializador não deve ser chamado diretamente. Em vez disso, utilize um dos classmethods ">>create_from_<<" para instanciar
- 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 utilizado para ligar ao ponto final do IoTHub.
- http_pipeline
Métodos
| connect |
Liga 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 transmitidas através do parâmetro auth_provider que foi fornecido quando este objeto foi inicializado. |
| create_from_connection_string |
Instanciar o cliente a partir de um dispositivo IoTHub ou de uma cadeia de ligação do módulo. |
| create_from_sastoken |
Instanciar o cliente a partir de uma cadeia de Token de SAS pré-criada |
| create_from_symmetric_key |
Instanciar um cliente através da autenticação de chave simétrica. |
| create_from_x509_certificate |
Instanciar um cliente com a autenticação de certificado X509. |
| disconnect |
Desligue o cliente do Hub IoT do Azure ou da instância do Hub IoT Edge do Azure. Recomenda-se que se certifique de que chama este coroutine quando terminar completamente a instância do cliente. |
| get_storage_info_for_blob |
Envia um pedido POST através de HTTP para um ponto final do IoTHub que irá devolver informações para carregamento através da Conta de Armazenamento do Azure associada ao IoTHub ao qual o seu dispositivo está ligado. |
| get_twin |
Obtém o dispositivo ou módulo duplo a partir do Hub IoT do Azure ou do serviço Hub IoT Edge do Azure. |
| notify_blob_upload_status |
Quando o carregamento estiver concluído, o dispositivo envia um pedido POST para o ponto final Hub IoT com informações sobre o estado de uma tentativa de carregamento para blob. Isto é utilizado por Hub IoT para notificar os clientes de escuta. |
| patch_twin_reported_properties |
Atualize as propriedades comunicadas com o Hub IoT do Azure ou o serviço Hub IoT Edge do Azure. Se o serviço devolver um erro na operação de patch, esta função gerará o erro adequado. |
| receive_message |
Receba uma mensagem que tenha sido enviada a partir do Hub IoT do Azure. Se ainda não existir nenhuma mensagem disponível, aguardará até que um item esteja disponível. Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_message_received para definir um processador |
| receive_method_request |
Receba um pedido de método através do Hub IoT do Azure ou do Hub de IoT Edge do Azure. Se ainda não estiver disponível nenhum pedido de método, aguardará até estar disponível. Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_method_request_received para definir um processador |
| receive_twin_desired_properties_patch |
Receba um patch de propriedade pretendido através do Hub IoT do Azure ou do Hub de IoT Edge do Azure. Se ainda não estiver disponível nenhum pedido de método, aguardará até estar disponível. Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_twin_desired_properties_patch_received para definir um processador |
| send_message |
Envia uma mensagem para o ponto final de eventos predefinido no Hub IoT do Azure ou na instância do Hub IoT Edge do Azure. Se a ligação ao serviço não tiver sido aberta anteriormente por uma chamada para ligar, esta função abrirá a ligação antes de enviar o evento. |
| send_method_response |
Envie uma resposta a um pedido de método através do Hub IoT do Azure ou do Hub IoT Edge do Azure. Se a ligação ao serviço não tiver sido aberta anteriormente por uma chamada para ligar, esta função abrirá a ligação antes de enviar o evento. |
| shutdown |
Encerre o cliente para uma saída correta. Assim que este método for chamado, todas as tentativas de outras chamadas de cliente resultarão num ClientError a ser gerado |
| update_sastoken |
Atualize o Token de SAS do cliente utilizado para autenticação e, em seguida, reautorize a ligação. Esta API só pode ser utilizada se o cliente tiver sido criado inicialmente com um Token de SAS. |
connect
Liga 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 transmitidas através do parâmetro auth_provider que foi fornecido quando este objeto foi inicializado.
async connect()Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
create_from_connection_string
Instanciar o cliente a partir de um dispositivo IoTHub ou de uma cadeia de ligação do módulo.
create_from_connection_string(connection_string, **kwargs)Parâmetros
- server_verification_cert
- str
Opção de Configuração. A cadeia de certificados fidedigna. Necessário ao utilizar a ligação a um ponto final que tenha uma raiz de confiança não padrão, como um gateway de protocolo.
- websockets
- bool
Opção de Configuração. A predefinição é Falso. Defina como verdadeiro se utilizar MQTT através de websockets.
Opção de Configuração. Conjunto(s) de cifras para TLS/SSL, como uma cadeia em "Formato de lista de cifras OpenSSL" ou como uma lista de cadeias de conjunto de cifras.
- product_info
- str
Opção de Configuração. A predefinição é a cadeia vazia. A cadeia contém informações arbitrárias do produto que são anexadas à cadeia de agente do utilizador.
- sastoken_ttl
- int
O tempo de vida (em segundos) do SasToken criado utilizado para autenticação. A predefinição é 3600 segundos (1 hora).
- keep_alive
- int
Período máximo em segundos entre comunicações com o mediador. Se não estiverem a ser trocadas outras mensagens, esta ação controla a taxa a que o cliente enviará mensagens ping para o mediador. Se não for fornecido, será utilizado o valor predefinido de 60 segundos.
- auto_connect
- bool
Ligue automaticamente o cliente ao IoTHub quando é invocado um método que requer que seja estabelecida uma ligação. (Predefinição: Verdadeiro)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma ligação perdida (Predefinição: 10)
- ensure_desired_properties
- bool
Confirme que o patch de propriedades pretendidas mais recente foi recebido após ligações novamente (Predefinição:Verdadeiro)
Devoluções
Uma instância de um cliente IoTHub que utiliza uma cadeia de ligação para autenticação.
Exceções
create_from_sastoken
Instanciar o cliente a partir de uma cadeia de Token de SAS pré-criada
create_from_sastoken(sastoken, **kwargs)Parâmetros
- server_verification_cert
- str
Opção de Configuração. A cadeia de certificados fidedigna. Necessário ao utilizar a ligação a um ponto final 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 anfitrião do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de Configuração. A predefinição é Falso. Defina como verdadeiro se utilizar MQTT através de websockets.
Opção de Configuração. Conjunto(s) de cifras para TLS/SSL, como uma cadeia em "Formato de lista de cifras OpenSSL" ou como uma lista de cadeias de conjunto de cifras.
- product_info
- str
Opção de Configuração. A predefinição é a cadeia vazia. A cadeia contém informações arbitrárias do produto que são anexadas à cadeia de agente do utilizador.
- keep_alive
- int
Período máximo em segundos entre comunicações com o mediador. Se não estiverem a ser trocadas outras mensagens, esta ação controla a taxa a que o cliente enviará mensagens ping para o mediador. Se não for fornecido, será utilizado o valor predefinido de 60 segundos.
- auto_connect
- bool
Ligue automaticamente o cliente ao IoTHub quando é invocado um método que requer que seja estabelecida uma ligação. (Predefinição: Verdadeiro)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma ligação perdida (Predefinição: 10)
- ensure_desired_properties
- bool
Confirme que o patch de propriedades pretendidas mais recente foi recebido após ligações novamente (Predefinição:Verdadeiro)
Exceções
create_from_symmetric_key
Instanciar um cliente através da 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
Anfitrião a executar o IotHub. Pode ser encontrado no portal do Azure no separador Descrição geral como o nome do anfitrião da cadeia.
- device_id
O ID do dispositivo
- server_verification_cert
- str
Opção de Configuração. A cadeia de certificados fidedigna. Necessário ao utilizar a ligação a um ponto final 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 anfitrião do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de Configuração. A predefinição é Falso. Defina como verdadeiro se utilizar MQTT através de websockets.
Opção de Configuração. Conjunto(s) de cifras para TLS/SSL, como uma cadeia em "Formato de lista de cifras OpenSSL" ou como uma lista de cadeias de conjunto de cifras.
- product_info
- str
Opção de Configuração. A predefinição é a cadeia vazia. A cadeia contém informações arbitrárias do produto que são anexadas à cadeia de agente do utilizador.
- sastoken_ttl
- int
O tempo de vida (em segundos) do SasToken criado utilizado para autenticação. A predefinição é 3600 segundos (1 hora)
- keep_alive
- int
Período máximo em segundos entre comunicações com o mediador. Se não estiverem a ser trocadas outras mensagens, esta ação controla a taxa a que o cliente enviará mensagens ping para o mediador. Se não for fornecido, será utilizado o valor predefinido de 60 segundos.
- auto_connect
- bool
Ligue automaticamente o cliente ao IoTHub quando é invocado um método que requer que seja estabelecida uma ligação. (Predefinição: Verdadeiro)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma ligação perdida (Predefinição: 10)
- ensure_desired_properties
- bool
Confirme que o patch de propriedades pretendidas mais recente foi recebido após ligações novamente (Predefinição:Verdadeiro)
Devoluções
Uma instância de um cliente do IoTHub que utiliza uma chave simétrica para autenticação.
Exceções
create_from_x509_certificate
Instanciar um cliente com a autenticação de certificado X509.
create_from_x509_certificate(x509, hostname, device_id, **kwargs)Parâmetros
- hostname
- str
Anfitrião a executar o IotHub. Pode ser encontrado no portal do Azure no separador Descrição geral como o nome do anfitrião da cadeia.
- x509
- X509
O objeto de certificado x509 completo. Para utilizar o certificado, o objeto de inscrição tem de conter o certificado de raiz (o certificado de raiz ou um dos certificados de AC intermédios). Se o certificado for proveniente de um ficheiro CER, tem de ser codificado em base64.
- server_verification_cert
- str
Opção de Configuração. A cadeia de certificados fidedigna. Necessário ao utilizar a ligação a um ponto final 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 anfitrião do gateway para o dispositivo de gateway.
- websockets
- bool
Opção de Configuração. A predefinição é Falso. Defina como verdadeiro se utilizar MQTT através de websockets.
Opção de Configuração. Conjunto(s) de cifras para TLS/SSL, como uma cadeia em "Formato de lista de cifras OpenSSL" ou como uma lista de cadeias de conjunto de cifras.
- product_info
- str
Opção de Configuração. A predefinição é a cadeia vazia. A cadeia contém informações arbitrárias do produto que são anexadas à cadeia de agente do utilizador.
- keep_alive
- int
Período máximo em segundos entre comunicações com o mediador. Se não estiverem a ser trocadas outras mensagens, esta ação controla a taxa a que o cliente enviará mensagens ping para o mediador. Se não for fornecido, será utilizado o valor predefinido de 60 segundos.
- auto_connect
- bool
Ligue automaticamente o cliente ao IoTHub quando é invocado um método que requer que seja estabelecida uma ligação. (Predefinição: Verdadeiro)
- connection_retry_interval
- int
Intervalo, em segundos, entre tentativas de restabelecer uma ligação perdida (Predefinição: 10)
- ensure_desired_properties
- bool
Confirme que o patch de propriedades pretendidas mais recente foi recebido após ligações novamente (Predefinição:Verdadeiro)
Devoluções
Uma instância de um cliente IoTHub que utiliza um certificado X509 para autenticação.
Exceções
disconnect
Desligue o cliente do Hub IoT do Azure ou da instância do Hub IoT Edge do Azure.
Recomenda-se que se certifique de que chama este coroutine quando terminar completamente a instância do cliente.
async disconnect()Exceções
se ocorrer uma falha inesperada durante a execução.
get_storage_info_for_blob
Envia um pedido POST através de HTTP para um ponto final do IoTHub que irá devolver informações para carregamento através da Conta de Armazenamento do Azure associada ao IoTHub ao qual o seu dispositivo está ligado.
async get_storage_info_for_blob(blob_name)Parâmetros
- blob_name
- str
O nome no formato de cadeia do blob que será carregado com a API de armazenamento. Este nome será utilizado para gerar as credenciais adequadas para o Armazenamento e tem de corresponder ao que será utilizado com o SDK de Armazenamento do Azure para executar o carregamento de blobs.
Devoluções
Um objeto semelhante a JSON (dicionário) de Hub IoT que irá conter informações relevantes, incluindo: correlationId, hostName, containerName, blobName, sasToken.
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
get_twin
Obtém o dispositivo ou módulo duplo a partir do Hub IoT do Azure ou do serviço Hub IoT Edge do Azure.
async get_twin()Devoluções
Completo Duplo como um ditado JSON
Tipo de retorno
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a tentativa de ligação exceder o limite de tempo
se o cliente não estiver ligado (e não existir ligação automática ativada)
se ocorrer uma falha inesperada durante a execução.
notify_blob_upload_status
Quando o carregamento estiver concluído, o dispositivo envia um pedido POST para o ponto final Hub IoT com informações sobre o estado de uma tentativa de carregamento para blob. Isto é utilizado por Hub IoT para notificar os clientes de escuta.
async notify_blob_upload_status(correlation_id, is_success, status_code, status_description)Parâmetros
- status_code
- int
Um código de estado numérico que corresponde ao estado do carregamento do ficheiro para o armazenamento.
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
patch_twin_reported_properties
Atualize as propriedades comunicadas com o Hub IoT do Azure ou o serviço Hub IoT Edge do Azure.
Se o serviço devolver um erro na operação de patch, esta função gerará o erro adequado.
async patch_twin_reported_properties(reported_properties_patch)Parâmetros
- reported_properties_patch
- dict
Patch propriedades reportadas de duplo como um ditado JSON
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a tentativa de ligação exceder o limite de tempo
se o cliente não estiver ligado (e não existir ligação automática ativada)
se ocorrer uma falha inesperada durante a execução.
receive_message
Receba uma mensagem que tenha sido enviada a partir do Hub IoT do Azure.
Se ainda não existir nenhuma mensagem disponível, aguardará até que um item esteja disponível.
Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_message_received para definir um processador
receive_message()Devoluções
Mensagem enviada a partir do Hub IoT do Azure.
Tipo de retorno
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
receive_method_request
Receba um pedido de método através do Hub IoT do Azure ou do Hub de IoT Edge do Azure.
Se ainda não estiver disponível nenhum pedido de método, aguardará até estar disponível.
Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_method_request_received para definir um processador
receive_method_request(method_name=None)Parâmetros
- method_name
- str
Opcionalmente, forneça o nome do método para o qual receber pedidos. Se este parâmetro não for fornecido, todos os métodos que ainda não estão a ser especificamente visados por uma chamada diferente para receive_method serão recebidos.
Devoluções
Objeto MethodRequest que representa o pedido de método recebido.
Tipo de retorno
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
receive_twin_desired_properties_patch
Receba um patch de propriedade pretendido através do Hub IoT do Azure ou do Hub de IoT Edge do Azure.
Se ainda não estiver disponível nenhum pedido de método, aguardará até estar disponível.
Preterido desde a versão 2.3.0: recomendamos que utilize a propriedade .on_twin_desired_properties_patch_received para definir um processador
receive_twin_desired_properties_patch()Devoluções
Patch propriedades pretendidas de duplo como um ditado JSON
Tipo de retorno
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a ligação exceder o limite de tempo.
se ocorrer uma falha inesperada durante a execução.
send_message
Envia uma mensagem para o ponto final de eventos predefinido no Hub IoT do Azure ou na instância do Hub IoT Edge do Azure.
Se a ligação ao serviço não tiver sido aberta anteriormente por uma chamada para ligar, esta função abrirá a ligação antes de enviar o evento.
async send_message(message)Parâmetros
- message
- Message
A mensagem real a enviar. Tudo o que for transmitido que não seja uma instância da classe Mensagem será convertido no objeto Mensagem.
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a tentativa de ligação exceder o limite de tempo
se o cliente não estiver ligado (e não existir ligação automática ativada)
se ocorrer uma falha inesperada durante a execução.
send_method_response
Envie uma resposta a um pedido de método através do Hub IoT do Azure ou do Hub IoT Edge do Azure.
Se a ligação ao serviço não tiver sido aberta anteriormente por uma chamada para ligar, esta função abrirá a ligação antes de enviar o evento.
async send_method_response(method_response)Parâmetros
Exceções
se as credenciais forem inválidas e não for possível estabelecer uma ligação.
se o estabelecimento de uma ligação resultar em falhas.
se a ligação for perdida durante a execução.
se a tentativa de ligação exceder o limite de tempo
se o cliente não estiver ligado (e não existir ligação automática ativada)
se ocorrer uma falha inesperada durante a execução.
shutdown
Encerre o cliente para uma saída correta.
Assim que este método for chamado, todas as tentativas de outras chamadas de cliente resultarão num ClientError a ser gerado
async shutdown()Exceções
se ocorrer uma falha inesperada durante a execução.
update_sastoken
Atualize o Token de SAS do cliente utilizado para autenticação e, em seguida, reautorize a ligação.
Esta API só pode ser utilizada se o cliente tiver sido criado inicialmente com um Token de SAS.
async update_sastoken(sastoken)Parâmetros
Exceções
se as credenciais forem inválidas e não for possível restabelecer uma ligação.
se um restaumento da ligação resultar em falha.
se a ligação for perdida durante a execução.
se a tentativa de reautorização exceder o limite de tempo.
se o cliente não tiver sido criado inicialmente com um token de SAS.
se ocorrer uma falha inesperada durante a execução.
Atributos
connected
Propriedade só de leitura para indicar se o transporte está ligado ou não.
on_background_exception
A função de processador ou coroutine será chamada quando ocorrer uma exceção em segundo plano.
A definição de função ou coroutina deve ter um argumento posicional (o objeto de exceção)
on_connection_state_change
A função de processador ou coroutine que será chamada quando o estado da ligação for alterado.
A definição de função ou coroutina não deve ter argumentos posicionais.
on_message_received
A função de processador ou coroutine que será chamada quando uma mensagem é recebida.
A definição de função ou coroutina deve ter um argumento posicional (o Message objeto)
on_method_request_received
A função de processador ou coroutine que será chamada quando um pedido de método for recebido.
Lembre-se de reconhecer o pedido de método na sua função ou corouteno através da utilização do método .send_method_response() do cliente.
A definição de função ou coroutina deve ter um argumento posicional (o MethodRequest objeto)
on_new_sastoken_required
A função de processador ou coroutine que será chamada quando o cliente exigir um novo token de SAS. Isto ocorrerá aproximadamente 2 minutos antes de o Token de SAS expirar. Nas plataformas Windows, se o tempo de vida for superior a aproximadamente 49 dias, será necessário um novo token após esses 49 dias, independentemente da duração da SAS.
Tenha em atenção que este processador só é necessário ao utilizar um cliente criado através do método .create_from_sastoken().
O novo token pode ser fornecido na sua função ou corouteno através da utilização do método .update_sastoken() do cliente.
A definição de função ou coroutina não deve ter argumentos posicionais.
on_twin_desired_properties_patch_received
A função de processador ou coroutine que será chamada quando for recebido um patch de propriedades pretendidas de duplos.
A definição de função ou coroutina deve ter um argumento posicional (o patch duplo sob a forma de um objeto de dicionário JSON)
Azure SDK for Python
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários