Biblioteka klienta usługi Azure Digital Twins Core dla języka Python — wersja 1.2.0
Ten pakiet zawiera zestaw SDK dla interfejsu API usługi Azure Digital Twins w celu zapewnienia dostępu do usługi Azure Digital Twins na potrzeby zarządzania bliźniaczymi reprezentacjami, modelami, relacjami itp.
Zrzeczenie odpowiedzialności
Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691
Wprowadzenie
Wprowadzenie
Azure Digital Twins to platforma deweloperów dla rozwiązań IoT nowej generacji, która umożliwia tworzenie, uruchamianie i zarządzanie reprezentacjami cyfrowymi środowiska biznesowego, bezpieczne i wydajne w chmurze. Dzięki usłudze Azure Digital Twins tworzenie reprezentacji stanu operacyjnego na żywo jest szybkie i ekonomiczne, a reprezentacje cyfrowe pozostają aktualne przy użyciu danych w czasie rzeczywistym z IoT i innych źródeł danych. Jeśli dopiero zaczynasz korzystać z usługi Azure Digital Twins i chcesz dowiedzieć się więcej na temat platformy, zapoznaj się z oficjalną stroną dokumentacji usługi Azure Digital Twins.
Aby zapoznać się z wprowadzeniem do programowania w usłudze Azure Digital Twins, odwiedź stronę samouczka kodowania , aby uzyskać łatwy przewodnik krok po kroku. Odwiedź ten samouczek , aby dowiedzieć się, jak korzystać z wystąpienia usługi Azure Digital Twin przy użyciu aplikacji klienckiej wiersza polecenia. Na koniec, aby uzyskać szybki przewodnik po tworzeniu kompleksowego rozwiązania usługi Azure Digital Twins opartego na danych na żywo ze środowiska, upewnij się, że zapoznasz się z tym pomocnym przewodnikiem.
Przewodniki wymienione powyżej mogą ułatwić rozpoczęcie pracy z kluczowymi elementami usługi Azure Digital Twins, takimi jak tworzenie wystąpień usługi Azure Digital Twins, modeli, grafów bliźniaczych itp. Skorzystaj z poniższego przewodnika przykładowego, aby zapoznać się z różnymi interfejsami API, które ułatwiają programowanie w usłudze Azure Digital Twins.
Jak zainstalować
Zainstaluj usługę [azure-digitaltwins-core][pypi_package_keys] i azure-identity przy użyciu narzędzia pip:
pip install azure-digitaltwins-core azure-identity
usługa azure-identity jest używana do uwierzytelniania usługi Azure Active Directory, jak pokazano poniżej.
Sposób użycia
Uwierzytelnianie, uprawnienie
Aby utworzyć nowego klienta usługi Digital Twins, potrzebny jest punkt końcowy do wystąpienia i poświadczeń usługi Azure Digital Twin.
W poniższych przykładach AZURE_URLnależy ustawić zmienne środowiskowe , AZURE_TENANT_ID, AZURE_CLIENT_IDi AZURE_CLIENT_SECRET .
Klient wymaga wystąpienia tokenuCredential lub ServiceClientCredentials.
W tych przykładach pokazano, jak używać jednej klasy pochodnej: DefaultAzureCredentials.
Uwaga: aby uzyskać dostęp do płaszczyzny danych dla usługi Digital Twins, jednostka musi mieć uprawnienia. W tym celu użyj polecenia interfejsu wiersza polecenia platformy Azure:
az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'
Wartość domyślnaAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń oparty na środowisku, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.
Przykładowy kod
# 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)
Kluczowe pojęcia
Azure Digital Twins to usługa IoT platformy Azure, która umożliwia tworzenie kompleksowych modeli środowiska fizycznego. Umożliwia ona tworzenie grafów analizy przestrzennej do modelowania relacji i interakcji między osobami, obszarami i urządzeniami. Więcej informacji na temat usługi Azure Digital Twins można uzyskać, odwiedzając dokumentację usługi Azure Digital Twins.
Przykłady
Interfejsy API cyfrowych reprezentacji bliźniaczych (przy użyciu biblioteki klienta) można eksplorować przy użyciu projektu przykładów.
W projekcie przykładów przedstawiono następujące kwestie:
- Tworzenie wystąpienia klienta
- Tworzenie, pobieranie i likwidowanie modeli
- Tworzenie, wykonywanie zapytań i usuwanie cyfrowej reprezentacji bliźniaczej
- Pobieranie i aktualizowanie składników cyfrowej reprezentacji bliźniaczej
- Tworzenie, pobieranie i usuwanie relacji między bliźniaczymi reprezentacjami cyfrowymi
- Tworzenie, pobieranie i usuwanie tras zdarzeń dla cyfrowej reprezentacji bliźniaczej
- Publikowanie komunikatów telemetrycznych w składniku cyfrowej reprezentacji bliźniaczej i cyfrowej reprezentacji bliźniaczej
Tworzenie, wyświetlanie listy, likwidowanie i usuwanie modeli
Tworzenie modeli
Utwórzmy modele przy użyciu poniższego kodu. Musisz przekazać tablicę zawierającą listę modeli.
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)
Wyświetlanie listy modeli
Pobieranie wszystkich utworzonych modeli przy użyciu polecenia list_models
listed_models = service_client.list_models()
for model in listed_models:
print(model)
Pobieranie modelu
Użyj get_model unikatowego identyfikatora modelu, aby uzyskać określony model.
# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)
Likwiduj model
Aby dekommisować model, przekaż identyfikator modelu dla modelu, który chcesz dekommisji.
# Decommission a model
service_client.decommission_model(model_id)
Usuwanie modelu
Aby usunąć model, przekaż identyfikator modelu dla modelu, który chcesz usunąć.
# Delete a model
service_client.delete_model(model_id)
Tworzenie i usuwanie cyfrowych reprezentacji bliźniaczych
Tworzenie cyfrowych reprezentacji bliźniaczych
W przypadku tworzenia bliźniaczej reprezentacji należy podać identyfikator cyfrowej reprezentacji bliźniaczej, takiej jak my_twin i aplikacja/json digital twin na podstawie utworzonego wcześniej modelu. Przykładowa aplikacja/kod json można znaleźć tutaj.
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)
Uzyskiwanie cyfrowej reprezentacji bliźniaczej
Uzyskanie cyfrowej reprezentacji bliźniaczej jest niezwykle łatwe.
get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)
Wykonywanie zapytań dotyczących cyfrowych reprezentacji bliźniaczych
Wykonaj zapytanie dotyczące wystąpienia usługi Azure Digital Twins dla cyfrowych reprezentacji bliźniaczych przy użyciu usługi Azure Digital Twins Query Store lanaguage. Wywołania zapytań obsługują stronicowanie. Oto przykład sposobu wykonywania zapytań dotyczących cyfrowych reprezentacji bliźniaczych i iteracji wyników.
Należy pamiętać, że może wystąpić opóźnienie między zmianami w wystąpieniu, które zostaną odzwierciedlone w zapytaniach. Aby uzyskać więcej informacji na temat ograniczeń zapytań, zobacz (/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)
Usuwanie cyfrowych reprezentacji bliźniaczych
Usuń cyfrową reprezentację bliźniaczą po prostu, podając identyfikator cyfrowej reprezentacji bliźniaczej, jak pokazano poniżej.
service_client.delete_digital_twin(digital_twin_id)
Pobieranie i aktualizowanie składników cyfrowej reprezentacji bliźniaczej
Aktualizowanie składników cyfrowej reprezentacji bliźniaczej
Aby zaktualizować składnik lub innymi słowy, usunąć i/lub dodać właściwość składnika lub podwłaściwość w usłudze Digital Twin, musisz mieć identyfikator cyfrowej reprezentacji bliźniaczej, nazwy składnika i operacji application/json-patch+json do wykonania w składniku określonej reprezentacji cyfrowej bliźniaczej. Oto przykładowy kod dotyczący tego, jak to zrobić.
component_name = "Component1"
patch = [
{
"op": "replace",
"path": "/ComponentProp1",
"value": "value2"
}
]
service_client.update_component(digital_twin_id, component_name, patch)
Pobieranie składników cyfrowej reprezentacji bliźniaczej
Pobierz składnik, podając nazwę składnika i identyfikator cyfrowej reprezentacji bliźniaczej, do której należy.
get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)
Tworzenie i wyświetlanie listy relacji cyfrowej reprezentacji bliźniaczej
Tworzenie relacji cyfrowej reprezentacji bliźniaczej
upsert_relationship Tworzy relację na cyfrowej reprezentacji bliźniaczej dostarczonej z identyfikatorem cyfrowej reprezentacji bliźniaczej, nazwy relacji, takiej jak "contains", identyfikator relacji, takiej jak "FloorContainsRoom" i relacja aplikacji/json, która ma zostać utworzona. Musi zawierać właściwość z kluczem "$targetId", aby określić element docelowy relacji. Przykładowe ładunki relacji można znaleźć tutaj.
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
)
Wyświetlanie listy relacji cyfrowej reprezentacji bliźniaczej
list_relationships i list_incoming_relationships wyświetla listę wszystkich relacji i wszystkich relacji przychodzących odpowiednio cyfrowej reprezentacji bliźniaczej.
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)
Tworzenie, wyświetlanie listy i usuwanie tras zdarzeń cyfrowych reprezentacji bliźniaczych
Tworzenie tras zdarzeń
Aby utworzyć trasę zdarzenia, podaj identyfikator trasy zdarzeń, taką jak "myEventRouteId" i dane trasy zdarzeń zawierające punkt końcowy i opcjonalny filtr, jak pokazano poniżej.
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)
Aby uzyskać więcej informacji na temat języka filtrowania tras zdarzeń, zobacz dokumentację dotyczącą zdarzeń filtru "jak zarządzać trasami".
Wyświetlanie listy tras zdarzeń
Wyświetl listę określonej trasy zdarzenia podanego identyfikatora trasy zdarzenia lub wszystkie opcje ustawiania tras zdarzeń za pomocą polecenia list_event_routes.
event_routes = service_client.list_event_routes()
for event_route in event_routes:
print(event_route)
Usuwanie tras zdarzeń
Usuń trasę zdarzenia o identyfikatorze trasy zdarzenia.
service_client.delete_event_route(event_route_id)
Publikowanie komunikatów telemetrycznych dla cyfrowej reprezentacji bliźniaczej
Aby opublikować komunikat telemetrii dla cyfrowej reprezentacji bliźniaczej, należy podać identyfikator cyfrowej reprezentacji bliźniaczej wraz z ładunkiem, na którym wymagana jest aktualizacja telemetrii.
digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
digita_twin_id,
telemetry_payload
)
Możesz również opublikować komunikat telemetryczny dla określonego składnika w cyfrowej reprezentacji bliźniaczej. Oprócz identyfikatora cyfrowej reprezentacji bliźniaczej i ładunku należy określić identyfikator składnika docelowego.
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
)
Rozwiązywanie problemów
Rejestrowanie
Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.
Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem słowa kluczowego logging_enable:
Rejestrowanie na poziomie 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)
Rejestrowanie na poziomie operacji
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)
Konfiguracja opcjonalna
Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje ponownych prób, rejestrowania, protokołów transportowych i nie tylko.
Następne kroki
Przekazywanie opinii
Jeśli wystąpią usterki lub masz sugestie, otwórz problem.
Współtworzenie
W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.
Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.
W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.
Azure SDK for Python