Delen via

Azure Azure Digital Twins Core-clientbibliotheek voor Python - versie 1.2.0

  • Artikel

Dit pakket bevat een SDK voor Azure Digital Twins API om toegang te bieden tot de Azure Digital Twins-service voor het beheren van tweelingen, modellen, relaties, enzovoort.

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Introductie

Azure Digital Twins is een ontwikkelaarsplatform voor IoT-oplossingen van de volgende generatie waarmee u veilig en efficiënt digitale weergaven van uw bedrijfsomgeving kunt maken, uitvoeren en beheren. Met Azure Digital Twins is het maken van live operationele statusweergaven snel en rendabel en blijven digitale representaties actueel met realtimegegevens uit IoT en andere gegevensbronnen. Als u nieuw bent bij Azure Digital Twins en meer wilt weten over het platform, raadpleegt u de officiële documentatiepagina van Azure Digital Twins.

Voor een inleiding over het programmeren met de Azure Digital Twins-service, gaat u naar de pagina voor de zelfstudie over coderen voor een eenvoudige stapsgewijze handleiding. Ga naar deze zelfstudie voor meer informatie over het werken met een Azure Digital Twin-exemplaar met behulp van een opdrachtregelclienttoepassing. Lees ten slotte deze handige handleiding voor een beknopte handleiding over het bouwen van een end-to-end Azure Digital Twins-oplossing die wordt aangestuurd door livegegevens uit uw omgeving.

De bovenstaande handleidingen kunnen u helpen aan de slag te gaan met belangrijke elementen van Azure Digital Twins, zoals het maken van Azure Digital Twins-exemplaren, modellen, dubbelgrafieken, enzovoort. Gebruik deze onderstaande voorbeeldgids om vertrouwd te raken met de verschillende API's die u helpen bij het programmeren met Azure Digital Twins.

Installeren

Installeer [azure-digitaltwins-core][pypi_package_keys] en azure-identity met pip:

pip install azure-digitaltwins-core azure-identity

azure-identity wordt gebruikt voor Azure Active Directory-verificatie, zoals hieronder wordt weergegeven.

Gebruik

Verificatie, machtiging

Als u een nieuwe digital twins-client wilt maken, hebt u het eindpunt naar een Azure Digital Twin-exemplaar en referenties nodig. Voor de onderstaande voorbeelden moeten de AZURE_URLomgevingsvariabelen , AZURE_TENANT_IDAZURE_CLIENT_ID, en AZURE_CLIENT_SECRET worden ingesteld. De client vereist een exemplaar van TokenCredential of ServiceClientCredentials. In deze voorbeelden laten we zien hoe u één afgeleide klasse gebruikt: DefaultAzureCredentials.

Opmerking: voor toegang tot het gegevensvlak voor de Digital Twins-service moet aan de entiteit machtigingen worden verleend. Gebruik hiervoor de Azure CLI-opdracht: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat een werkende referentie wordt gevonden.

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

Belangrijkste concepten

Azure Digital Twins is een Azure IoT-service waarmee uitgebreide modellen van de fysieke omgeving worden gemaakt. Er kunnen grafieken voor ruimtelijke intelligentie mee worden gemaakt voor het modelleren van de relaties en interacties tussen personen, ruimten en apparaten. Ga naar Documentatie voor Azure Digital Twins voor meer informatie over Azure Digital Twins.

Voorbeelden

U kunt de DIGITAL Twins-API's verkennen (met behulp van de clientbibliotheek) met behulp van het voorbeeldproject.

In het voorbeeldproject ziet u het volgende:

  • Een instantie maken voor de client
  • Modellen maken, ophalen en buiten gebruik stellen
  • Een digitale dubbel maken, er query's op uitvoeren en verwijderen
  • Onderdelen voor een digitale dubbel ophalen en bijwerken
  • Relaties tussen digitale dubbels maken, ophalen en verwijderen
  • Gebeurtenisroutes voor digitale dubbels maken, ophalen en verwijderen
  • Telemetrieberichten publiceren naar een digital twin en digital twin component

Modellen maken, weergeven, buiten gebruik stellen en verwijderen

Modellen maken

Laten we modellen maken met behulp van de onderstaande code. U moet een matrix met een lijst met modellen doorgeven.

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)

Modellen weergeven

Gebruiken list_models om alle gemaakte modellen op te halen

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

Model ophalen

Gebruik get_model met de unieke id van het model om een specifiek model op te halen.

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

Model buiten bedrijf stellen

Als u een model wilt opsplitsen, geeft u een model-id door voor het model dat u wilt decommisioneren.

# Decommission a model
service_client.decommission_model(model_id)

Model verwijderen

Als u een model wilt verwijderen, geeft u een model-id door voor het model dat u wilt verwijderen.

# Delete a model
service_client.delete_model(model_id)

Digitale dubbels maken en verwijderen

Digitale tweelingen maken

Voor het maken van een tweeling moet u de id van een digitale dubbel opgeven, zoals my_twin en de digitale toepassings-/json-dubbel op basis van het model dat u eerder hebt gemaakt. U kunt hier de voorbeeldtoepassing/json bekijken.

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)

Een digitale dubbel ophalen

Het verkrijgen van een digitale dubbel is heel eenvoudig.

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

Query's uitvoeren op digitale tweelingen

Voer een query uit op het Azure Digital Twins-exemplaar voor digitale tweelingen met behulp van de Azure Digital Twins Query Store-lanaguage. Query-aanroepen ondersteunen paging. Hier volgt een voorbeeld van het uitvoeren van query's op digitale dubbels en het herhalen van de resultaten.

Houd er rekening mee dat er een vertraging kan zijn tussen voordat wijzigingen in uw exemplaar worden doorgevoerd in query's. Zie (/azure/digital-twins/how-to-query-graph#query-limitations) voor meer informatie over querybeperkingen.

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

Digitale dubbels verwijderen

Verwijder een digitale dubbel door de id van een digitale dubbel op te geven, zoals hieronder.

service_client.delete_digital_twin(digital_twin_id)

Digitale dubbelonderdelen ophalen en bijwerken

Digitale dubbelonderdelen bijwerken

Als u een onderdeel wilt bijwerken of met andere woorden een onderdeeleigenschap of subeigenschap in Digital Twin wilt vervangen, verwijderen en/of toevoegen, hebt u de id van een digitale dubbel, onderdeelnaam en toepassings-/json-patch+json-bewerkingen nodig die moeten worden uitgevoerd op het opgegeven onderdeel van de digitale dubbel. Hier volgt de voorbeeldcode voor hoe u dit doet.

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

Digitale dubbelonderdelen ophalen

Haal een onderdeel op door de naam op te geven van een onderdeel en de id van de digitale dubbel waartoe het behoort.

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

Digitale dubbelrelaties maken en weergeven

Digitale dubbelrelaties maken

upsert_relationship maakt een relatie op een digitale dubbel met de id van een digitale dubbel, de naam van de relatie zoals 'contains', de id van een relatie zoals 'FloorContainsRoom' en een toepassings-/json-relatie die moet worden gemaakt. Moet de eigenschap bevatten met de sleutel '$targetId' om het doel van de relatie op te geven. Voorbeelden van nettoladingen voor relaties vindt u 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
    )

Digitale dubbelrelaties weergeven

list_relationships en list_incoming_relationships geeft een lijst weer van alle relaties en alle binnenkomende relaties van een digitale dubbel.

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)

Gebeurtenisroutes van digitale dubbels maken, weergeven en verwijderen

Gebeurtenisroutes maken

Als u een gebeurtenisroute wilt maken, geeft u een id op van een gebeurtenisroute zoals 'myEventRouteId' en gegevens van de gebeurtenisroute die het eindpunt en het optionele filter bevatten, zoals in het onderstaande voorbeeld.

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)

Zie de documentatie 'Routes beheren' voor filter gebeurtenissen voor meer informatie over de filtertaal voor gebeurtenisroute.

Gebeurtenisroutes weergeven

Vermeld een specifieke gebeurtenisroute opgegeven gebeurtenisroute-id of alle instellingsopties voor gebeurtenisroutes met list_event_routes.

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

Gebeurtenisroutes verwijderen

Verwijder een gebeurtenisroute opgegeven gebeurtenisroute-id.

service_client.delete_event_route(event_route_id)

Telemetrieberichten voor een digitale dubbel publiceren

Als u een telemetriebericht voor een digitale dubbel wilt publiceren, moet u de id van de digitale dubbel opgeven, samen met de nettolading waarvoor de telemetrie moet worden bijgewerkt.

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

U kunt ook een telemetriebericht publiceren voor een specifiek onderdeel in een digitale dubbel. Naast de id en nettolading van de digitale dubbel moet u de doelonderdeel-id opgeven.

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
)

Problemen oplossen

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable trefwoordargument:

Logboekregistratie op clientniveau

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)

Logboekregistratie op bewerkingsniveau

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)

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de referentiedocumentatie voor Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Volgende stappen

Feedback geven

Als u fouten tegenkomt of suggesties hebt, opent u een probleem.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.