Klientská knihovna Azure Digital Twins Core pro Python – verze 1.2.0

Článek
04/05/2023

Tento balíček obsahuje sadu SDK pro rozhraní API služby Azure Digital Twins, která poskytuje přístup ke službě Azure Digital Twins pro správu dvojčat, modelů, relací atd.

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Úvod

Azure Digital Twins je vývojářská platforma pro řešení IoT nové generace, která umožňuje bezpečně a efektivně vytvářet, spouštět a spravovat digitální reprezentace vašeho podnikového prostředí, a to bezpečně a efektivně v cloudu. Se službou Azure Digital Twins je vytváření živých reprezentací provozního stavu rychlé a nákladově efektivní a digitální reprezentace zůstávají aktuální díky datům z IoT a dalších zdrojů dat v reálném čase. Pokud se službou Azure Digital Twins začínáte a chcete se o této platformě dozvědět více, nezapomeňte se podívat na oficiální stránku dokumentace ke službě Azure Digital Twins.

Úvodní informace o tom, jak programovat proti službě Azure Digital Twins, najdete na stránce s kurzem kódování , kde najdete jednoduchého podrobného průvodce. V tomto kurzu se dozvíte, jak interagovat s instancí Azure Digital Twin pomocí klientské aplikace příkazového řádku. Nakonec se podívejte na tohoto užitečného průvodce, který vám pomůže vytvořit ucelené řešení Azure Digital Twins založené na živých datech z vašeho prostředí.

Výše uvedené příručky vám můžou pomoct začít s klíčovými prvky služby Azure Digital Twins, jako je vytváření instancí služby Azure Digital Twins, modelů, grafů dvojčat atd. Pomocí následujícího ukázkového průvodce se seznámíte s různými rozhraními API, která vám pomůžou programovat s využitím služby Azure Digital Twins.

Postup instalace

Nainstalujte [azure-digitaltwins-core][pypi_package_keys] a azure-identity pomocí pip:

pip install azure-digitaltwins-core azure-identity

Azure-identity se používá k ověřování Azure Active Directory, jak je znázorněno níže.

Způsob použití

Ověřování, oprávnění

K vytvoření nového klienta digitálních dvojčat potřebujete koncový bod instance a přihlašovací údaje služby Azure Digital Twins. Pro níže uvedené AZURE_URLukázky je potřeba nastavit proměnné prostředí , AZURE_TENANT_IDAZURE_CLIENT_ID, a AZURE_CLIENT_SECRET . Klient vyžaduje instanci TokenCredential nebo ServiceClientCredentials. V těchto ukázkách ukazujeme, jak použít jednu odvozenou třídu: DefaultAzureCredentials.

Poznámka: Aby bylo možné získat přístup k rovině dat pro službu Digital Twins, musí mít entitě udělená oprávnění. K tomu použijte příkaz Azure CLI: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se spouští. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Ukázka kódu

# 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)

Klíčové koncepty

Azure Digital Twins je služba Azure IoT, která vytváří komplexní modely fyzického prostředí. Může vytvářet grafy prostorové inteligence pro modelování vztahů a interakcí mezi lidmi, prostory a zařízeními. Další informace o službě Azure Digital Twins najdete v dokumentaci ke službě Azure Digital Twins.

Příklady

Rozhraní API služby Digital Twins (pomocí klientské knihovny) můžete prozkoumat pomocí ukázkového projektu.

Ukázkový projekt ukazuje následující:

Vytvoření instance klienta
Vytvoření, získání a vyřazení modelů z provozu
Vytvoření, dotazování a odstranění digitálního dvojčete
Získání a aktualizace komponent pro digitální dvojče
Vytvoření, získání a odstranění vztahů mezi digitálními dvojčaty
Vytvoření, získání a odstranění tras událostí pro digitální dvojče
Publikování zpráv telemetrie do digitálního dvojčete a komponenty digitálního dvojčete

Vytvoření, výpis, vyřazení z provozu a odstranění modelů

Vytváření modelů

Pojďme vytvořit modely pomocí následujícího kódu. Potřebujete předat pole obsahující seznam modelů.

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)

Výpis modelů

Použití list_models k načtení všech vytvořených modelů

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

Získání modelu

Použijte get_model s jedinečným identifikátorem modelu k získání konkrétního modelu.

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

Vyřazení modelu z provozu

Chcete-li dekompizi modelu dekompizi, předejte id modelu, který chcete dekommisovat.

# Decommission a model
service_client.decommission_model(model_id)

Odstranit model

Pokud chcete model odstranit, předejte id modelu, který chcete odstranit.

# Delete a model
service_client.delete_model(model_id)

Vytvoření a odstranění digitálních dvojčat

Vytvoření digitálních dvojčat

Při vytváření dvojčete budete muset zadat ID digitálního dvojčete, jako my_twin je, a digitální dvojče application/json na základě modelu vytvořeného dříve. Ukázkovou aplikaci/json si můžete prohlédnout tady.

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)

Získání digitálního dvojčete

Získání digitálního dvojčete je velmi snadné.

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

Dotazování digitálních dvojčat

Zadejte dotaz na instanci služby Azure Digital Twins na digitální dvojčata pomocí úložiště dotazů Azure Digital Twins lanaguage. Volání dotazů podporují stránkování. Tady je příklad, jak se dotazovat na digitální dvojčata a jak iterovat výsledky.

Mějte na paměti, že mezi tím, než se změny ve vaší instanci projeví v dotazech, může dojít ke zpoždění. Další podrobnosti o omezeních dotazů najdete v tématu (/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)

Odstranění digitálních dvojčat

Digitální dvojče odstraníte jednoduše zadáním ID digitálního dvojčete, jak je uvedeno níže.

service_client.delete_digital_twin(digital_twin_id)

Získání a aktualizace součástí digitálního dvojčete

Aktualizace součástí digitálního dvojčete

Pokud chcete aktualizovat komponentu nebo jinými slovy nahradit, odebrat nebo přidat vlastnost nebo dílčí vlastnost komponenty v rámci digitálního dvojčete, potřebujete, aby se na zadané komponentě digitálního dvojčete provedlo ID digitálního dvojčete, název komponenty a operace application/json-patch+json. Tady je ukázkový kód, jak to udělat.

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

Získání komponent digitálního dvojčete

Získejte komponentu zadáním názvu komponenty a ID digitálního dvojčete, ke kterému patří.

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

Vytvoření a výpis vztahů digitálních dvojčat

Vytvoření vztahů digitálních dvojčat

upsert_relationship vytvoří relaci u digitálního dvojčete s ID digitálního dvojčete, názvem relace, jako je "contains", ID relace, například FloorContainsRoom, a relací aplikace/json, která se má vytvořit. Aby bylo možné určit cíl relace, musí obsahovat vlastnost s klíčem "$targetId". Ukázkové datové části pro relace najdete tady.

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
    )

Výpis vztahů digitálních dvojčat

list_relationships a list_incoming_relationships vypíše všechny relace a všechny příchozí relace digitálního dvojčete.

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)

Vytvoření, výpis a odstranění tras událostí digitálních dvojčat

Vytvoření tras událostí

Pokud chcete vytvořit trasu události, zadejte ID trasy události, například myEventRouteId, a data trasy události obsahující koncový bod a volitelný filtr jako v příkladu níže.

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)

Další informace o jazyku filtru tras událostí najdete v dokumentaci k událostem filtru "Jak spravovat trasy".

Výpis tras událostí

Vypište konkrétní trasu události s daným ID trasy události nebo všemi možnostmi nastavení tras událostí pomocí list_event_routes.

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

Odstranění tras událostí

Odstraňte trasu události a dané ID trasy události.

service_client.delete_event_route(event_route_id)

Publikování zpráv telemetrie pro digitální dvojče

Pokud chcete publikovat zprávu telemetrie pro digitální dvojče, musíte zadat ID digitálního dvojčete spolu s datovou částí, pro kterou je potřeba aktualizovat telemetrická data.

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

Můžete také publikovat telemetrické zprávy pro konkrétní komponentu v digitálním dvojčeti. Kromě ID a datové části digitálního dvojčete musíte zadat ID cílové komponenty.

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
)

Poradce při potížích

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování. Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně DEBUG, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné v klientovi povolit pomocí argumentu logging_enable klíčového slova:

Protokolování na úrovni klienta

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)

Protokolování na úrovni jednotlivých operací

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)

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a na úrovni jednotlivých operací. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Další kroky

Zadání zpětné vazby

Pokud narazíte na chyby nebo máte návrhy, otevřete problém.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Sdílet prostřednictvím