Share via

Klientbibliotek för Azure IoT-modeller för Python – version 1.0.0a20220330001

  • Artikel

Lagringsbiblioteket för Azure IoT-modeller för Python innehåller funktioner för att arbeta med Lagringsplatsen för Azure IoT-modeller

Komma igång

Installera paket

Installera Azure IoT Models Repository-biblioteket för Python med pip:

pip install azure-iot-modelsrepository

Förutsättningar

Publicera modeller

Följ guiden för att publicera modeller till den globala Lagringsplatsen för Azure IoT-modeller.

Om du använder en anpassad lokal lagringsplats eller fjärrlagringsplats kan du helt enkelt lägga till dina modellfiler i en katalogstruktur på lagringsplatsen, t.ex. dtmi/com/example/thermostat-1.json

Autentisering

För närvarande stöds inga autentiseringsmekanismer. Den globala slutpunkten är inte kopplad till en Azure-prenumeration och stöder inte autentisering. Alla publicerade modeller är avsedda för anonym offentlig konsumtion.

Viktiga begrepp

Lagringsplatsen för Azure IoT-modeller gör det möjligt för byggare att hantera och dela modeller med digitala tvillingar. Modellerna är JSON-LD-dokument som definieras med Digital Twins Definition Language (DTDL).

Lagringsplatsen definierar ett mönster för att lagra DTDL-gränssnitt i en katalogstruktur baserat på DTMI (Digital Twin Model Identifier). Du kan hitta ett gränssnitt på lagringsplatsen genom att konvertera DTMI till en relativ sökväg. DTMI dtmi:com:example:Thermostat;1 översätts till exempel till /dtmi/com/example/thermostat-1.json.

Exempel

Följande avsnitt innehåller flera kodfragment som omfattar vanliga uppgifter för modelllagringsplatsen:

Initiera ModelsRepositoryClient

Lagringsplats

När ingen lagringsplats anges under instansiering används den globala slutpunkten för Azure IoT-modellers lagringsplats (https://devicemodels.azure.com/)

client = ModelsRepositoryClient()

Du kan också ange en anpassad plats där lagringsplatsen finns via det valfria repository_location nyckelordet . Klienten accepterar följande platsformat:

  • Webb-URL – t.ex. "https://contoso.com/models/"
  • URI för lokalt filsystem – t.ex. "file:///path/to/repository/"
  • POSIX-filsökväg – t.ex. "/path/to/repository/"
  • Filsökväg för enhetsbeteckning – t.ex. "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Beroendematchningsläge

Klienten kan konfigureras med ett valfritt dependency_resolution läge vid instansiering med något av följande värden:

  • 'disabled' – Klienten löser inte modellberoenden
  • 'enabled' – Klienten löser eventuella modellberoenden
  • 'tryFromExpanded' – Klienten försöker lösa modeller med hjälp av en utökad modelldefinition (återgår 'enabled' till läget om det inte är möjligt)
client = ModelsRepositoryClient(dependency_resolution="enabled")

Om läget dependency_resolution inte har angetts:

  • Klienter som konfigurerats för den globala slutpunkten för Azure IoT-modellers lagringsplats använder som standard 'tryFromExpanded'
  • Klienter som konfigurerats för en anpassad plats (fjärransluten eller lokal) använder som standard 'enabled'

Ytterligare alternativ

Om du behöver åsidosätta standardbeteendet för pipelinen från azure-core-biblioteket kan du ange olika nyckelordsargument under instansieringen.

Klientrensning

När du är klar med klienten måste du anropa .close() för att frigöra resurser

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

För att undvika att behöva göra detta rekommenderar vi att du använder klienten inifrån en kontexthanterare när det är möjligt, vilket stängs automatiskt åt dig

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient – Hämta modeller

Observera att du först måste på lagringsplatsen innan du kan hämta dem. I följande exempel förutsätter vi att du använder den globala lagringsplatsen för Azure IoT-modeller.

Anrop .get_models() hämtar modellen vid angivet DTMI och eventuellt dess beroenden (beroende på beroendematchningsläget). Den returnerar en dict som mappar DTMC:er till modelldefinitioner.

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

Om du anger flera DTM:er till metoden kan du hämta flera modeller (och eventuellt deras beroenden) samtidigt

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

Som standard använder klienten beroendematchningsläge som den konfigurerades med vid instansiering när modeller hämtades. Det här beteendet kan dock åsidosättas genom att skicka något av de giltiga alternativen i som ett valfritt nyckelordsargument till .get_models()

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

DTMI-konventioner

Paketet innehåller en modul med namnet dtmi_conventions, som när den importeras innehåller en serie verktygsåtgärder för att arbeta med DTMC:er

# 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"

Felsökning

Loggning

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

Undantag

API:er för modelllagringsplats kan generera undantag som definierats i azure-core.

Dessutom kan de generera undantag som definierats i azure-iot-modelsrepository:

  • ModelError – Anger att ett fel uppstod vid försök att parsa/lösa en modelldefinition. Detta innebär vanligtvis att det finns en felaktig modell som inte uppfyller modellens DTDL-specifikation

Ge feedback

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

Nästa steg

Exempel

Ytterligare exempel finns på lagringsplatsen för exempel.

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.