Udostępnij za pośrednictwem

Biblioteka klienta repozytorium modeli Usługi Azure IoT dla języka Python — wersja 1.0.0a20220330001

  • Artykuł

Biblioteka repozytorium modeli usługi Azure IoT dla języka Python udostępnia funkcje pracy z repozytorium modeli usługi Azure IoT

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę repozytorium azure IoT Models dla języka Python przy użyciu narzędzia pip:

pip install azure-iot-modelsrepository

Wymagania wstępne

Publikowanie modeli

Postępuj zgodnie z przewodnikiem , aby opublikować modele w globalnym repozytorium modeli usługi Azure IoT.

Jeśli używasz niestandardowego repozytorium lokalnego lub zdalnego, możesz po prostu dodać pliki modelu do struktury katalogów w lokalizacji repozytorium, np. dtmi/com/example/thermostat-1.json

Authentication

Obecnie nie są obsługiwane żadne mechanizmy uwierzytelniania. Globalny punkt końcowy nie jest powiązany z subskrypcją platformy Azure i nie obsługuje uwierzytelniania. Wszystkie opublikowane modele są przeznaczone do anonimowego użytku publicznego.

Kluczowe pojęcia

Repozytorium modeli usługi Azure IoT umożliwia konstruktorom zarządzanie modelami cyfrowych reprezentacji bliźniaczych i udostępnianie ich. Modele są dokumentami JSON-LD zdefiniowanymi przy użyciu języka Digital Twins Definition Language (DTDL).

Repozytorium definiuje wzorzec przechowywania interfejsów DTDL w strukturze katalogów na podstawie identyfikatora modelu cyfrowej reprezentacji bliźniaczej (DTMI). Interfejs można zlokalizować w repozytorium, konwertując dtMI na ścieżkę względną. Na przykład dtMI dtmi:com:example:Thermostat;1 tłumaczy się na /dtmi/com/example/thermostat-1.json.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących typowe zadania repozytorium modeli:

Inicjowanie elementu ModelsRepositoryClient

Lokalizacja repozytorium

Jeśli podczas tworzenia wystąpienia nie zostanie podana żadna lokalizacja repozytorium, zostanie użyty globalny punkt końcowy repozytorium modeli usługi Azure IoT (https://devicemodels.azure.com/)

client = ModelsRepositoryClient()

Alternatywnie możesz podać niestandardową lokalizację, w której znajduje się repozytorium, za pomocą opcjonalnego repository_location słowa kluczowego. Klient akceptuje następujące formaty lokalizacji:

  • Adres URL sieci Web — np. "https://contoso.com/models/"
  • Lokalny identyfikator URI systemu plików — np. "file:///path/to/repository/"
  • Ścieżka pliku POSIX — np. "/path/to/repository/"
  • Ścieżka pliku litery dysku — np. "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Tryb rozpoznawania zależności

Klient można skonfigurować przy użyciu trybu opcjonalnego dependency_resolution podczas tworzenia wystąpienia przy użyciu jednej z następujących wartości:

  • 'disabled' — Klient nie rozwiąże zależności modelu
  • 'enabled' — Klient rozpozna wszystkie zależności modelu
  • 'tryFromExpanded' — Klient podejmie próbę rozwiązania modeli przy użyciu rozszerzonej definicji modelu (jeśli 'enabled' nie jest to możliwe)
client = ModelsRepositoryClient(dependency_resolution="enabled")

dependency_resolution Jeśli tryb nie jest określony:

  • Klienci skonfigurowani dla globalnego punktu końcowego repozytorium usługi Azure IoT Models domyślnie będą używać polecenia 'tryFromExpanded'
  • Klienci skonfigurowani dla lokalizacji niestandardowej (zdalnej lub lokalnej) będą domyślnie używać 'enabled'

Opcje dodatkowe

Jeśli musisz zastąpić domyślne zachowanie potoku z biblioteki azure-core, możesz podać różne argumenty słów kluczowych podczas tworzenia wystąpienia.

Oczyszczanie klienta

Po zakończeniu pracy z klientem upewnij się, że wywołaj polecenie .close() w celu zwolnienia zasobów

client = ModelsRepositoryClient()
# Do things
client.close()

Aby uniknąć konieczności tego wykonania, zaleca się użycie klienta z poziomu menedżera kontekstu, gdy jest to możliwe, co spowoduje automatyczne zamknięcie

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient — pobieranie modeli

Pamiętaj, że przed ich pobraniem należy najpierw opublikować w repozytorium. W poniższych przykładach założono, że używasz globalnego repozytorium modeli usługi Azure IoT.

Wywołanie .get_models() spowoduje pobranie modelu w podanym dtMI i potencjalnie jego zależności (w zależności od trybu rozpoznawania zależności). Zwróci element mapujący dict jednostki DTMI na definicje modelu.

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient() as client:
    models = get_models(dtmi)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

Jeśli do metody podasz wiele identyfikatorów DTMI, możesz pobrać wiele modeli (i potencjalnie ich zależności) jednocześnie

dtmis = ["dtmi:com:example:TemperatureController;1", "dtmi:com:example:azuresphere:sampledevice;1"]
with ModelsRepositoryClient() as client:
    models = get_models(dtmis)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

Domyślnie klient będzie używać niezależnie od , z którym został skonfigurowany przy wystąpieniu podczas pobierania modeli. To zachowanie można jednak zastąpić, przekazując dowolną z prawidłowych opcji jako opcjonalny argument słowa kluczowego do .get_models()

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient(dependency_resolution="disabled") as client:
    models = get_models(dtmi, dependency_resolution="enabled")

Konwencje DTMI

Pakiet zawiera moduł o nazwie dtmi_conventions, który po zaimportowaniu zapewnia serię operacji narzędziowych do pracy z jednostkami DTMI

# Returns True - this is a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat;1")

# Returns False - this is NOT a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat")

dtmi = "dtmi:com:example:Thermostat;1"

# Local repository example
repo_uri = "file:///path/to/repository"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.expanded.json"

# Remote repository example
repo_uri = "https://contoso.com/models/"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.expanded.json"

Rozwiązywanie problemów

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na DEBUG poziomie.

Wyjątki

Interfejsy API repozytorium modeli mogą zgłaszać wyjątki zdefiniowane w usłudze azure-core.

Ponadto mogą zgłaszać wyjątki zdefiniowane w elemecie azure-iot-modelsrepository:

  • ModelError — Wskazuje, że wystąpił błąd podczas próby przeanalizowania/rozwiązania definicji modelu. Zazwyczaj oznacza to, że istnieje źle sformułowany model, który nie jest zgodny ze specyfikacją DTDL modelu

Przekazywanie opinii

Jeśli wystąpią usterki lub masz sugestie, otwórz problem.

Następne kroki

Przykłady

Dodatkowe przykłady są dostępne w repozytorium przykładów.

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.