Share via

Azure Azure Digital Twins Core-Clientbibliothek für Python– Version 1.2.0

  • Artikel

Dieses Paket enthält ein SDK für die Azure Digital Twins-API, um Zugriff auf den Azure Digital Twins-Dienst zum Verwalten von Zwillingen, Modellen, Beziehungen usw. bereitzustellen.

Haftungsausschluss

Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Einführung

Azure Digital Twins ist eine Entwicklerplattform für IoT-Lösungen der nächsten Generation, mit der Sie digitale Darstellungen Ihrer Geschäftsumgebung sicher und effizient in der Cloud erstellen, ausführen und verwalten können. Mit Azure Digital Twins ist das Erstellen von Livebetriebszustandsdarstellungen schnell und kostengünstig, und digitale Darstellungen bleiben mit Echtzeitdaten aus IoT und anderen Datenquellen auf dem neuesten Stand. Wenn Sie noch nicht mit Azure Digital Twins vertraut sind und mehr über die Plattform erfahren möchten, sollten Sie sich die offizielle Dokumentationsseite für Azure Digital Twins ansehen.

Eine Einführung in das Programmieren mit dem Azure Digital Twins-Dienst finden Sie auf der Tutorialseite zum Programmieren , um eine einfache Schritt-für-Schritt-Anleitung zu erhalten. In diesem Tutorial erfahren Sie, wie Sie mithilfe einer Befehlszeilenclientanwendung mit einer Azure Digital Twin-Instanz interagieren. Eine kurze Anleitung zum Erstellen einer End-to-End-Lösung von Azure Digital Twins, die von Livedaten aus Ihrer Umgebung gesteuert wird, finden Sie in diesem hilfreichen Leitfaden.

Die oben genannten Leitfäden helfen Ihnen bei den ersten Schritten mit wichtigen Elementen von Azure Digital Twins, z. B. beim Erstellen von Azure Digital Twins-Instanzen, Modellen, Zwillingsgraphen usw. Verwenden Sie diesen Beispielleitfaden unten, um sich mit den verschiedenen APIs vertraut zu machen, die Ihnen beim Programmieren für Azure Digital Twins helfen.

Installation

Installieren Sie [azure-digitaltwins-core][pypi_package_keys] und azure-identity mit pip:

pip install azure-digitaltwins-core azure-identity

azure-identity wird für die Azure Active Directory-Authentifizierung verwendet, wie unten gezeigt.

Verwendung

Authentifizierung, Berechtigung

Um einen neuen Digital Twins-Client zu erstellen, benötigen Sie den Endpunkt für eine Azure Digital Twin-Instanz und Anmeldeinformationen. Für die folgenden Beispiele müssen die Umgebungsvariablen AZURE_URL, AZURE_TENANT_ID, AZURE_CLIENT_IDund AZURE_CLIENT_SECRET festgelegt werden. Der Client erfordert eine Instanz von TokenCredential oder ServiceClientCredentials. In diesem Beispiel wird veranschaulicht, wie eine abgeleitete Klasse verwendet wird: DefaultAzureCredentials.

Hinweis: Um auf die Datenebene für den Digital Twins-Dienst zugreifen zu können, müssen der Entität Berechtigungen erteilt werden. Verwenden Sie hierzu den Azure CLI-Befehl: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den geeigneten Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis funktionierende Anmeldeinformationen gefunden werden.

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

Wichtige Begriffe

Azure Digital Twins ist ein Azure IoT-Dienst zur Erstellung umfassender Modelle der physischen Umgebung. Er kann Raumintelligenzgraphen erstellen, um die Beziehungen und Interaktionen zwischen Personen, Bereichen und Geräten zu modellieren. Weitere Informationen zu Azure Digital Twins finden Sie in der Dokumentation zu Azure Digital Twins.

Beispiele

Sie können die APIs für digitale Zwillinge (mithilfe der Clientbibliothek) mithilfe des Beispielprojekts untersuchen.

Das Beispielprojekt veranschaulicht Folgendes:

  • Instanziieren des Clients
  • Erstellen, Abrufen und Außerbetriebnahme von Modellen
  • Erstellen, Abfragen und Löschen eines digitalen Zwillings
  • Abrufen und Aktualisieren von Komponenten für einen digitalen Zwilling
  • Erstellen, Abrufen und Löschen von Beziehungen zwischen digitalen Zwillingen
  • Erstellen, Abrufen und Löschen von Ereignisrouten für den digitalen Zwilling
  • Veröffentlichen von Telemetrienachrichten für einen digitalen Zwilling und eine Komponente für digitale Zwillinge

Erstellen, Auflisten, Außerbetriebnahme und Löschen von Modellen

Erstellen von Modellen

Wir erstellen Modelle mithilfe des folgenden Codes. Sie müssen ein Array übergeben, das eine Liste von Modellen enthält.

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)

Auflisten von Modellen

Verwenden, list_models um alle erstellten Modelle abzurufen

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

Modell abrufen

Verwenden Sie get_model mit dem eindeutigen Bezeichner des Modells, um ein bestimmtes Modell abzurufen.

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

Außerbetriebnahmemodell

Um dieCommision eines Modells aufzugeben, übergeben Sie eine Modell-ID für das Modell, das Sie aufheben möchten.

# Decommission a model
service_client.decommission_model(model_id)

Löschen des Modells

Um ein Modell zu löschen, übergeben Sie eine Modell-ID für das Modell, das Sie löschen möchten.

# Delete a model
service_client.delete_model(model_id)

Erstellen und Löschen von digitalen Zwillingen

Erstellen digitaler Zwillinge

Zum Erstellen eines Zwillings müssen Sie die ID eines digitalen Zwillings angeben, z my_twin . B. und den digitalen Anwendungs-/JSON-Zwilling basierend auf dem zuvor erstellten Modell. Sie können sich hier ein Beispiel für anwendung/json ansehen.

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)

Abrufen eines digitalen Zwillings

Ein digitaler Zwilling ist extrem einfach.

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

Abfragen von digitalen Zwillingen

Fragen Sie die Azure Digital Twins-Instanz mithilfe von Azure Digital Twins Abfragespeicher lanaguage nach digitalen Zwillingen ab. Abfrageaufrufe unterstützen Paging. Hier sehen Sie ein Beispiel dafür, wie Sie digitale Zwillinge abfragen und die Ergebnisse durchlaufen.

Beachten Sie, dass es möglicherweise zu einer Verzögerung zwischen den Abfragen kommt, bevor Änderungen in Ihrer Instanz in Abfragen widerzuspiegeln sind. Weitere Informationen zu Abfragebeschränkungen finden Sie unter (/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)

Löschen von digitalen Zwillingen

Löschen Sie einen digitalen Zwilling, indem Sie einfach die ID eines digitalen Zwillings wie unten angegeben angeben.

service_client.delete_digital_twin(digital_twin_id)

Abrufen und Aktualisieren von Komponenten für digitale Zwillinge

Aktualisieren von Komponenten für digitale Zwillinge

Zum Aktualisieren einer Komponente oder anders ausgedrückt zum Ersetzen, Entfernen und/oder Hinzufügen einer Komponenteneigenschaft oder -untereigenschaft in Digital Twin müssen id eines digitalen Zwillings, Komponentenname und application/json-patch+json-Vorgänge für die Komponente des angegebenen digitalen Zwillings ausgeführt werden. Im Folgenden finden Sie den Beispielcode für die Vorgehensweise.

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

Abrufen von Komponenten für digitale Zwillinge

Rufen Sie eine Komponente ab, indem Sie den Namen einer Komponente und die ID des digitalen Zwillings angeben, zu dem sie gehört.

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

Erstellen und Auflisten von Beziehungen zu digitalen Zwillingen

Erstellen von Beziehungen zu digitalen Zwillingen

upsert_relationship erstellt eine Beziehung zu einem digitalen Zwilling, die mit der ID eines digitalen Zwillings, dem Namen der Beziehung wie "contains", der ID einer Beziehung wie "FloorContainsRoom" und einer zu erstellenden Anwendungs-JSON-Beziehung bereitgestellt wird. Muss die Eigenschaft mit dem Schlüssel "$targetId" enthalten, um das Ziel der Beziehung anzugeben. Beispielnutzlasten für Beziehungen finden Sie hier.

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
    )

Auflisten von Beziehungen mit digitalen Zwillingen

list_relationships und list_incoming_relationships listet alle Beziehungen bzw. alle eingehenden Beziehungen eines digitalen Zwillings auf.

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)

Erstellen, Auflisten und Löschen von Ereignisrouten für digitale Zwillinge

Erstellen von Ereignisrouten

Um eine Ereignisroute zu erstellen, geben Sie eine ID einer Ereignisroute wie "myEventRouteId" und Ereignisroutendaten an, die den Endpunkt und optionalen Filter enthalten, wie im folgenden Beispiel gezeigt.

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)

Weitere Informationen zur Filtersprache für Ereignisrouten finden Sie in der Dokumentation zum Verwalten von Routenfilterereignissen.

Auflisten von Ereignisrouten

Auflisten einer bestimmten Ereignisroute, die ereignisrouten-ID oder alle Ereignisrouten-Einstellungsoptionen mit angegeben sind list_event_routes.

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

Löschen von Ereignisrouten

Löscht eine Ereignisroute mit der angegebenen Ereignisrouten-ID.

service_client.delete_event_route(event_route_id)

Veröffentlichen von Telemetriemeldungen für einen digitalen Zwilling

Um eine Telemetrienachricht für einen digitalen Zwilling zu veröffentlichen, müssen Sie die ID des digitalen Zwillings zusammen mit der Nutzlast angeben, für die die Telemetriedaten aktualisiert werden müssen.

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

Sie können auch eine Telemetrienachricht für eine bestimmte Komponente in einem digitalen Zwilling veröffentlichen. Zusätzlich zur ID und Nutzlast des digitalen Zwillings müssen Sie die Zielkomponenten-ID angeben.

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
)

Problembehandlung

Protokollierung

Diese Bibliothek verwendet für die Protokollierung die Standardprotokollierungsbibliothek. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem Logging_enable-Schlüsselwortargument aktiviert werden:

Protokollierung auf Clientebene

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)

Protokollierung pro Vorgangsebene

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)

Optionale Konfiguration

Optionale Schlüsselwortargumente können auf Client- und Vorgangsebene übergeben werden. In der Azure Core-Referenzdokumentation werden verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr beschrieben.

Nächste Schritte

Feedback geben

Wenn Fehler auftreten oder wenn Sie Vorschläge haben, erstellen Sie ein Problem.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.