Repository del modello di dispositivoDevice model repository

Il repository del modello di dispositivo (ricevitore) consente ai generatori di dispositivi di gestire e condividere la Plug and Play dei modelli di dispositivo.The device model repository (DMR) enables device builders to manage and share IoT Plug and Play device models. I modelli di dispositivo sono documenti JSON LD definiti con il linguaggio di modellazione digitale gemello (DTDL).The device models are JSON LD documents defined using the Digital Twins Modeling Language (DTDL).

RICEVITORE definisce un modello per archiviare le interfacce DTDL in una struttura di cartelle basata sull'identificatore del modello del dispositivo gemello (DTMI).The DMR defines a pattern to store DTDL interfaces in a folder structure based on the device twin model identifier (DTMI). È possibile individuare un'interfaccia in ricevitore convertendo DTMI in un percorso relativo.You can locate an interface in the DMR by converting the DTMI to a relative path. Il DTMI, ad esempio, viene dtmi:com:example:Thermostat;1 convertito in /dtmi/com/example/thermostat-1.json .For example, the dtmi:com:example:Thermostat;1 DTMI translates to /dtmi/com/example/thermostat-1.json.

Repository del modello di dispositivo pubblicoPublic device model repository

Microsoft ospita una ricevitore pubblica con queste caratteristiche:Microsoft hosts a public DMR with these characteristics:

  • Modelli curati.Curated models. Microsoft esamina e approva tutte le interfacce disponibili usando un flusso di lavoro di convalida della richiesta pull di GitHub.Microsoft reviews and approves all available interfaces using a GitHub pull request (PR) validation workflow.
  • Immutabilità.Immutability. Dopo la pubblicazione, non è possibile aggiornare un'interfaccia.After it's published, an interface can't be updated.
  • Hyper-scale.Hyper-scale. Microsoft fornisce l'infrastruttura necessaria per creare un endpoint sicuro e scalabile in cui è possibile pubblicare e utilizzare i modelli di dispositivo.Microsoft provides the required infrastructure to create a secure, scalable endpoint where you can publish and consume device models.

Repository del modello di dispositivo personalizzatoCustom device model repository

Usare lo stesso modello ricevitore per creare un ricevitore personalizzato in qualsiasi supporto di archiviazione, ad esempio file system locali o server Web HTTP personalizzati.Use the same DMR pattern to create a custom DMR in any storage medium, such as local file system or custom HTTP web servers. È possibile recuperare i modelli di dispositivo dal ricevitore personalizzato in modo analogo a quello del ricevitore pubblico modificando l'URL di base usato per accedere a ricevitore.You can retrieve device models from the custom DMR in the same way as from the public DMR by changing the base URL used to access the DMR.

Nota

Microsoft fornisce gli strumenti per convalidare i modelli di dispositivo nella ricevitore pubblica.Microsoft provides tools to validate device models in the public DMR. È possibile riutilizzare questi strumenti in repository personalizzati.You can reuse these tools in custom repositories.

Modelli pubbliciPublic models

I modelli di dispositivo pubblico archiviati nel repository del modello sono disponibili per l'utilizzo e l'integrazione da parte di tutti gli utenti nelle proprie applicazioni.The public device models stored in the model repository are available for everyone to consume and integrate in their applications. I modelli di dispositivo pubblico consentono a un eco-sistema aperto per i generatori di dispositivi e gli sviluppatori di soluzioni di condividere e riutilizzare i propri dispositivi Plug and Play modelli di dispositivo.Public device models enable an open eco-system for device builders and solution developers to share and reuse their IoT Plug and Play device models.

Vedere la sezione pubblicare un modello per istruzioni su come pubblicare un modello nel repository del modello per renderlo pubblico.Refer to the Publish a model section for instructions on how to publish a model in the model repository to make it public.

Gli utenti possono sfogliare, cercare e visualizzare le interfacce pubbliche dal repository GitHubufficiale.Users can browse, search, and view public interfaces from the official GitHub repository.

Tutte le interfacce nelle dtmi cartelle sono disponibili anche dall'endpoint pubblico https://devicemodels.azure.comAll interfaces in the dtmi folders are also available from the public endpoint https://devicemodels.azure.com

Risolvere i modelliResolve models

Per accedere a livello di codice a queste interfacce, è necessario convertire un DTMI in un percorso relativo che è possibile usare per eseguire una query sull'endpoint pubblico.To programmatically access these interfaces, you need to convert a DTMI to a relative path that you can use to query the public endpoint.

Per convertire un DTMI in un percorso assoluto, usare la DtmiToPath funzione con IsValidDtmi :To convert a DTMI to an absolute path, use the DtmiToPath function with IsValidDtmi:

static string DtmiToPath(string dtmi)
{
    if (!IsValidDtmi(dtmi))
    {
        return null;
    }
    // dtmi:com:example:Thermostat;1 -> dtmi/com/example/thermostat-1.json
    return $"/{dtmi.ToLowerInvariant().Replace(":", "/").Replace(";", "-")}.json";
}

static bool IsValidDtmi(string dtmi)
{
    // Regex defined at https://github.com/Azure/digital-twin-model-identifier#validation-regular-expressions
    Regex rx = new Regex(@"^dtmi:[A-Za-z](?:[A-Za-z0-9_]*[A-Za-z0-9])?(?::[A-Za-z](?:[A-Za-z0-9_]*[A-Za-z0-9])?)*;[1-9][0-9]{0,8}$");
    return rx.IsMatch(dtmi);
}

Con il percorso risultante e l'URL di base per il repository è possibile ottenere l'interfaccia:With the resulting path and the base URL for the repository we can obtain the interface:

const string _repositoryEndpoint = "https://devicemodels.azure.com";

string dtmiPath = DtmiToPath(dtmi.ToString());
string fullyQualifiedPath = $"{_repositoryEndpoint}{dtmiPath}";
string modelContent = await _httpClient.GetStringAsync(fullyQualifiedPath);

Pubblicare un modelloPublish a model

Importante

È necessario avere un account GitHub per poter inviare i modelli alla ricevitore pubblica.You must have a GitHub account to be able to submit models to the public DMR.

  1. Creare un fork del repository GitHub pubblico: https://github.com/Azure/iot-plugandplay-models .Fork the public GitHub repository: https://github.com/Azure/iot-plugandplay-models.
  2. Clonare il repository con fork.Clone the forked repository. Se lo si desidera, è possibile creare un nuovo ramo per evitare che le modifiche siano isolate dal main ramo.Optionally create a new branch to keep your changes isolated from the main branch.
  3. Aggiungere le nuove interfacce alla dtmi cartella usando la convenzione cartella/nome file.Add the new interfaces to the dtmi folder using the folder/filename convention. Per altre informazioni, vedere importare un modello nella dtmi/ cartella.To learn more, see Import a Model to the dtmi/ folder.
  4. Convalidare i modelli localmente utilizzando lo dmr-client strumento.Validate the models locally using the dmr-client tool. Per altre informazioni, vedere convalidare i modelli.To learn more, see validate models.
  5. Eseguire il commit delle modifiche in locale ed effettuare il push nel fork.Commit the changes locally and push to your fork.
  6. Dal fork creare una richiesta pull destinata al main ramo.From your fork, create a pull request that targets the main branch. Vedere la documentazione relativa alla creazione di un problema o di una richiesta pull .See Creating an issue or pull request docs.
  7. Esaminare i requisiti della richiesta pull.Review the pull request requirements.

La richiesta pull attiva un set di azioni GitHub che convalidano le interfacce inviate e assicura che la richiesta pull soddisfi tutti i requisiti.The pull request triggers a set of GitHub actions that validate the submitted interfaces, and makes sure your pull request satisfies all the requirements.

Microsoft risponderà a una richiesta pull con tutti i controlli in tre giorni lavorativi.Microsoft will respond to a pull request with all checks in three business days.

dmr-client strumentidmr-client tools

Gli strumenti usati per convalidare i modelli durante i controlli della richiesta pull possono essere usati anche per aggiungere e convalidare le interfacce DTDL localmente.The tools used to validate the models during the PR checks can also be used to add and validate the DTDL interfaces locally.

Nota

Questo strumento richiede .NET SDK versione 3,1 o successiva.This tool requires the .NET SDK version 3.1 or greater.

Installare dmr-clientInstall dmr-client

curl -L https://aka.ms/install-dmr-client-linux | bash
iwr https://aka.ms/install-dmr-client-windows -UseBasicParsing | iex

Importare un modello nella dtmi/ cartellaImport a model to the dtmi/ folder

Se il modello è già archiviato in file JSON, è possibile usare il dmr-client import comando per aggiungerli alla dtmi/ cartella con i nomi file corretti:If you have your model already stored in json files, you can use the dmr-client import command to add them to the dtmi/ folder with the correct file names:

# from the local repo root folder
dmr-client import --model-file "MyThermostat.json"

Suggerimento

È possibile usare l' --local-repo argomento per specificare la cartella radice del repository locale.You can use the --local-repo argument to specify the local repository root folder.

Convalida modelliValidate models

È possibile convalidare i modelli con il dmr-client validate comando:You can validate your models with the dmr-client validate command:

dmr-client validate --model-file ./my/model/file.json

Nota

La convalida usa la versione più recente del parser DTDL per assicurarsi che tutte le interfacce siano compatibili con la specifica del linguaggio DTDL.The validation uses the latest DTDL parser version to ensure all the interfaces are compatible with the DTDL language specification.

Per convalidare le dipendenze esterne, devono esistere nel repository locale.To validate external dependencies, they must exist in the local repository. Per convalidare i modelli, utilizzare l' --repo opzione per specificare una local remote cartella o per risolvere le dipendenze:To validate models, use the --repo option to specify a local or remote folder to resolve dependencies:

# from the repo root folder
dmr-client validate --model-file ./my/model/file.json --repo .

Convalida rigorosaStrict validation

Il ricevitore include requisitiaggiuntivi, usare il stict flag per convalidare il modello:The DMR includes additional requirements, use the stict flag to validate your model against them:

dmr-client validate --model-file ./my/model/file.json --repo . --strict true

Controllare l'output della console per eventuali messaggi di errore.Check the console output for any error messages.

Esportare i modelliExport models

I modelli possono essere esportati da un repository specifico (locale o remoto) a un singolo file usando una matrice JSON:Models can be exported from a given repository (local or remote) to a single file using a JSON Array:

dmr-client export --dtmi "dtmi:com:example:TemperatureController;1" -o TemperatureController.expanded.json

Passaggi successiviNext steps

Il passaggio successivo suggerito consiste nel rivedere l' architettura plug and Play.The suggested next step is to review the IoT Plug and Play architecture.