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

Artigo
04/05/2023

Este pacote contém um SDK para a Azure Digital Twins API para fornecer acesso ao serviço Azure Digital Twins para gerir gémeos, modelos, relacionamentos, etc.

Exclusão de Responsabilidade

O apoio aos pacotes Azure SDK Python para python 2.7 terminou em 01 de janeiro de 2022. Para mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

A Azure Digital Twins é uma plataforma de desenvolvimento para soluções IoT de próxima geração que permite criar, executar e gerir representações digitais do seu ambiente de negócios, de forma segura e eficiente na nuvem. Com a Azure Digital Twins, a criação de representações estatais operacionais ao vivo é rápida e rentável, e as representações digitais permanecem atuais com dados em tempo real da IoT e de outras fontes de dados. Se é novo na Azure Digital Twins e gostaria de saber mais sobre a plataforma, por favor, certifique-se de consultar a página oficial de documentação da Azure Digital Twins.

Para uma introdução sobre como programar contra o serviço Azure Digital Twins, visite a página tutorial de codificação para um guia passo a passo fácil. Visite este tutorial para aprender a interagir com uma instância Azure Digital Twin utilizando uma aplicação de cliente de linha de comando. Finalmente, para um guia rápido sobre como construir uma solução de gémeos digitais Azure que é impulsionada por dados ao vivo do seu ambiente, certifique-se de consultar este guia útil.

Os guias acima mencionados podem ajudá-lo a começar com elementos-chave da Azure Digital Twins, tais como a criação de instâncias, modelos, gráficos duplos, etc. Utilize este guia de amostras abaixo para se familiarizar com as várias APIs que o ajudam a programar contra as Gémeas Digitais Azure.

Como instalar

Instalar [azure-digitaltwins-core][pypi_package_keys] e azure-identidade com pip:

pip install azure-digitaltwins-core azure-identity

a identidade azul é usada para a autenticação do Diretório Ativo Azure, conforme demonstrado abaixo.

Como utilizar

Autenticação, permissão

Para criar um novo cliente de gémeos digitais, você precisa do ponto final para uma instância Estil Digital Azure e credenciais. Para as amostras abaixo, as AZURE_URLvariáveis , AZURE_TENANT_IDe AZURE_CLIENT_IDAZURE_CLIENT_SECRET ambiente têm de ser definidas. O cliente requer uma instância de TokenCredential ou ServiceClientCredentials. Nestas amostras, ilustramos como usar uma classe derivada: DefaultAzureCredentials.

Nota: Para aceder ao plano de dados para o serviço Digital Twins, a entidade deve ter permissões. Para isso, utilize o comando Azure CLI: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

O DefaultAzureCredential suporta diferentes mecanismos de autenticação e determina o tipo credencial adequado baseado no ambiente em que está a executar. Tenta usar vários tipos de credenciais numa ordem até encontrar uma credencial de 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)

Conceitos-chave

O Azure Digital Twins é um serviço do Azure IoT que cria modelos abrangentes do ambiente físico. Pode criar gráficos de inteligência espacial para modelar as relações e interações entre pessoas, espaços e dispositivos. Você pode saber mais sobre Azure Digital Twins visitando Azure Digital Twins Documentação.

Exemplos

Você pode explorar as APIs de gémeos digitais (usando a biblioteca do cliente) usando o projeto amostras.

O projeto de amostras demonstra o seguinte:

Instanciar o cliente
Criar, obter e desativar modelos
Criar, consultar e eliminar um gémeo digital
Obter e atualizar componentes para um gémeo digital
Criar, obter e apagar relações entre gémeos digitais
Criar, obter e apagar rotas de eventos para gémeos digitais
Publique mensagens de telemetria a um componente digital twin e digital twin

Criar, listar, desativar e eliminar modelos

Criar modelos

Vamos criar modelos usando o código abaixo. Tens de passar por uma lista de modelos que contenha.

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)

Modelos de lista

Usando 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 único 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 desmantelamento

Para descomplitar um modelo, passe num ID de modelo para o modelo que pretende descomplitar.

# Decommission a model
service_client.decommission_model(model_id)

Eliminar modelo

Para eliminar um modelo, passe um Id de modelo para o modelo que pretende eliminar.

# Delete a model
service_client.delete_model(model_id)

Criar e eliminar gémeos digitais

Criar duplos digitais

Para criar twin, terá de fornecer Id de um Twin digital como my_twin e o twin digital de aplicação/json baseado no modelo criado anteriormente. Pode olhar para a aplicação da amostra/json 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

Arranjar um gémeo digital é extremamente fácil.

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

Consultas gémeas digitais

Consulta a exemplo de Gémeos Digitais Azure para gémeos digitais que usam a Azure Digital Twins Query Store lanaguage. Consulta chama de apoio de paging. Aqui está um exemplo de como consultar gémeos digitais e como iterar sobre os resultados.

Note que pode haver um atraso entre antes que as alterações no seu caso sejam refletidas em consultas. Para obter mais detalhes sobre as limitações de consulta, consulte (/azure/digital-twins/how-to-consulta-graph#questionry-limitações)

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

Eliminar gémeos digitais

Elimine um gémeo digital simplesmente fornecendo id de um gémeo digital como abaixo.

service_client.delete_digital_twin(digital_twin_id)

Obter e atualizar componentes digitais gémeos

Atualizar componentes gémeos digitais

Para atualizar um componente ou por outras palavras para substituir, remover e/ou adicionar uma propriedade componente ou subproteperty dentro da Digital Twin, você precisaria de identificação de um twin digital, nome de componente e operações de aplicação/json-patch+json para ser executado no componente digital especificado twin. Aqui está o código de amostra de como fazê-lo.

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

Obtenha componentes gémeos digitais

Obtenha um componente fornecendo o nome de um componente e id de twin digital a que pertence.

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

Criar e listar relações gémeas digitais

Criar relações gémeas digitais

upsert_relationship cria uma relação num gémeo digital fornecido com ID de um gémeo digital, nome de relação como "contém", Id de uma relação como "FloorContainsRoom" e uma relação aplicação/json a ser criada. Deve conter propriedade com "$targetId" chave para especificar o alvo da relação. As cargas de amostra para relacionamentos podem ser encontradas 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 gémeas digitais

list_relationships e list_incoming_relationships lista todas as relações e todas as relações recebidas, 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 apagar rotas de eventos de gémeos digitais

Criar rotas de eventos

Para criar uma rota de eventos, forneça um Id de uma rota de eventos como "myEventRouteId" e dados de rota de eventos que contenham o ponto final e 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 o idioma do filtro de rotas do evento, consulte a documentação de filtragem de eventos de filtro "como gerir rotas".

Listar rotas de eventos

Liste uma rota específica de eventos dado o Id da rota do evento ou todas as rotas de eventos definindo opções com list_event_routes.

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

Excluir rotas de eventos

Elimine uma rota de evento dada a rota do evento Id.

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, é necessário fornecer o ID digital twin, juntamente com a carga útil em que 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
)

Também pode publicar uma mensagem de telemetria para um componente específico num gémeo digital. Além do ID digital twin e da carga útil, tem de especificar o ID do componente alvo.

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
)

Resolução de problemas

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos. Informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível info.

A registo detalhado do nível DEBUG, incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos, pode ser ativado num cliente com o argumento logging_enable palavra-chave:

Registo de nível de 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)

Registo de nível de operação por 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

Os argumentos de palavras-chave opcionais podem ser transmitidos ao cliente e ao nível por operação. A documentação de referência do núcleo azul descreve as configurações disponíveis para recaídas, registos, protocolos de transporte e muito mais.

Passos seguintes

Enviar Comentários

Se encontrar escutas ou tiver sugestões, por favor abra um problema.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Partilhar via

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

Exclusão de Responsabilidade

Introdução

Introdução

Como instalar

Como utilizar

Autenticação, permissão

Código de exemplo

Conceitos-chave

Exemplos

Criar, listar, desativar e eliminar modelos

Criar modelos

Modelos de lista

Obter modelo

Modelo de desmantelamento

Eliminar modelo

Criar e eliminar gémeos digitais

Criar duplos digitais

Obter um gémeo digital

Consultas gémeas digitais

Eliminar gémeos digitais

Obter e atualizar componentes digitais gémeos

Atualizar componentes gémeos digitais

Obtenha componentes gémeos digitais

Criar e listar relações gémeas digitais

Criar relações gémeas digitais

Listar relações gémeas digitais

Criar, listar e apagar rotas de eventos de gémeos digitais

Criar rotas de eventos

Listar rotas de eventos

Excluir rotas de eventos

Publicar mensagens de telemetria para um gémeo digital

Resolução de problemas

Registo

Registo de nível de cliente

Registo de nível de operação por operação

Configuração opcional

Passos seguintes

Enviar Comentários

Contribuir

Recursos adicionais