Azure Azure Digital Twins Core-Clientbibliothek für Python– Version 1.2.0
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_ID
und 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.
Azure SDK for Python