Share via

Biblioteca de clientes repositório azure IoT Models para Python - versão 1.0.0a2020330001

  • Artigo

A Biblioteca de Repositório de Modelos Azure IoT para Python fornece funcionalidade para trabalhar com o Repositório de Modelos Azure IoT

Introdução

Instalar pacote

Instale a biblioteca de repositório de modelos Azure IoT para Python com pip:

pip install azure-iot-modelsrepository

Pré-requisitos

Modelos de publicação

Siga o guia para publicar modelos para o repositório global de modelos Azure IoT.

Se utilizar um repositório local ou remoto personalizado, pode simplesmente adicionar os seus ficheiros de modelo a uma estrutura de diretório no local do repositório, por exemplo. dtmi/com/example/thermostat-1.json

Autenticação

Atualmente, não são suportados mecanismos de autenticação. O ponto final global não está ligado a uma subscrição do Azure e não suporta a autenticação. Todos os modelos publicados destinam-se a consumo público anónimo.

Conceitos-chave

O Azure IoT Models Repository permite aos construtores gerir e partilhar modelos digitais gémeos. Os modelos são documentos JSON-LD definidos usando a Linguagem de Definição de Gémeos Digitais (DTDL).

O repositório define um padrão para armazenar interfaces DTDL numa estrutura de diretório baseada no Digital Twin Model Identifier (DTMI). Pode localizar uma interface no repositório convertendo o DTMI num caminho relativo. Por exemplo, o DTMI dtmi:com:example:Thermostat;1 traduz-se para /dtmi/com/example/thermostat-1.json.

Exemplos

As seguintes secções fornecem vários excertos que abrangem tarefas comuns de repositório de modelos:

Inicialização dos ModelosRepositoryCliente

Localização do Repositório

Quando não é fornecida qualquer localização de repositório durante a instantânea, o ponto final global do repositório Azure IoT Models (https://devicemodels.azure.com/) é utilizado

client = ModelsRepositoryClient()

Em alternativa, pode fornecer uma localização personalizada para onde o seu repositório está localizado através da palavra-chave opcional repository_location . O cliente aceita os seguintes formatos de localização:

  • URL web - por exemplo. "https://contoso.com/models/"
  • Sistema de Arquivo Local URI - por exemplo. "file:///path/to/repository/"
  • Ficheiro POSIX - por exemplo. "/path/to/repository/"
  • Acionar o filepath da carta - por exemplo. "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Modo de Resolução de Dependência

O cliente pode ser configurado com um modo opcional dependency_resolution em instantaneamente, utilizando um dos seguintes valores:

  • 'disabled' - O cliente não resolverá as dependências dos modelos
  • 'enabled' - O cliente resolverá quaisquer dependências de modelos
  • 'tryFromExpanded' - O cliente tentará resolver os modelos utilizando uma definição de modelo expandida (recuando no 'enabled' modo, se não for possível)
client = ModelsRepositoryClient(dependency_resolution="enabled")

Se o dependency_resolution modo não for especificado:

  • Os clientes configurados para o Azure IoT Models Repository global endpoint global irá por defeito usar 'tryFromExpanded'
  • Os clientes configurados para uma localização personalizada (remota ou local) não irão utilizar 'enabled'

Opções Adicionais

Se precisar de anular o comportamento predefinido do pipeline da biblioteca azul-core, pode fornecer vários argumentos de palavras-chave durante a instantânea.

Limpeza do cliente

Quando terminar com o seu cliente, certifique-se de ligar .close() para libertar recursos

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

Para evitar ter de o fazer, recomenda-se que utilize o seu cliente de dentro de um gestor de contexto sempre que possível, o que será automaticamente fechado para si

with ModelsRepositoryClient() as client:
    # Do things

ModelosRepositoryCliente - Obter Modelos

Note que primeiro os publicaram modelos no seu repositório antes de os poder ir buscar. Os seguintes exemplos assumem que está a usar o Repositório global de modelos Azure IoT.

A chamada .get_models() irá buscar o modelo ao DTMI fornecido e potencialmente às suas dependências (dependendo do modo de resolução de dependência). Devolverá um dict que mapeia DTMIs para definições de modelo.

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

Se fornecer vários DTMIs ao método, pode recuperar vários modelos (e potencialmente as suas dependências) de uma só 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)))

Por predefinição, o cliente utilizará o modo de resolução com que foi configurado em instantaneamente ao recuperar os modelos. No entanto, este comportamento pode ser ultrapassado ao passar qualquer uma das opções válidas como um argumento opcional de palavra-chave para .get_models()

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

Convenções do DTMI

O pacote contém um módulo chamado dtmi_conventions, que, quando importado fornece uma série de operações de utilidade para trabalhar com 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"

Resolução de problemas

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos. Informações sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao DEBUG nível.

Exceções

Os APIs de repositório de modelos podem levantar exceções definidas no núcleo azul.

Além disso, podem levantar exceções definidas no azure-iot-modelsrepository:

  • ModelError - Indica que ocorreu um erro ao tentar analisar/resolver uma definição de modelo. Isto geralmente significa que há um modelo mal formado que não cumpre a especificação DTDL do modelo

Enviar Comentários

Se encontrar escutas ou tiver sugestões, por favor abra um problema.

Passos seguintes

Amostras

Estão disponíveis amostras adicionais no repositório de amostras.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.