Bibliothèque cliente azure IoT Models Repository pour Python - version 1.0.0a20220330001

  • Article

La bibliothèque de référentiels de modèles Azure IoT pour Python fournit des fonctionnalités permettant d’utiliser le référentiel de modèles Azure IoT

Prise en main

Installer le package

Installez la bibliothèque azure IoT Models Repository pour Python avec pip :

pip install azure-iot-modelsrepository

Prérequis

  • Un référentiel de modèles suivant les conventions Azure IoT
    • Le référentiel de modèles peut être hébergé sur le système de fichiers local ou hébergé sur un serveur web
    • Azure IoT héberge le référentiel de modèles Azure IoT global que le client utilisera si aucun emplacement personnalisé n’est fourni

Publication de modèles

Suivez le guide pour publier des modèles dans le référentiel de modèles Azure IoT global.

Si vous utilisez un dépôt local ou distant personnalisé, vous pouvez simplement ajouter vos fichiers de modèle à une structure de répertoires à l’emplacement du dépôt, par exemple. dtmi/com/example/thermostat-1.json

Authentification

Actuellement, aucun mécanisme d’authentification n’est pris en charge. Le point de terminaison global n’est pas lié à un abonnement Azure et ne prend pas en charge l’authentification. Tous les modèles publiés sont destinés à une consommation publique anonyme.

Concepts clés

Le référentiel de modèles Azure IoT permet aux générateurs de gérer et de partager des modèles de jumeau numérique. Les modèles sont des documents JSON-LD définis à l’aide du langage DTDL (Digital Twins Definition Language).

Le référentiel définit un modèle pour stocker les interfaces DTDL dans une structure de répertoires basée sur l’identificateur de modèle de jumeau numérique (DTMI). Vous pouvez localiser une interface dans le référentiel en convertissant le DTMI en chemin relatif. Par exemple, le DTMI dtmi:com:example:Thermostat;1 se traduit /dtmi/com/example/thermostat-1.jsonen .

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant les tâches courantes du référentiel de modèles :

Initialisation de ModelsRepositoryClient

Emplacement du dépôt

Lorsqu’aucun emplacement de dépôt n’est fourni pendant l’instanciation, le point de terminaison global du référentiel Azure IoT Models (https://devicemodels.azure.com/) est utilisé

client = ModelsRepositoryClient()

Vous pouvez également fournir un emplacement personnalisé pour l’emplacement de votre dépôt via le mot clé facultatif repository_location . Le client accepte les formats d’emplacement suivants :

  • URL web , par exemple "https://contoso.com/models/"
  • URI du système de fichiers local, par exemple "file:///path/to/repository/"
  • Chemin de fichier POSIX , par exemple "/path/to/repository/"
  • Chemin de fichier de la lettre de lecteur , par exemple "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Mode résolution des dépendances

Le client peut être configuré avec un mode facultatif dependency_resolution lors de l’instanciation, à l’aide de l’une des valeurs suivantes :

  • 'disabled' - Le client ne résout pas les dépendances du modèle
  • 'enabled' - Le client résout toutes les dépendances de modèle
  • 'tryFromExpanded' - Le client tente de résoudre les modèles à l’aide d’une définition de modèle développée (revenir au 'enabled' mode si ce n’est pas possible)
client = ModelsRepositoryClient(dependency_resolution="enabled")

Si le dependency_resolution mode n’est pas spécifié :

  • Les clients configurés pour le point de terminaison global du référentiel De modèles Azure IoT seront par défaut à l’aide de 'tryFromExpanded'
  • Les clients configurés pour un emplacement personnalisé (distant ou local) utilisent par défaut l’utilisation 'enabled'

Options supplémentaires

Si vous devez remplacer le comportement de pipeline par défaut à partir de la bibliothèque azure-core, vous pouvez fournir différents arguments de mot clé lors de l’instanciation.

Nettoyage du client

Lorsque vous avez terminé avec votre client, veillez à appeler .close() afin de libérer des ressources

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

Afin d’éviter d’avoir à le faire, il est recommandé d’utiliser votre client à partir d’un gestionnaire de contexte chaque fois que possible, qui se ferme automatiquement pour vous

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient - Obtenir des modèles

Notez que vous devez d’abord publier des dans votre référentiel avant de pouvoir les extraire. Les exemples suivants supposent que vous utilisez le référentiel de modèles Azure IoT global.

L’appel .get_models() extrait le modèle à l’adresse DTMI fournie et potentiellement ses dépendances (en fonction du mode de résolution des dépendances). Il retourne un dict qui mappe les DTMIs aux définitions de modèle.

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

Si vous fournissez plusieurs DTMIs à la méthode, vous pouvez récupérer plusieurs modèles (et potentiellement leurs dépendances) à la fois

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

Par défaut, le client utilise le mode de résolution des avec lequel il a été configuré lors de l’instanciation lors de la récupération des modèles. Toutefois, ce comportement peut être remplacé en transmettant l’une des options valides dans en tant qu’argument de mot clé facultatif à .get_models()

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

DTMI Conventions

Le package contient un module appelé dtmi_conventions, qui, lorsqu’il est importé, fournit une série d’opérations utilitaires permettant d’utiliser des DTMIs

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

Résolution des problèmes

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au DEBUG niveau.

Exceptions

Les API de référentiel de modèles peuvent déclencher des exceptions définies dans azure-core.

En outre, ils peuvent déclencher des exceptions définies dans :azure-iot-modelsrepository

  • ModelError - Indique qu’une erreur s’est produite lors de la tentative d’analyse/résolution d’une définition de modèle. Cela signifie généralement qu’il existe un modèle mal formé qui n’est pas conforme à la spécification DTDL du modèle

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème.

Étapes suivantes

Exemples

Des exemples supplémentaires sont disponibles dans le référentiel d’exemples.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.