Share via

Azure Digital Twins Core-klientbibliotek för Python – version 1.2.0

  • Artikel

Det här paketet innehåller ett SDK för Azure Digital Twins API för att ge åtkomst till Azure Digital Twins-tjänsten för hantering av tvillingar, modeller, relationer osv.

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

Introduktion

Azure Digital Twins är en utvecklarplattform för nästa generations IoT-lösningar som gör att du kan skapa, köra och hantera digitala representationer av din företagsmiljö på ett säkert och effektivt sätt i molnet. Med Azure Digital Twins är det snabbt och kostnadseffektivt att skapa realtidsrepresentationer av drifttillstånd, och digitala representationer förblir aktuella med realtidsdata från IoT och andra datakällor. Om du inte har använt Azure Digital Twins tidigare och vill veta mer om plattformen kan du kolla in den officiella dokumentationssidan för Azure Digital Twins.

En introduktion till hur du programmerar mot Azure Digital Twins-tjänsten finns på sidan med kodningsguiden för en enkel steg-för-steg-guide. I den här självstudien får du lära dig hur du interagerar med en Azure Digital Twin-instans med hjälp av ett kommandoradsklientprogram. Om du vill ha en snabbguide om hur du skapar en Azure Digital Twins-lösning från slutpunkt till slutpunkt som drivs av realtidsdata från din miljö kan du läsa den här användbara guiden.

Guiderna som nämns ovan kan hjälpa dig att komma igång med viktiga element i Azure Digital Twins, till exempel att skapa Azure Digital Twins-instanser, modeller, tvillingdiagram osv. Använd den här exempelguiden nedan för att bekanta dig med de olika API:er som hjälper dig att programmera mot Azure Digital Twins.

Så här installerar du

Installera [azure-digitaltwins-core][pypi_package_keys] och azure-identity med pip:

pip install azure-digitaltwins-core azure-identity

azure-identity används för Azure Active Directory-autentisering enligt nedan.

Använd så här

Autentisering, behörighet

Om du vill skapa en ny Digital Twins-klient behöver du slutpunkten till en Azure Digital Twin-instans och autentiseringsuppgifter. För exemplen nedan AZURE_URLmåste miljövariablerna , AZURE_TENANT_ID, AZURE_CLIENT_IDoch AZURE_CLIENT_SECRET anges. Klienten kräver en instans av TokenCredential eller ServiceClientCredentials. I de här exemplen illustrerar vi hur du använder en härledd klass: DefaultAzureCredentials.

Obs! För att få åtkomst till dataplanet för Digital Twins-tjänsten måste entiteten ges behörighet. Det gör du genom att använda Azure CLI-kommandot: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential stöder olika autentiseringsmekanismer och avgör lämplig typ av autentiseringsuppgifter baserat på den miljö som den körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

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

Viktiga begrepp

Azure Digital Twins är en Azure IoT-tjänst som skapar omfattande modeller av den fysiska miljön. Det kan skapa diagram för spatial intelligens för att modellera relationer och interaktioner mellan människor, utrymmen och enheter. Du kan lära dig mer om Azure Digital Twins genom att gå till Dokumentation om Azure Digital Twins.

Exempel

Du kan utforska Digital Twins-API:erna (med klientbiblioteket) med hjälp av exempelprojektet.

Exempelprojektet visar följande:

  • Instansiera klienten
  • Skapa, hämta och inaktivera modeller
  • Skapa, fråga och ta bort en digital tvilling
  • Hämta och uppdatera komponenter för en digital tvilling
  • Skapa, hämta och ta bort relationer mellan digitala tvillingar
  • Skapa, hämta och ta bort händelsevägar för digital tvilling
  • Publicera telemetrimeddelanden till en komponent för digitala tvillingar och digitala tvillingar

Skapa, lista, inaktivera och ta bort modeller

Skapa modeller

Nu ska vi skapa modeller med hjälp av koden nedan. Du måste skicka en matris som innehåller en lista över modeller.

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)

Lista modeller

Använda list_models för att hämta alla skapade modeller

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

Hämta modell

Använd get_model med modellens unika identifierare för att hämta en specifik modell.

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

Inaktivera modell

Om du vill delegera en modell skickar du in ett modell-ID för den modell som du vill decommision.

# Decommission a model
service_client.decommission_model(model_id)

Ta bort modell

Om du vill ta bort en modell skickar du in ett modell-ID för den modell som du vill ta bort.

# Delete a model
service_client.delete_model(model_id)

Skapa och ta bort digitala tvillingar

Skapa digitala tvillingar

För att skapa tvilling måste du ange ID för en digital tvilling, till exempel och den digitala tvillingen application/json baserat på modellen som my_twin skapades tidigare. Du kan titta på exempelprogrammet/json här.

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)

Hämta en digital tvilling

Att få en digital tvilling är extremt enkelt.

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

Fråga digitala tvillingar

Fråga Azure Digital Twins-instansen efter digitala tvillingar med hjälp av Azure Digital Twins Query Store-lanaguage. Frågeanrop stöder sidindelning. Här är ett exempel på hur du frågar efter digitala tvillingar och hur du itererar över resultaten.

Observera att det kan uppstå en fördröjning mellan innan ändringar i din instans återspeglas i frågor. Mer information om frågebegränsningar finns i (/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)

Ta bort digitala tvillingar

Ta bort en digital tvilling genom att ange ID för en digital tvilling enligt nedan.

service_client.delete_digital_twin(digital_twin_id)

Hämta och uppdatera komponenter för digitala tvillingar

Uppdatera komponenter för digitala tvillingar

Om du vill uppdatera en komponent eller med andra ord för att ersätta, ta bort och/eller lägga till en komponentegenskap eller underegenskaper i Digital Twin, behöver du ID för en digital tvilling, komponentnamn och application/json-patch+json-åtgärder som ska utföras på den angivna digitala tvillingens komponent. Här är exempelkoden om hur du gör det.

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

Hämta komponenter för digitala tvillingar

Hämta en komponent genom att ange namnet på en komponent och ID för den digitala tvilling som den tillhör.

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

Skapa och lista digitala tvillingrelationer

Skapa digitala tvillingrelationer

upsert_relationship skapar en relation på en digital tvilling som tillhandahålls med ID för en digital tvilling, namnet på relationen, till exempel "contains", ID för en relation som "FloorContainsRoom" och en application/json-relation som ska skapas. Måste innehålla egenskapen med nyckeln "$targetId" för att ange målet för relationen. Exempelnyttolaster för relationer finns här.

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
    )

Visa en lista över digitala tvillingrelationer

list_relationships och list_incoming_relationships visar alla relationer och alla inkommande relationer för en digital tvilling.

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)

Skapa, lista och ta bort händelsevägar för digitala tvillingar

Skapa händelsevägar

Om du vill skapa en händelseväg anger du ett ID för en händelseväg, till exempel "myEventRouteId" och händelsevägsdata som innehåller slutpunkten och det valfria filtret, som i exemplet nedan.

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)

Mer information om filterspråket för händelsevägsfilter finns i filterhändelsedokumentationen "så här hanterar du vägar".

Lista händelsevägar

Ange en specifik händelseväg med angivet händelsevägs-ID eller alla inställningsalternativ för händelsevägar med list_event_routes.

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

Ta bort händelsevägar

Ta bort en händelseväg angivet händelsevägs-ID.

service_client.delete_event_route(event_route_id)

Publicera telemetrimeddelanden för en digital tvilling

Om du vill publicera ett telemetrimeddelande för en digital tvilling måste du ange ID:t för den digitala tvillingen, tillsammans med nyttolasten som telemetrin som behöver uppdateringen på.

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

Du kan också publicera ett telemetrimeddelande för en specifik komponent i en digital tvilling. Förutom digital tvilling-ID och nyttolast måste du ange målkomponent-ID:t.

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
)

Felsökning

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med nyckelordsargumentet logging_enable:

Loggning på klientnivå

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)

Loggning per åtgärdsnivå

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)

Valfri konfiguration

Valfria nyckelordsargument kan skickas in på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Nästa steg

Ge feedback

Om du stöter på buggar eller har förslag kan du öppna ett problem.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.