Azure IoT Models Repository-Clientbibliothek für Python – Version 1.0.0a2020330001
Die Repositorybibliothek für Azure IoT-Modelle für Python bietet Funktionen für die Arbeit mit dem Repository für Azure IoT-Modelle.
Erste Schritte
Paket installieren
Installieren Sie die Repositorybibliothek von Azure IoT Models für Python mit pip:
pip install azure-iot-modelsrepository
Voraussetzungen
- Ein Modellrepository nach Azure IoT-Konventionen
- Das Modellrepository kann im lokalen Dateisystem gehostet oder auf einem Webserver gehostet werden.
- Azure IoT hostet das globale Azure IoT-Modellrepository , das der Client verwendet, wenn kein benutzerdefinierter Speicherort angegeben wird.
Veröffentlichen von Modellen
Befolgen Sie die Anleitung zum Veröffentlichen von Modellen im globalen Azure IoT-Modellrepository.
Wenn Sie ein benutzerdefiniertes lokales Oder Remoterepository verwenden, können Sie Ihre Modelldateien einfach einer Verzeichnisstruktur im Repositoryspeicherort hinzufügen, z. B. dtmi/com/example/thermostat-1.json
Authentifizierung
Derzeit werden keine Authentifizierungsmechanismen unterstützt. Der globale Endpunkt ist nicht an ein Azure-Abonnement gebunden und unterstützt keine Authentifizierung. Alle veröffentlichten Modelle sind für den anonymen öffentlichen Verbrauch bestimmt.
Wichtige Begriffe
Das Azure IoT Models-Repository ermöglicht Es Buildern, Modelle für digitale Zwillinge zu verwalten und gemeinsam zu nutzen. Bei den Modellen handelt es sich um JSON-LD-Dokumente , die mit der Digital Twins Definition Language (DTDL) definiert werden.
Das Repository definiert ein Muster zum Speichern von DTDL-Schnittstellen in einer Verzeichnisstruktur basierend auf dem Digital Twin Model Identifier (DTMI). Sie können eine Schnittstelle im Repository suchen, indem Sie den DTMI in einen relativen Pfad konvertieren. Der DTMI dtmi:com:example:Thermostat;1 übersetzt z. B. in /dtmi/com/example/thermostat-1.json.
Beispiele
Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die allgemeine Aufgaben des Modellrepositorys behandeln:
Initialisieren des ModelsRepositoryClient
Repositoryspeicherort
Wenn während der Instanziierung kein Repositoryspeicherort angegeben wird, wird der globale Endpunkt des Azure IoT Models-Repositorys () verwendet.https://devicemodels.azure.com/
client = ModelsRepositoryClient()
Alternativ können Sie über das optionale repository_location Schlüsselwort einen benutzerdefinierten Speicherort für das Repository angeben. Der Client akzeptiert die folgenden Speicherortformate:
- Web-URL – z. B.
"https://contoso.com/models/" - Lokaler Dateisystem-URI– z. B.
"file:///path/to/repository/" - POSIX-Dateipfad – z. B.
"/path/to/repository/" - Laufwerkbuchstabendateipfad – z. B.
"C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")
Abhängigkeitsauflösungsmodus
Der Client kann mit einem optionalen dependency_resolution Modus bei der Instanziierung konfiguriert werden, wobei einer der folgenden Werte verwendet wird:
'disabled'– Der Client löst keine Modellabhängigkeiten auf.'enabled'– Der Client löst alle Modellabhängigkeiten auf.'tryFromExpanded'– Der Client versucht, Modelle mithilfe einer erweiterten Modelldefinition aufzulösen (falls'enabled'nicht möglich)
client = ModelsRepositoryClient(dependency_resolution="enabled")
Wenn der dependency_resolution Modus nicht angegeben ist:
- Clients, die für den globalen Endpunkt des Azure IoT Models-Repositorys konfiguriert sind, verwenden standardmäßig
'tryFromExpanded' - Clients, die für einen benutzerdefinierten Standort (remote oder lokal) konfiguriert sind, verwenden standardmäßig die Verwendung
'enabled'
Zusätzliche Optionen
Wenn Sie das Standardpipelineverhalten aus der azure-core-Bibliothek außer Kraft setzen müssen, können Sie während der Instanziierung verschiedene Schlüsselwortargumente bereitstellen.
Clientbereinigung
Wenn Sie mit Ihrem Client fertig sind, rufen Sie auf .close() , um Ressourcen freizugeben.
client = ModelsRepositoryClient()
# Do things
client.close()
Um dies zu vermeiden, empfiehlt es sich, ihren Client nach Möglichkeit innerhalb eines Kontext-Managers zu verwenden, der automatisch für Sie geschlossen wird.
with ModelsRepositoryClient() as client:
# Do things
ModelsRepositoryClient – Modelle abrufen
Beachten Sie, dass Sie modelle zuerst in Ihrem Repository veröffentlichen müssen, bevor Sie sie abrufen können. In den folgenden Beispielen wird davon ausgegangen, dass Sie das globale Azure IoT Models-Repository verwenden.
Beim Aufrufen .get_models() wird das Modell am bereitgestellten DTMI und möglicherweise dessen Abhängigkeiten (abhängig vom Abhängigkeitsauflösungsmodus) abgerufen. Es wird ein dict zurückgegeben, das DTMIs Modelldefinitionen zuordnet.
dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient() as client:
models = get_models(dtmi)
print("{} resolved in {} interfaces".format(dtmi, len(models)))
Wenn Sie mehrere DTMIs für die -Methode bereitstellen, können Sie mehrere Modelle (und möglicherweise deren Abhängigkeiten) gleichzeitig abrufen.
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)))
Standardmäßig verwendet der Client den , mit dem er beim Abrufen von Modellen bei der Instanziierung konfiguriert wurde. Dieses Verhalten kann jedoch überschrieben werden, indem eine der gültigen Optionen als optionales Schlüsselwortargument an übergeben wird. .get_models()
dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient(dependency_resolution="disabled") as client:
models = get_models(dtmi, dependency_resolution="enabled")
DTMI-Konventionen
Das Paket enthält ein Modul namens dtmi_conventions, das beim Import eine Reihe von Hilfsprogrammvorgängen für die Arbeit mit DTMIs bereitstellt.
# 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"
Problembehandlung
Protokollierung
Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf Ebene DEBUG protokolliert.
Ausnahmen
Modellrepository-APIs können ausnahmen auslösen, die in azure-core definiert sind.
Darüber hinaus können sie Ausnahmen auslösen, die azure-iot-modelsrepositoryin definiert sind:
ModelError– Gibt einen Fehler an, der beim Analysieren/Auflösen einer Modelldefinition aufgetreten ist. Dies bedeutet im Allgemeinen, dass es ein falsch formatiertes Modell gibt, das nicht der DTDL-Spezifikation des Modells entspricht.
Feedback geben
Wenn Fehler auftreten oder wenn Sie Vorschläge haben, erstellen Sie ein Problem.
Nächste Schritte
Beispiele
Weitere Beispiele sind im Beispielrepository verfügbar.
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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für