Sdílet prostřednictvím

Klientská knihovna úložiště Azure IoT Models pro Python – verze 1.0.0a20220330001

  • Článek

Knihovna úložiště Azure IoT Models pro Python poskytuje funkce pro práci s úložištěm modelů Azure IoT.

Začínáme

Nainstalovat balíček

Nainstalujte knihovnu úložiště Azure IoT Models pro Python pomocí pip:

pip install azure-iot-modelsrepository

Požadavky

  • Úložiště modelů podle konvencí Azure IoT
    • Úložiště modelů může být hostované v místním systému souborů nebo hostované na webovém serveru.
    • Azure IoT je hostitelem globálního úložiště modelů Azure IoT, které bude klient používat, pokud není k dispozici žádné vlastní umístění.

Modely publikování

Postupujte podle průvodce publikováním modelů do globálního úložiště modelů Azure IoT.

Pokud používáte vlastní místní nebo vzdálené úložiště, můžete jednoduše přidat soubory modelu do adresářové struktury v umístění úložiště, např. dtmi/com/example/thermostat-1.json

Authentication

V současné době nejsou podporovány žádné mechanismy ověřování. Globální koncový bod není vázaný na předplatné Azure a nepodporuje ověřování. Všechny publikované modely jsou určené k anonymnímu veřejnému používání.

Klíčové koncepty

Úložiště modelů Azure IoT umožňuje tvůrcům spravovat a sdílet modely digitálních dvojčat. Modely jsou dokumenty JSON-LD definované pomocí jazyka DTDL (Digital Twins Definition Language).

Úložiště definuje vzor pro ukládání rozhraní DTDL do adresářové struktury založené na identifikátoru modelu DTMI (Digital Twin Model Identifier). Rozhraní v úložišti můžete najít převodem DTMI na relativní cestu. Například DTMI dtmi:com:example:Thermostat;1 se přeloží na /dtmi/com/example/thermostat-1.json.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají běžné úlohy úložiště modelů:

Inicializace modelsRepositoryClient

Umístění úložiště

Pokud během vytváření instance není zadané žádné umístění úložiště, použije se globální koncový bod úložiště Azure IoT Models (https://devicemodels.azure.com/).

client = ModelsRepositoryClient()

Alternativně můžete prostřednictvím volitelného repository_location klíčového slova zadat vlastní umístění, kde se vaše úložiště nachází. Klient přijímá následující formáty umístění:

  • Adresa URL webu – např. "https://contoso.com/models/"
  • Identifikátor URI místního systému souborů – např. "file:///path/to/repository/"
  • Cesta k souboru POSIX – např. "/path/to/repository/"
  • Cesta k souboru s písmenem jednotky – např. "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Režim řešení závislostí

Klienta je možné nakonfigurovat s volitelným dependency_resolution režimem při vytváření instance pomocí jedné z následujících hodnot:

  • 'disabled' – Klient nepřeloží závislosti modelu.
  • 'enabled' – Klient vyřeší všechny závislosti modelu.
  • 'tryFromExpanded' – Klient se pokusí přeložit modely pomocí rozšířené definice modelu (pokud není možné, vrátí se zpět do 'enabled' režimu).
client = ModelsRepositoryClient(dependency_resolution="enabled")

dependency_resolution Pokud režim není zadaný:

  • Klienti nakonfigurovaní pro globální koncový bod úložiště Azure IoT Models budou ve výchozím nastavení používat 'tryFromExpanded'
  • Klienti nakonfigurovaní pro vlastní umístění (vzdálené nebo místní) budou ve výchozím nastavení používat 'enabled'

Další možnosti

Pokud potřebujete přepsat výchozí chování kanálu z knihovny azure-core, můžete během vytváření instance zadat různé argumenty s klíčovými slovy .

Vyčištění klienta

Po dokončení práce s klientem nezapomeňte zavolat .close() , abyste uvolnili prostředky.

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

Abyste se tomu vyhnuli, doporučujeme, abyste kdykoli je to možné, používali klienta z kontextového správce, který se pro vás automaticky uzavře.

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient – získání modelů

Mějte na paměti, že před jejich načtením musíte nejprve publikovat modely modelů do úložiště. Následující příklady předpokládají, že používáte globální úložiště modelů Azure IoT.

Volání .get_models() načte model na zadaném rozhraní DTMI a potenciálně i jeho závislosti (v závislosti na režimu rozlišení závislostí). Vrátí hodnotu , dict která mapuje rozhraní DTMI na definice modelu.

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

Pokud metodě poskytnete více DTMI, můžete načíst více modelů (a potenciálně jejich závislosti) najednou.

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

Ve výchozím nastavení klient při načítání modelů použije režim rozlišení závislostí závislostí, se kterým byl nakonfigurován při vytváření instance. Toto chování však lze přepsat předáním libovolné z platných možností v souboru jako volitelného argumentu klíčového slova do .get_models()

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

Konvence DTMI

Balíček obsahuje modul s názvem dtmi_conventions, který při importu poskytuje řadu pomocných operací pro práci s 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"

Poradce při potížích

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na DEBUG úrovni.

Výjimky

Rozhraní API úložiště modelů můžou vyvolávat výjimky definované v Azure-Core.

Kromě toho mohou vyvolat výjimky definované v :azure-iot-modelsrepository

  • ModelError – Označuje, že při pokusu o analýzu nebo vyřešení definice modelu došlo k chybě. Obecně to znamená, že existuje poškozený model, který nevyhovuje specifikaci modelu DTDL.

Zadání zpětné vazby

Pokud narazíte na chyby nebo máte návrhy, otevřete problém.

Další kroky

Ukázky

Další ukázky jsou k dispozici v úložišti ukázek.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.