Клиентская библиотека Azure Digital Twins Core для Python версии 1.2.0
Этот пакет содержит пакет SDK для API Azure Digital Twins, предоставляющий доступ к службе Azure Digital Twins для управления двойниками, моделями, связями и т. д.
Заявление об отказе
Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691
Начало работы
Введение
Azure Digital Twins — это платформа разработчика для решений Интернета вещей нового поколения, которая позволяет безопасно и эффективно создавать, запускать и администрировать цифровые представления бизнес-среды в облаке. С помощью Azure Digital Twins создание динамических представлений рабочего состояния является быстрым и экономичным, а цифровые представления остаются актуальными с данными в реальном времени из Интернета вещей и других источников данных. Если вы еще не знакомы с Azure Digital Twins и хотите узнать больше о платформе, ознакомьтесь со страницей официальной документации по Azure Digital Twins.
Общие сведения о том, как программировать для службы Azure Digital Twins, см. на странице руководства по программированию , чтобы получить простое пошаговое руководство. Ознакомьтесь с этим руководством , чтобы узнать, как взаимодействовать с экземпляром Azure Digital Twin с помощью клиентского приложения командной строки. Наконец, краткое руководство по созданию комплексного решения Azure Digital Twins на основе динамических данных из вашей среды см. в этом полезном руководстве.
Приведенные выше руководства помогут вам приступить к работе с ключевыми элементами Azure Digital Twins, такими как создание экземпляров Azure Digital Twins, моделей, графов двойников и т. д. Используйте это руководство ниже, чтобы ознакомиться с различными API- интерфейсами, которые помогут вам программировать в Azure Digital Twins.
Установка
Установите [azure-digitaltwins-core][pypi_package_keys] и azure-identity с помощью pip:
pip install azure-digitaltwins-core azure-identity
Azure-identity используется для проверки подлинности Azure Active Directory, как показано ниже.
Использование
Проверка подлинности, разрешение
Чтобы создать клиент цифровых двойников, вам потребуется конечная точка экземпляра Azure Digital Twin и учетные данные.
Для приведенных ниже AZURE_URLпримеров необходимо задать переменные среды , AZURE_TENANT_ID, AZURE_CLIENT_IDи AZURE_CLIENT_SECRET .
Клиенту требуется экземпляр TokenCredential или ServiceClientCredentials.
В этих примерах мы иллюстрируем использование одного производного класса: DefaultAzureCredentials.
Примечание. Чтобы получить доступ к плоскости данных для службы Digital Twins, сущности должны быть предоставлены разрешения. Для этого используйте команду Azure CLI:
az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'
DefaultAzureCredential поддерживает различные механизмы проверки подлинности и определяет соответствующий тип учетных данных на основе среды, в которой он выполняется. Он пытается использовать несколько типов учетных данных в порядке, пока не найдет рабочие учетные данные.
Образец кода
# 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)
Основные понятия
Azure Digital Twins представляет собой службу Интернета вещей, с помощью которой можно создать комплексные модели физического окружения. С ее помощью можно создавать пространственные интеллектуальные графы для моделирования связей и взаимодействий между людьми, пространствами и устройствами. Дополнительные сведения об Azure Digital Twins см. в документации по Azure Digital Twins.
Примеры
Вы можете изучить API цифровых двойников (с помощью клиентской библиотеки) с помощью проекта примеров.
В проекте примеров показано следующее:
- Создание экземпляра клиента
- Создание, получение и вывод моделей из эксплуатации
- Создание, запрос и удаление цифрового двойника
- Получение и обновление компонентов для цифрового двойника
- Создание, получение и удаление связей между цифровыми двойниками
- Создание, получение и удаление маршрутов событий для цифрового двойника
- Публикация сообщений телеметрии в цифровом двойнику и компоненте цифрового двойника
Создание, перечисление, вывод из эксплуатации и удаление моделей
Создание моделей
Давайте создадим модели с помощью приведенного ниже кода. Необходимо передать массив, содержащий список моделей.
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)
Перечисление моделей
Использование list_models для получения всех созданных моделей
listed_models = service_client.list_models()
for model in listed_models:
print(model)
Получение модели
Используйте get_model с уникальным идентификатором модели, чтобы получить определенную модель.
# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)
Модель вывода из эксплуатации
Чтобы вывести модель из эксплуатации, передайте идентификатор модели, которую требуется вывести из эксплуатации.
# Decommission a model
service_client.decommission_model(model_id)
Удаление модели
Чтобы удалить модель, передайте идентификатор модели, которую нужно удалить.
# Delete a model
service_client.delete_model(model_id)
Создание и удаление цифровых двойников
Создание цифровых двойников
Для создания двойника необходимо указать идентификатор цифрового двойника, например my_twin и цифрового двойника приложения или json на основе созданной ранее модели. Пример приложения или json можно просмотреть здесь.
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)
Получение цифрового двойника
Получить цифровой двойник очень просто.
get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)
Запрашивание цифровых двойников
Запрос экземпляра Azure Digital Twins для цифровых двойников с помощью azure Digital Twins хранилище запросов lanaguage. Вызовы запросов поддерживают разбивку на страницы. Ниже приведен пример того, как запрашивать цифровые двойники и выполнять итерацию по результатам.
Обратите внимание, что между изменениями в экземпляре может возникнуть задержка. Дополнительные сведения об ограничениях запросов см. в разделе (/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)
Удаление цифровых двойников
Удалите цифровой двойник, просто указав идентификатор цифрового двойника, как показано ниже.
service_client.delete_digital_twin(digital_twin_id)
Получение и обновление компонентов цифрового двойника
Обновление компонентов цифрового двойника
Чтобы обновить компонент или другими словами заменить, удалить и (или) добавить свойство или подсвойство компонента в Digital Twin, вам потребуется идентификатор цифрового двойника, имя компонента и операции application/json-patch+json, которые должны выполняться с компонентом указанного цифрового двойника. Ниже приведен пример кода, который описывает, как это сделать.
component_name = "Component1"
patch = [
{
"op": "replace",
"path": "/ComponentProp1",
"value": "value2"
}
]
service_client.update_component(digital_twin_id, component_name, patch)
Получение компонентов цифрового двойника
Получите компонент, указав имя компонента и идентификатор цифрового двойника, которому он принадлежит.
get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)
Создание и перечисление связей цифровых двойников
Создание связей цифровых двойников
upsert_relationship создает связь для цифрового двойника, предоставленного с идентификатором цифрового двойника, именем связи, например "contains", идентификатором связи, например "FloorContainsRoom", и создаваемой связью application/json. Должно содержать свойство с ключом "$targetId", чтобы указать целевой объект связи. Примеры полезных данных для связей можно найти здесь.
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
)
Перечисление связей цифровых двойников
list_relationships и list_incoming_relationships перечисляет все связи и все входящие связи цифрового двойника соответственно.
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)
Создание, перечисление и удаление маршрутов событий цифровых двойников
Создание маршрутов событий
Чтобы создать маршрут событий, укажите идентификатор маршрута события, например myEventRouteId, и данные маршрута событий, содержащие конечную точку и необязательный фильтр, как показано в примере ниже.
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)
Дополнительные сведения о языке фильтра маршрутов событий см. в документации по управлению событиями фильтра маршрутов.
Перечисление маршрутов событий
Укажите конкретный маршрут события, заданный идентификатор маршрута события или все маршруты событий, задав параметры с list_event_routesпомощью .
event_routes = service_client.list_event_routes()
for event_route in event_routes:
print(event_route)
Удаление маршрутов событий
Удалите маршрут события, заданный идентификатором маршрута события.
service_client.delete_event_route(event_route_id)
Публикация сообщений телеметрии для цифрового двойника
Чтобы опубликовать сообщение телеметрии для цифрового двойника, необходимо указать идентификатор цифрового двойника вместе с полезными данными телеметрии, для которых требуется обновление.
digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
digita_twin_id,
telemetry_payload
)
Вы также можете опубликовать сообщение телеметрии для определенного компонента в цифровом двойнике. Помимо идентификатора цифрового двойника и полезных данных необходимо указать идентификатор целевого компонента.
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
)
Устранение неполадок
Ведение журнала
Эта библиотека использует для ведения журнала соответствующую стандартную библиотеку. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.
Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте с помощью аргумента ключевого слова logging_enable:
Ведение журнала на уровне клиента
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)
Ведение журнала на уровне операций
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)
Дополнительная настройка
Необязательные аргументы ключевого слова можно передать на уровне клиента и на уровне операций. В справочной документации azure-Core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.
Дальнейшие действия
Отзывы
Если у вас возникли ошибки или есть предложения, откройте проблему.
Участие
На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.
При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.
В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.
Azure SDK for Python
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по