Biblioteca de clientes do Azure Azure Digital Twins Core para Python – versão 1.2.0

Artigo
04/05/2023

Esse pacote contém um SDK para a API dos Gêmeos Digitais do Azure para fornecer acesso ao serviço gêmeos digitais do Azure para gerenciar gêmeos, modelos, relacionamentos etc.

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Os Gêmeos Digitais do Azure são uma plataforma de desenvolvedor para soluções de IoT de última geração que permitem criar, executar e gerenciar representações digitais do seu ambiente de negócios, de forma segura e eficiente na nuvem. Com os Gêmeos Digitais do Azure, a criação de representações de estado operacional ao vivo é rápida e econômica, e as representações digitais permanecem atualizadas com dados em tempo real da IoT e de outras fontes de dados. Se você for novo nos Gêmeos Digitais do Azure e quiser saber mais sobre a plataforma, confira a página de documentação oficial dos Gêmeos Digitais do Azure.

Para obter uma introdução sobre como programar no serviço dos Gêmeos Digitais do Azure, visite a página do tutorial de codificação para obter um guia passo a passo fácil. Visite este tutorial para saber como interagir com uma instância do Gêmeo Digital do Azure usando um aplicativo cliente de linha de comando. Por fim, para obter um guia rápido sobre como criar uma solução de Gêmeos Digitais do Azure de ponta a ponta que é controlada por dados dinâmicos do seu ambiente, confira este guia útil.

Os guias mencionados acima podem ajudá-lo a começar a usar os principais elementos dos Gêmeos Digitais do Azure, como a criação de instâncias dos Gêmeos Digitais do Azure, modelos, grafos gêmeos etc. Use este guia de exemplos abaixo para se familiarizar com as várias APIs que ajudam você a programar nos Gêmeos Digitais do Azure.

Como instalar

Instale [azure-digitaltwins-core][pypi_package_keys] e azure-identity com pip:

pip install azure-digitaltwins-core azure-identity

azure-identity é usado para autenticação do Azure Active Directory, conforme demonstrado abaixo.

Como usar

Autenticação, permissão

Para criar um novo cliente de gêmeos digitais, você precisa do ponto de extremidade para uma instância e credenciais do Gêmeo Digital do Azure. Para os exemplos abaixo, as AZURE_URLvariáveis de ambiente , AZURE_TENANT_ID, AZURE_CLIENT_IDe AZURE_CLIENT_SECRET precisam ser definidas. O cliente requer uma instância de TokenCredential ou ServiceClientCredentials. Nestes exemplos, ilustramos como usar uma classe derivada: DefaultAzureCredentials.

Observação: para acessar o plano de dados do serviço gêmeos digitais, a entidade deve receber permissões. Para fazer isso, use o comando da CLI do Azure: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential dá suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Ele tenta usar vários tipos de credencial em uma ordem até encontrar uma credencial em funcionamento.

Código de exemplo

# DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based of the environment it is executing in.
# It attempts to use multiple credential types in an order until it finds a working credential.

# - AZURE_URL: The URL to the ADT in Azure
url = os.getenv("AZURE_URL")

# DefaultAzureCredential expects the following three environment variables:
# - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
# - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
# - AZURE_CLIENT_SECRET: The client secret for the registered application
credential = DefaultAzureCredential()
service_client = DigitalTwinsClient(url, credential)

Principais conceitos

Os Gêmeos Digitais do Azure são um serviço de IoT do Azure que cria modelos abrangentes do ambiente físico. Eles podem criar grafos de inteligência espacial para modelar relações e interações entre pessoas, espaços e dispositivos. Você pode saber mais sobre os Gêmeos Digitais do Azure visitando a Documentação dos Gêmeos Digitais do Azure.

Exemplos

Você pode explorar as APIs de gêmeos digitais (usando a biblioteca de clientes) usando o projeto de exemplos.

O projeto de exemplos demonstra o seguinte:

Instancie o cliente
Criar, obter e desativar modelos
Criar, consultar e excluir um gêmeo digital
Obter e atualizar componentes para um gêmeo digital
Criar, obter e excluir relações entre gêmeos digitais
Criar, obter e excluir rotas de evento para gêmeo digital
Publicar mensagens de telemetria em um componente de gêmeo digital e gêmeo digital

Criar, listar, desativar e excluir modelos

Criar modelos

Vamos criar modelos usando o código abaixo. Você precisa passar uma matriz contendo uma lista de modelos.

temporary_component = {
    "@id": component_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Component1",
    "contents": [
    {
        "@type": "Property",
        "name": "ComponentProp1",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "ComponentTelemetry1",
        "schema": "integer"
    }
    ]
}

temporary_model = {
    "@id": model_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "TempModel",
    "contents": [
    {
        "@type": "Property",
        "name": "Prop1",
        "schema": "string"
    },
    {
        "@type": "Component",
        "name": "Component1",
        "schema": component_id
    },
    {
        "@type": "Telemetry",
        "name": "Telemetry1",
        "schema": "integer"
    }
    ]
}

new_models = [temporary_component, temporary_model]
models = service_client.create_models(new_models)
print('Created Models:')
print(models)

Listar modelos

Usar list_models para recuperar todos os modelos criados

listed_models = service_client.list_models()
for model in listed_models:
    print(model)

Obter modelo

Use get_model com o identificador exclusivo do modelo para obter um modelo específico.

# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)

Modelo de descomissionamento

Para descompromissar um modelo, passe uma ID de modelo para o modelo que você deseja descompromissar.

# Decommission a model
service_client.decommission_model(model_id)

Excluir modelo

Para excluir um modelo, passe uma ID de modelo para o modelo que você deseja excluir.

# Delete a model
service_client.delete_model(model_id)

Criar e excluir gêmeos digitais

Criar gêmeos digitais

Para Criar Gêmeo, você precisará fornecer a ID de um gêmeo digital, como my_twin e o gêmeo digital application/json com base no modelo criado anteriormente. Você pode examinar o aplicativo/json de exemplo aqui.

digital_twin_id = 'digitalTwin-' + str(uuid.uuid4())
temporary_twin = {
    "$metadata": {
        "$model": model_id
    },
    "$dtId": digital_twin_id,
    "Prop1": 42
}

created_twin = service_client.upsert_digital_twin(digital_twin_id, temporary_twin)
print('Created Digital Twin:')
print(created_twin)

Obter um gêmeo digital

Obter um gêmeo digital é extremamente fácil.

get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)

Consultar os gêmeos digitais

Consulte a instância dos Gêmeos Digitais do Azure para gêmeos digitais usando os Gêmeos Digitais do Azure Repositório de Consultas lanaguage. As chamadas de consulta dão suporte para paginação. Aqui está um exemplo de como consultar gêmeos digitais e como iterar sobre os resultados.

Observe que pode haver um atraso entre antes que as alterações em sua instância sejam refletidas em consultas. Para obter mais detalhes sobre limitações de consulta, consulte (/azure/digital-twins/how-to-query-graph#query-limitations)

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

Excluir gêmeos digitais

Exclua um gêmeo digital simplesmente fornecendo a ID de um gêmeo digital, conforme mostrado abaixo.

service_client.delete_digital_twin(digital_twin_id)

Obter e atualizar componentes do gêmeo digital

Atualizar componentes do gêmeo digital

Para atualizar um componente ou em outras palavras para substituir, remover e/ou adicionar uma propriedade de componente ou subpropriedade no Gêmeo Digital, você precisaria da ID de um gêmeo digital, nome do componente e operações application/json-patch+json a serem executadas no componente do gêmeo digital especificado. Aqui está o código de exemplo sobre como fazer isso.

component_name = "Component1"
patch = [
    {
        "op": "replace",
        "path": "/ComponentProp1",
        "value": "value2"
    }
]
service_client.update_component(digital_twin_id, component_name, patch)

Obter componentes do gêmeo digital

Obtenha um componente fornecendo o nome de um componente e a ID do gêmeo digital ao qual ele pertence.

get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)

Criar e listar relações de gêmeo digital

Criar relações de gêmeo digital

upsert_relationship cria uma relação em um gêmeo digital fornecido com a ID de um gêmeo digital, nome de relação como "contains", Id de uma relação como "FloorContainsRoom" e uma relação de aplicativo/json a ser criada. Deve conter a propriedade com a chave "$targetId" para especificar o destino da relação. Conteúdos de exemplo para relações podem ser encontrados aqui.

hospital_relationships = [
    {
        "$relationshipId": "BuildingHasFloor",
        "$sourceId": building_twin_id,
        "$relationshipName": "has",
        "$targetId": floor_twin_id,
        "isAccessRestricted": False
    },
    {
        "$relationshipId": "BuildingIsEquippedWithHVAC",
        "$sourceId": building_twin_id,
        "$relationshipName": "isEquippedWith",
        "$targetId": hvac_twin_id
    },
    {
        "$relationshipId": "HVACCoolsFloor",
        "$sourceId": hvac_twin_id,
        "$relationshipName": "controlsTemperature",
        "$targetId": floor_twin_id
    },
    {
        "$relationshipId": "FloorContainsRoom",
        "$sourceId": floor_twin_id,
        "$relationshipName": "contains",
        "$targetId": room_twin_id
    }
]

for relationship in hospital_relationships:
    service_client.upsert_relationship(
        relationship["$sourceId"],
        relationship["$relationshipId"],
        relationship
    )

Listar relações de gêmeo digital

list_relationships e list_incoming_relationships lista todas as relações e todas as relações de entrada, respectivamente, de um gêmeo digital.

relationships = service_client.list_relationships(digital_twint_id)
for relationship in relationships:
    print(relationship)

incoming_relationships = service_client.list_incoming_relationships(digital_twin_id)
for incoming_relationship in incoming_relationships:
    print(incoming_relationship)

Criar, listar e excluir rotas de eventos de gêmeos digitais

Criar rotas de evento

Para criar uma rota de evento, forneça uma ID de uma rota de evento como "myEventRouteId" e dados de rota de evento que contêm o ponto de extremidade e o filtro opcional, como o exemplo mostrado abaixo.

event_route_id = 'eventRoute-' + str(uuid.uuid4())
event_filter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"
route = DigitalTwinsEventRoute(
    endpoint_name=event_hub_endpoint_name,
    filter=event_filter
)
service_client.upsert_event_route(event_route_id, route)

Para obter mais informações sobre a linguagem de filtro de rota de evento, consulte a documentação de eventos de filtro "como gerenciar rotas".

Listar rotas de evento

Liste uma rota de evento específica dada a ID de rota de evento ou todas as opções de configuração de rotas de evento com list_event_routes.

event_routes = service_client.list_event_routes()
for event_route in event_routes:
    print(event_route)

Excluir rotas de evento

Exclua uma rota de evento dada a ID da rota de evento.

service_client.delete_event_route(event_route_id)

Publicar mensagens de telemetria para um gêmeo digital

Para publicar uma mensagem de telemetria para um gêmeo digital, você precisa fornecer a ID do gêmeo digital, juntamente com a carga na qual a telemetria precisa da atualização.

digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
    digita_twin_id,
    telemetry_payload
)

Você também pode publicar uma mensagem de telemetria para um componente específico em um gêmeo digital. Além da ID do gêmeo digital e do conteúdo, você precisa especificar a ID do componente de destino.

digita_twin_id = "<DIGITAL TWIN ID>"
component_name = "<COMPONENT_NAME>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_component_telemetry(
    digita_twin_id,
    component_name,
    telemetry_payload
)

Solução de problemas

Log

Essa biblioteca usa a biblioteca de log padrão para o log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o argumento de palavra-chave logging_enable:

Log no nível do cliente

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Create service client and enable logging for all operations
service_client = DigitalTwinsClient(url, credential, logging_enable=True)

Registro em log no nível de operação

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Get model with logging enabled
model = service_client.get_model(model_id, logging_enable=True)

Configuração opcional

Argumentos de palavra-chave opcionais podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Próximas etapas

Forneça comentários

Se você encontrar bugs ou tiver sugestões, abra um problema.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Compartilhar via

Biblioteca de clientes do Azure Azure Digital Twins Core para Python – versão 1.2.0

Aviso de isenção de responsabilidade

Introdução

Introdução

Como instalar

Como usar

Autenticação, permissão

Código de exemplo

Principais conceitos

Exemplos

Criar, listar, desativar e excluir modelos

Criar modelos

Listar modelos

Obter modelo

Modelo de descomissionamento

Excluir modelo

Criar e excluir gêmeos digitais

Criar gêmeos digitais

Obter um gêmeo digital

Consultar os gêmeos digitais

Excluir gêmeos digitais

Obter e atualizar componentes do gêmeo digital

Atualizar componentes do gêmeo digital

Obter componentes do gêmeo digital

Criar e listar relações de gêmeo digital

Criar relações de gêmeo digital

Listar relações de gêmeo digital

Criar, listar e excluir rotas de eventos de gêmeos digitais

Criar rotas de evento

Listar rotas de evento

Excluir rotas de evento

Publicar mensagens de telemetria para um gêmeo digital

Solução de problemas

Log

Log no nível do cliente

Registro em log no nível de operação

Configuração opcional

Próximas etapas

Forneça comentários

Contribuição

Recursos adicionais