Compartir a través de

Biblioteca cliente del repositorio de modelos de Azure IoT para Python: versión 1.0.0a20220330001

  • Artículo

La biblioteca de repositorios de modelos de Azure IoT para Python proporciona funcionalidad para trabajar con el repositorio de modelos de Azure IoT.

Introducción

Instalación del paquete

Instale la biblioteca del repositorio de modelos de Azure IoT para Python con pip:

pip install azure-iot-modelsrepository

Requisitos previos

  • Un repositorio de modelos siguiendo las convenciones de Azure IoT
    • El repositorio de modelos se puede hospedar en el sistema de archivos local o hospedado en un servidor web.
    • Azure IoT hospeda el repositorio global de modelos de Azure IoT que usará el cliente si no se proporciona ninguna ubicación personalizada.

Modelo de publicación

Siga la guía para publicar modelos en el repositorio global de modelos de Azure IoT.

Si usa un repositorio local o remoto personalizado, simplemente puede agregar los archivos de modelo a una estructura de directorios en la ubicación del repositorio, por ejemplo. dtmi/com/example/thermostat-1.json

Authentication

Actualmente, no se admite ningún mecanismo de autenticación. El punto de conexión global no está vinculado a una suscripción de Azure y no admite la autenticación. Todos los modelos publicados están diseñados para el consumo público anónimo.

Conceptos clave

El repositorio de modelos de Azure IoT permite a los generadores administrar y compartir modelos de gemelos digitales. Los modelos son documentos JSON-LD definidos mediante el lenguaje de definición de Digital Twins (DTDL).

El repositorio define un patrón para almacenar interfaces DTDL en una estructura de directorios basada en el identificador de modelo de gemelo digital (DTMI). Para localizar una interfaz en el repositorio, convierta la DTMI en una ruta de acceso relativa. Por ejemplo, DTMI dtmi:com:example:Thermostat;1 se traduce en /dtmi/com/example/thermostat-1.json.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan tareas comunes del repositorio de modelos:

Inicialización de ModelsRepositoryClient

Ubicación del repositorio

Cuando no se proporciona ninguna ubicación del repositorio durante la creación de instancias, se usa el punto de conexión global del repositorio de modelos de Azure IoT (https://devicemodels.azure.com/)

client = ModelsRepositoryClient()

Como alternativa, puede proporcionar una ubicación personalizada para la ubicación del repositorio a través de la palabra clave opcional repository_location . El cliente acepta los siguientes formatos de ubicación:

  • Dirección URL web: por ejemplo, "https://contoso.com/models/"
  • URI del sistema de archivos local( por ejemplo, "file:///path/to/repository/"
  • Ruta de archivo POSIX, por ejemplo, "/path/to/repository/"
  • Ruta de acceso de la letra de unidad: por ejemplo, "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Modo de resolución de dependencias

El cliente se puede configurar con un modo opcional dependency_resolution en la creación de instancias mediante uno de los siguientes valores:

  • 'disabled' - El cliente no resolverá las dependencias del modelo.
  • 'enabled' - El cliente resolverá las dependencias del modelo.
  • 'tryFromExpanded' - El cliente intentará resolver los modelos mediante una definición de modelo expandida (revertir en 'enabled' modo si no es posible)
client = ModelsRepositoryClient(dependency_resolution="enabled")

Si no se especifica el dependency_resolution modo:

  • Los clientes configurados para el punto de conexión global del repositorio de modelos de Azure IoT usarán de forma predeterminada 'tryFromExpanded'
  • Los clientes configurados para una ubicación personalizada (remota o local) usarán de forma predeterminada 'enabled'

Opciones adicionales

Si necesita invalidar el comportamiento de canalización predeterminado de la biblioteca azure-core, puede proporcionar varios argumentos de palabra clave durante la creación de instancias.

Limpieza de cliente

Cuando haya terminado con el cliente, asegúrese de llamar .close() para liberar recursos.

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

Para evitar tener que hacerlo, se recomienda usar el cliente desde un administrador de contexto siempre que sea posible, lo que se cerrará automáticamente para usted.

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient: obtener modelos

Tenga en cuenta que primero debe en el repositorio para poder capturarlos. En los ejemplos siguientes se supone que usa el repositorio global de modelos de Azure IoT.

La llamada .get_models() a capturará el modelo en la DTMI proporcionada y potencialmente sus dependencias (según el modo de resolución de dependencias). Devolverá un dict objeto que asigna DTMIs a definiciones de modelo.

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

Si proporciona varios DTMIs al método , puede recuperar varios modelos (y potencialmente sus dependencias) a la vez.

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

De forma predeterminada, el cliente usará el dependencias con el modo de resolución de dependencias con el que se configuró en la creación de instancias al recuperar modelos. Sin embargo, este comportamiento se puede invalidar pasando cualquiera de las opciones válidas en como argumento de palabra clave opcional a . .get_models()

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

Convenciones de DTMI

El paquete contiene un módulo denominado dtmi_conventions, que, cuando se importa, proporciona una serie de operaciones de utilidad para trabajar con 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"

Solución de problemas

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en DEBUG el nivel.

Excepciones

Las API del repositorio de modelos pueden generar excepciones definidas en azure-core.

Además, pueden generar excepciones definidas en :azure-iot-modelsrepository

  • ModelError : indica un error al intentar analizar o resolver una definición de modelo. Esto generalmente significa que hay un modelo con formato incorrecto que no cumple con la especificación dtDL del modelo

Envío de comentarios

Si encuentra errores o tiene sugerencias, cree una incidencia.

Pasos siguientes

Ejemplos

Hay ejemplos adicionales disponibles en el repositorio de ejemplos.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.