Biblioteca de clientes Azure Azure Digital Twins Core para Python - versão 1.2.0
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
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.
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