Compartir vía

Administración de modelos de Azure Digital Twins

  • Artículo

En este artículo se describe cómo administrar los modelos de la instancia de Azure Digital Twins. Las operaciones de administración incluyen la carga, validación, recuperación y eliminación de modelos.

Requisitos previos

Para poder seguir los pasos que se describen en este artículo y trabajar con Azure Digital Twins, es preciso configurar una instancia de Azure Digital Twins y los permisos necesarios para usarla. Si ya tiene una instancia configurada de Azure Digital Twins, puede usarla y pasar a la sección siguiente. De lo contrario, siga las instrucciones que se indican en Configuración de una instancia y autenticación. Las instrucciones contienen información que le ayudará a comprobar que ha completado cada paso correctamente.

Una vez configurada la instancia, anote el nombre de host de esta. El nombre de host se encuentra en Azure Portal.

Interfaces para desarrolladores

En este artículo se describe cómo completar diferentes operaciones de administración con el SDK de .NET (C#). También puede crear estas mismas llamadas de administración con los otros SDK de lenguaje descritos en API y SDK de Azure Digital Twins.

Otras interfaces de desarrollador que se pueden usar para completar estas operaciones incluyen:

Nota:

Actualmente, Azure Digital Twins Explorer es totalmente compatible con modelos DTDL v2 y admite funcionalidad limitada para los modelos DTDL v3.

Los modelos de DTDL v3 se pueden ver en el panel Modelos y los gemelos creados con modelos de DTDL v3 se pueden ver y editar (incluidos los que tienen propiedades de matriz). Sin embargo, los modelos DTDL v3 no se mostrarán en el panel Gráfico de modelos y no se pueden importar mediante Azure Digital Twins Explorer. Para importar modelos DTDL v3 a la instancia, use otra interfaz de desarrollador, como las API y los SDK o la CLI de Azure.

Visualización

Azure Digital Twins Explorer es una herramienta visual para explorar los datos en el grafo de Azure Digital Twins. Puede usar el explorador para ver, consultar y editar los modelos, los gemelos y las relaciones.

Para obtener información sobre la herramienta Azure Digital Twins Explorer, vea Azure Digital Twins Explorer. Para obtener pasos detallados sobre el uso de sus características, consulte Uso de Azure Digital Twins Explorer.

Este es el aspecto de la visualización:

Captura de pantalla de Azure Digital Twins Explorer en la que se muestra un grafo de modelo de ejemplo.

Crear modelos

Puede crear sus propios modelos desde cero o usar ontologías existentes que están disponibles para su sector.

Creación de modelos

Los modelos de Azure Digital Twins se escriben en DTDL y se guardan como archivos JSON. También hay una extensión de DTDL disponible para Visual Studio Code, que proporciona validación de sintaxis y otras características para facilitar la escritura de documentos DTDL.

Considere un ejemplo en el que un hospital quiere representar digitalmente sus habitaciones. Cada habitación contiene un dispensador de jabón inteligente para supervisar el lavado de manos y sensores para controlar el tráfico en la habitación.

El primer paso para la solución consiste en crear modelos para representar aspectos del hospital. La habitación de un paciente en este escenario podría describirse de la siguiente manera:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Nota:

Se trata de un cuerpo de ejemplo de un archivo JSON en el que se define y se guarda un modelo, que se va a cargar como parte de un proyecto de cliente. La llamada a la API de REST, por otro lado, adopta una matriz de definiciones de modelo como la anterior (que se asigna a un atributo IEnumerable<string> en el SDK de .NET). Por lo tanto, para usar este modelo en la API de REST directamente, inclúyalo entre corchetes.

Este modelo define un nombre y un id. único para la habitación del paciente, y propiedades para representar el recuento de visitantes y el estado del lavado de manos. Estos contadores se actualizarán a partir de sensores de movimiento y dispensadores de jabón inteligentes, y se usarán juntos para calcular una propiedad de handwash percentage. El modelo también define una relación hasDevices, que se usará para conectar cualquier gemelo digital basado este modelo de Habitación con los dispositivos reales.

Nota:

Existen algunas características DTDL que Azure Digital Twins no admite actualmente, incluido el atributo writable en las propiedades y relaciones, y minMultiplicity y maxMultiplicity para las relaciones. Para más información, consulte Notas de DTDL específicas del servicio.

Siguiendo este método, puede definir modelos para las salas y las zonas del hospital, o bien para todo el hospital.

Si su objetivo es crear un conjunto de modelos completo que describa el dominio del sector, considere si hay una ontología del sector existente que puede usar para facilitar la creación de modelos. En la sección siguiente se describen las ontologías del sector con más detalle.

Uso de ontologías existentes estándar del sector

Una ontología es un conjunto de modelos que describen de manera completa un dominio determinado, como la construcción, la creación de estructuras, los sistemas IoT, las ciudades inteligentes, las redes eléctricas, el contenido web, etc.

Si la solución es para un determinado sector que usa cualquier tipo de estándar de modelado, considere la posibilidad de empezar con un conjunto preexistente de modelos diseñados para el sector en lugar de diseñar los modelos desde cero. Microsoft se ha asociado con expertos en dominios para crear ontologías de modelos de DTDL basados en estándares del sector, con el fin de ayudar a minimizar la reinvención y alentar la coherencia y la simplificación en las soluciones del sector. Puede leer más sobre estos ontologías, incluido cómo usarlas y qué ontologías están disponibles ahora, en ¿Qué es una ontología?.

Validación de la sintaxis

Después de crear un modelo, se recomienda validar los modelos sin conexión antes de cargarlos en la instancia de Azure Digital Twins.

Para ayudarle a validar los modelos, se proporciona una biblioteca de análisis de DTDL del lado cliente de .NET en NuGet: DTDLParser. Puede usar la biblioteca del analizador directamente en el código de C#. También puede ver el uso de ejemplo del analizador en DTDLParserResolveSample en GitHub.

Carga de modelos

Una vez creados los modelos, puede cargarlos en la instancia de Azure Digital Twins.

Cuando esté listo para cargar un modelo, puede usar el fragmento de código siguiente para el SDK de .NET:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

En la carga, el servicio valida los archivos de modelo.

Normalmente, tendrá que cargar más de un modelo en el servicio. Hay varias maneras de cargar muchos modelos a la vez en una sola transacción. Para ayudarle a elegir una estrategia, tenga en cuenta el tamaño del conjunto de modelos a medida que continúe con el resto de esta sección.

Carga de conjuntos de modelos pequeños

Para conjuntos de modelos más pequeños, puede cargar varios modelos a la vez mediante llamadas API individuales. Puede comprobar el límite actual del número de modelos que se pueden cargar en una sola llamada API en los límites de Azure Digital Twins.

Si usa el SDK, puede cargar varios archivos de modelo con el método CreateModels de esta manera:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Si usa las API de REST o CLI de Azure, puede cargar varios modelos colocando varias definiciones de modelo en un único archivo JSON para cargarlos juntos. En este caso, los modelos deben colocarse en una matriz JSON dentro del archivo, como en el ejemplo siguiente:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Carga de conjuntos de modelos grandes con la API Import Jobs

Para conjuntos de modelos grandes, puede usar la API Import Jobs para cargar muchos modelos a la vez en una sola llamada API. La API puede aceptar simultáneamente hasta el límite de Azure Digital Twins para el número de modelos de una instancia y reordena automáticamente los modelos si es necesario para resolver las dependencias entre ellos. Este método requiere el uso de Azure Blob Storage, así como permisos de escritura en la instancia de Azure Digital Twins para modelos y trabajos masivos.

Sugerencia

La API Import Jobs también permite importar gemelos y relaciones en la misma llamada, para crear todas las partes de un grafo a la vez. Para obtener más información sobre este proceso, consulte Carga de modelos, gemelos y relaciones de forma masiva con la API Import Jobs.

Para importar modelos de forma masiva, deberá estructurar los modelos (y cualquier otro recurso incluido en el trabajo de importación masiva) como un archivo NDJSON. La sección Models viene inmediatamente después de la sección Header, lo que la convierte en la primera sección de datos del grafo del archivo. Puede ver un archivo de importación de ejemplo y un proyecto de ejemplo para crear estos archivos en la introducción a la API Import Jobs.

A continuación, el archivo debe cargarse en un blob anexo en Azure Blob Storage. Para obtener instrucciones sobre cómo crear un contenedor de Azure Storage, consulte Creación de un contenedor. A continuación, cargue el archivo mediante el método de carga preferido (algunas opciones son el comando AzCopy, la CLI de Azure o Azure Portal).

Una vez cargado el archivo NDJSON en el contenedor, obtenga su dirección URL dentro del contenedor de blobs. Usará este valor más adelante en el cuerpo de la llamada API de importación masiva.

Esta es una captura de pantalla que muestra el valor de dirección URL de un archivo de blob en Azure Portal:

Captura de pantalla de Azure Portal que muestra la dirección URL de un archivo en un contenedor de almacenamiento.

A continuación, el archivo se puede usar en una llamada API de Import Jobs. Proporcionará la dirección URL del almacenamiento de blobs del archivo de entrada, así como una nueva dirección URL de almacenamiento de blobs para indicar dónde desea que el registro de salida se almacene cuando el servicio lo cree.

Recuperación de modelos

Puede mostrar y recuperar los modelos almacenados en la instancia de Azure Digital Twins.

Existen varias opciones:

  • Recuperar un único modelo
  • Recuperar todos los modelos
  • Recuperar los metadatos y las dependencias de los modelos.

A continuación, se muestran algunas llamadas de ejemplo:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

Todas las llamadas SDK para recuperar modelos devuelven todos los objetos DigitalTwinsModelData. DigitalTwinsModelData contiene metadatos sobre el modelo almacenado en la instancia Azure Digital Twins, como el nombre, la DTMI y la fecha de creación del modelo. El objeto DigitalTwinsModelData también incluye opcionalmente el propio modelo. Significa que, en función de los parámetros, puede usar las llamadas de recuperación para recuperar solo los metadatos (lo que resulta útil en escenarios en los que se desea mostrar una lista de interfaz de usuario de las herramientas disponibles, por ejemplo) o todo el modelo.

La llamada a RetrieveModelWithDependencies devuelve no solo el modelo solicitado, sino también todos los modelos de los que depende el modelo solicitado.

Los modelos no se devuelven necesariamente con el formato de documento exacto con el que se cargaron. Azure Digital Twins solo garantiza que el formato devuelvo será equivalente desde el punto de vista semántico.

Actualización de modelos

En esta sección se describen las consideraciones y estrategias para actualizar los modelos.

Antes de actualizar: piense en el contexto de toda la solución.

Antes de realizar actualizaciones en los modelos, se recomienda pensar holísticamente en toda la solución y el impacto de los cambios de modelo que está a punto de realizar. Los modelos de una solución Azure Digital Twins a menudo están interconectados, por lo que es importante tener en cuenta los cambios en cascada en los que la actualización de un modelo requiere actualizar varios otros. La actualización de modelos afectará a los gemelos que usan los modelos y también puede afectar a la entrada y el procesamiento de código, las aplicaciones cliente y los informes automatizados.

Estas son algunas recomendaciones que le ayudarán a administrar las transiciones del modelo sin problemas:

  • En lugar de pensar en los modelos como entidades individuales, considere la posibilidad de evolucionar todo el conjunto de modelos cuando sea necesario para mantener los modelos y sus relaciones actualizados.
  • Trate los modelos como código fuente y adminístrelos en el control de código fuente. Aplique el mismo rigor y la misma atención a los modelos y los cambios de modelo que aplica a otro código de la solución.

Cuando esté listo para continuar con el proceso de actualizar los modelos, encontrará en el resto de esta sección las estrategias que puede usar para implementar las actualizaciones.

Estrategias para actualizar modelos

Una vez que se carga un modelo en la instancia de Azure Digital Twins, la interfaz del modelo es inmutable, lo que significa que no hay ninguna "edición" tradicional de los modelos. Azure Digital Twins tampoco permite la recarga del mismo modelo exacto mientras un modelo correspondiente ya esté presente en la instancia.

En su lugar, si desea realizar cambios en un modelo, como actualizar displayName o description, o agregar y quitar propiedades, deberá reemplazar el modelo original.

Hay dos estrategias entre las que elegir al reemplazar un modelo:

  • Estrategia 1: Cargar una nueva versión del modelo: cargue el modelo, con un nuevo número de versión, y actualice los gemelos para usar ese nuevo modelo. Las versiones nuevas y anteriores del modelo existirán en la instancia hasta que elimine una.
    • Use esta estrategia cuando quiera actualizar solo algunos de los gemelos que usan el modelo, o cuando desee asegurarse de que los gemelos se mantienen conformes con sus modelos y se pueden escribir a través de la transición del modelo.
  • Estrategia 2: Eliminar el modelo antiguo y volver a cargarlo: elimine el modelo original y cargue el nuevo modelo con el mismo nombre e id. (valor DTMI) en su lugar. Reemplace completamente el modelo anterior por el nuevo.
    • Use esta estrategia cuando quiera actualizar todos los gemelos que usan este modelo a la vez, así como todo el código que reacciona a los modelos. Si la actualización del modelo contiene un cambio importante con la actualización del modelo, los gemelos no serán conformes con sus modelos durante un breve período de tiempo mientras los está transfiriendo del modelo anterior al nuevo, lo que significa que no podrán realizar ninguna actualización hasta que se cargue el nuevo modelo y los gemelos se ajusten a él.

Nota:

No se recomienda realizar cambios importantes en los modelos fuera del desarrollo.

Continúe con las secciones siguientes para obtener más información sobre cada opción de estrategia en detalle.

Estrategia 1: Cargar una nueva versión del modelo

Esta opción implica crear una nueva versión del modelo y cargarla en la instancia.

Esta operación no sobrescribe versiones anteriores del modelo, por lo que varias versiones del modelo coexistirán en la instancia hasta que las quite. Puesto que coexisten la nueva versión del modelo y la versión anterior, los gemelos pueden usar la nueva versión del modelo o la versión anterior, lo que significa que cargar una nueva versión de un modelo no afecta automáticamente a los gemelos existentes. Los gemelos existentes permanecerán como instancias de la versión anterior del modelo y puede actualizar estos gemelos a la nueva versión del modelo mediante su aplicación de revisiones.

Para usar esta estrategia, siga estos pasos:

1. Cree y cargue una nueva versión del modelo

Para crear una nueva versión de un modelo existente, empiece con el DTDL del modelo original. Actualice, agregue o quite los campos que quiera cambiar.

A continuación, marque este modelo como una versión más reciente del modelo actualizando el campo id del modelo. La última sección del identificador de modelo, después del ;, representa el número de modelo. Para indicar que esta es una versión más actualizada de este modelo, incremente el número al final del valor id en cualquier número mayor que el número de versión actual.

Por ejemplo, si el identificador de modelo anterior tuviera el siguiente aspecto:

"@id": "dtmi:com:contoso:PatientRoom;1",

La versión 2 de este modelo podría tener este aspecto:

"@id": "dtmi:com:contoso:PatientRoom;2",

A continuación, cargue la nueva versión del modelo en la instancia.

Esta versión del modelo estará disponible en su instancia para usarse con gemelos digitales. No sobrescribe las versiones anteriores del modelo, por lo que ahora coexisten varias versiones del modelo en la instancia.

2. Actualice los elementos del grafo según sea necesario

A continuación, actualice los gemelos y las relaciones de la instancia para utilizar la nueva versión del modelo en lugar de la antigua.

Puede utilizar las siguientes instrucciones para actualizar gemelos y actualizar relaciones. La operación de revisión para actualizar el modelo de un gemelo tendrá un aspecto parecido al siguiente:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Importante

Cuando actualice gemelos, utilice la misma revisión para actualizar los id. de modelo (a la nueva versión) y los campos que deben modificarse para que se ajusten al nuevo modelo.

Es posible que también tenga que actualizar relaciones y otros modelos de la instancia que hagan referencia a este modelo para que hagan referencia a la nueva versión del modelo. Tendrá que realizar otra operación de actualización de modelos para lograr este propósito, así que vuelva al principio de esta sección y repita el proceso para cualquier otro modelo que necesite actualizar.

3. (Opcional) Retire o elimine la versión anterior del modelo

Si no va a utilizar más la versión del modelo antiguo, puede desconectar el modelo antiguo. Esta acción permite que el modelo siga existiendo en la instancia, pero no se puede usar para crear nuevos gemelos digitales.

También puede eliminar el modelo antiguo por completo si ya no lo quiere en la instancia.

Las secciones vinculadas anteriormente contienen código de ejemplo y consideraciones para retirar y eliminar modelos.

Estrategia 2: Eliminar el modelo antiguo y volver a cargar

En lugar de incrementar la versión de un modelo, puede eliminar un modelo por completo y volver a cargar un modelo editado en la instancia.

Azure Digital Twins no recuerda que el modelo anterior se haya cargado alguna vez, por lo que esta acción será como cargar un modelo completamente nuevo. Los gemelos que usan el modelo cambiarán automáticamente a la nueva definición una vez que esté disponible. En función de cómo difiere la nueva definición de la anterior, estos gemelos pueden tener propiedades y relaciones que coincidan con la definición eliminada y no sean válidas con la nueva, por lo que es posible que tenga que aplicarles revisiones para asegurarse de que siguen siendo válidos.

Para usar esta estrategia, siga estos pasos:

1. Elimine el modelo anterior

Puesto que Azure Digital Twins no permite dos modelos con el mismo id., empiece por eliminar el modelo original de la instancia.

Nota:

Si tiene otros modelos que dependen de este modelo (mediante herencia o componentes), deberá quitar esas referencias antes de poder eliminar el modelo. Puede actualizar esos modelos dependientes primero para quitar temporalmente las referencias o eliminar los modelos dependientes y volver a cargarlos en un paso posterior.

Use las instrucciones siguientes para eliminar su modelo original. Esta acción dejará a los gemelos que usaban ese modelo temporalmente "huérfanos", ya que ahora usan un modelo que ya no existe. Este estado se reparará en el paso siguiente al volver a cargar el modelo actualizado.

2. Cree y cargue un nuevo modelo

Comience con el DTDL del modelo original. Actualice, agregue o quite los campos que quiera cambiar.

A continuación, cargue el modelo a la instancia, como si fuera un nuevo modelo que se carga por primera vez.

3. Actualice los elementos del grafo según sea necesario

Ahora que el nuevo modelo se ha cargado en lugar del anterior, los gemelos del grafo comenzarán automáticamente a usar la nueva definición de modelo una vez que expire y se restablezca el almacenamiento en caché en la instancia. Este proceso puede tardar entre 10 y 15 minutos o más, dependiendo del tamaño del gráfico. Después de eso, las propiedades nuevas y modificadas del modelo deben ser accesibles y las propiedades quitadas ya no serán accesibles.

Nota:

Si quitó otros modelos dependientes anteriormente para eliminar el modelo original, vuelva a cargarlos ahora después de restablecer la memoria caché. Si actualizó los modelos dependientes para quitar temporalmente las referencias al modelo original, puede actualizarlos de nuevo para volver a colocar la referencia.

A continuación, actualice los gemelos y las relaciones de la instancia para que sus propiedades coincidan con las propiedades definidas por el nuevo modelo. Antes de completar este paso, se pueden leer los gemelos que no coinciden con su modelo, pero no se pueden escribir en ellos. Para obtener más información sobre el estado de los gemelos sin un modelo válido, consulte Gemelos sin modelos.

Hay dos maneras de actualizar gemelos y relaciones para el nuevo modelo para que se puedan escribir de nuevo:

  • Aplicar revisiones a los gemelos y las relaciones según sea necesario para que se ajusten al nuevo modelo. Puede utilizar las siguientes instrucciones para actualizar gemelos y actualizar relaciones.
    • Si ha agregado propiedades: no es necesario actualizar los gemelos y las relaciones para que tengan los nuevos valores, ya que los gemelos que no tienen los nuevos valores seguirán siendo gemelos válidos. Puede aplicarles revisiones, pero deberá agregar valores para las nuevas propiedades.
    • Si ha quitado propiedades: es necesario aplicar revisiones a los gemelos para quitar las propiedades que ahora no son válidas con el nuevo modelo.
    • Si ha actualizado propiedades: es necesario aplicar revisiones a los gemelos para actualizar los valores de las propiedades modificadas para que sean válidos con el nuevo modelo.
  • Elimine los gemelos y las relaciones que usan el modelo y vuelva a crearlos. Puede utilizar las siguientes instrucciones para eliminar gemelos y volver a crear gemelos, y para borrar relaciones y volver a crear relaciones.
    • Es posible que quiera realizar esta operación si está realizando muchos cambios en el modelo y será difícil actualizar los gemelos existentes para que coincidan con él. Sin embargo, volver a crearlos puede ser complicado si tiene muchos gemelos interconectados por muchas relaciones.

Eliminación de modelos

Los modelos también se pueden quitar del servicio de alguna de estas dos maneras:

  • Retirada: una vez que se ha retirado un modelo, ya no se puede usar para crear otros gemelos digitales. Las instancias existentes de Digital Twins que ya usan este modelo no se ven afectadas, por lo que todavía se pueden actualizar con elementos como cambios de propiedades y con la adición o eliminación de relaciones.
  • Eliminación: esta operación eliminará completamente el modelo de la solución. Todas las instancias de Digital Twins que utilicen este modelo dejarán de estar asociadas con cualquier modelo válido, por lo que se tratarán como si no tuvieran ningún modelo. Todavía puede leer estas instancias de Digital Twins, pero no puede actualizarlas hasta que se reasignen a un modelo diferente.

Estas operaciones son características independientes que no se ven afectadas entre sí, aunque se pueden usar juntas para quitar un modelo gradualmente.

Nota:

Si desea eliminar todos los modelos, gemelos y relaciones de una instancia a la vez, use la API Delete Jobs.

Retirada

Para retirar un modelo, puede utilizar el método DecommissionModel del SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

También puede retirar un modelo mediante la llamada API REST DigitalTwinModels Update. La propiedad decommissioned es la única propiedad que se puede reemplazar por esta llamada API. El documento de revisión JSON tendrá un aspecto parecido al siguiente:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

El estado de retirada de un modelo se incluye en los registros ModelData devueltos por las API de recuperación del modelo.

Eliminación

Puede eliminar todos los modelos de la instancia a la vez o de manera individual.

Para obtener un ejemplo de cómo eliminar todos los modelos al mismo tiempo, consulte el repositorio Ejemplos de un extremo a otro para Azure Digital Twins en GitHub. El archivo CommandLoop.cs contiene una función CommandDeleteAllModels con código para eliminar todos los modelos de la instancia.

Para eliminar un modelo individual, siga las instrucciones y consideraciones del resto de esta sección.

Antes de la eliminación: Requisitos para la eliminación

Por lo general, los modelos se pueden eliminar en cualquier momento.

La excepción son los modelos de los que dependen otros modelos, ya sea con una relación extends o como componente. Por ejemplo, si un modelo ConferenceRoom extiende un modelo Room y tiene un modelo ACUnit como componente, no puede eliminar Room ni ACUnit hasta que ConferenceRoom elimina dichas referencias correspondientes.

Para ello, puede actualizar el modelo dependiente para quitar las dependencias o eliminarlo por completo.

Durante la eliminación: Proceso de eliminación

Incluso si un modelo cumple los requisitos para eliminarlo inmediatamente, es posible que quiera seguir unos cuantos pasos para evitar consecuencias no deseadas en las instancias de Digital Twins dependientes. Estos son algunos de los pasos que pueden facilitar la administración del proceso:

  1. En primer lugar, retire el modelo.
  2. Espere unos minutos para asegurarse de que el servicio ha procesado las solicitudes de creación gemelas de último minuto enviadas antes de la retirada.
  3. Consulte las instancias de Digital Twins por modelo para ver todas las instancias de Digital Twins que usan el modelo que ya se ha retirado.
  4. Elimine las instancias de Digital Twins si ya no las necesita o aplíqueles una revisión en un nuevo modelo, si es necesario. También puede optar por dejarlas como independientes, en cuyo caso se convierten en instancias de Digital Twins sin modelos una vez que se elimine el modelo. Vea la sección siguiente para conocer las implicaciones de este estado.
  5. Espere unos minutos para asegurarse de que los cambios se han aplicado.
  6. Eliminación del modelo

Para eliminar un modelo, puede usar la llamada al SDK deleteModel:.

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

También puede eliminar un modelo con la llamada API REST DigitalTwinModels Delete.

Después de la eliminación: Instancias de Digital Twins sin modelos

Una vez eliminado un modelo, ahora se considerará que todas las instancias de Digital Twins que usaban dicho modelo ya no tendrán ningún modelo. No hay ninguna consulta que pueda proporcionar una lista de todas las instancias de Digital Twins con este estado, aunque puede seguir consultando las instancias de Digital Twins del modelo eliminado para saber qué instancias se ven afectadas.

A continuación, se ofrece información general sobre lo que puede y no puede hacer con instancias de Digital Twins que no tienen ningún modelo.

Cosas que puede hacer:

  • Consulta de la instancia de Digital Twins.
  • Lectura de las propiedades
  • Lectura de las relaciones salientes
  • Adición y eliminación de las relaciones entrantes (de la misma forma, otras instancias de Digital Twins todavía pueden formar relaciones con esta instancia de Digital Twins)
    • El atributo target de la definición de la relación todavía puede reflejar el DTMI del modelo eliminado. Una relación sin destino definido también puede funcionar aquí.
  • Eliminar relaciones
  • Eliminación de la instancia de Digital Twins

Cosas que no puede hacer:

  • Editar las relaciones de salida (de la misma forma, las relaciones de esta instancia de Digital Twins con otras)
  • Modificar propiedades

Después de la eliminación: volver a cargar un modelo

Una vez eliminado un modelo, puede decidir más tarde si cargar un nuevo modelo con el mismo identificador que el que ha eliminado. Esto es lo que sucede en ese caso.

  • Desde la perspectiva del almacén de soluciones, esta operación equivale a cargar un modelo completamente nuevo. El servicio no recuerda si el anterior se cargó alguna vez.
  • Si hay otras instancias de Digital Twins en el grafo que hacen referencia al modelo eliminado, dejarán de estar huérfanas; este id. de modelo vuelve a ser válido con la nueva definición. Sin embargo, si la nueva definición del modelo es diferente de la definición del modelo que se eliminó, estas instancias de Digital Twins pueden tener propiedades y relaciones que coincidan con la definición eliminada y que no sean válidas con la nueva.

Azure Digital Twins no impide este estado, por lo que debe asegurarse de revisar detenidamente las instancias de Digital Twins para comprobar que siguen siendo válidas para el cambio de la definición del modelo.

Conversión de modelos v2 a v3

Azure Digital Twins admite las versiones 2 y 3 de DTDL (abreviadas en la documentación como v2 y v3, respectivamente). V3 es la opción recomendada debido a sus funcionalidades expandidas. En esta sección se explica cómo actualizar un modelo DTDL v2 existente a DTDL v3.

  1. Actualice el contexto. La característica principal que identifica un modelo como v2 o v3 es el campo @context de la interfaz. Para convertir un modelo de v2 a v3, cambie el valor de contexto de dtmi:dtdl:context;2 a dtmi:dtdl:context;3. Para muchos modelos, este será el único cambio necesario.
    1. Valor en v2: "@context": "dtmi:dtdl:context;2"
    2. Valor en v3: "@context": "dtmi:dtdl:context;3".
  2. Si es necesario, actualice los tipos semánticos. En DTDL v2, se admiten de manera nativa los tipos semánticos. En DTDL v3, se incluyen con la extensión de características QuantitativeTypes. Por lo tanto, si el modelo v2 usa tipos semánticos, deberá agregar la extensión de características al convertir el modelo en v3. Para ello, cambie primero el campo @context de la interfaz de un solo valor a una matriz de valores y agregue el valor dtmi:dtdl:extension:quantitativeTypes;1.
    1. Valor en v2: "@context": "dtmi:dtdl:context;2"
    2. Valor en v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. Si es necesario, considere los límites de tamaño. V2 y v3 tienen límites de tamaño diferentes, por lo que si la interfaz es muy grande, es posible que quiera revisar los límites en las diferencias entre DTDL v2 y v3.

Después de estos cambios, se ha convertido un modelo de DTDL v2 anterior a un modelo DTDL v3.

También puede considerar las nuevas funcionalidades de DTDL v3, como propiedades de tipo de matriz, relajación de versiones y extensiones de características adicionales, para ver si alguna de ellas sería una adición beneficiosa. Para obtener una lista completa de las diferencias entre DTDL v2 y v3, consulte Cambios de la versión 2 en la descripción del lenguaje DTDL v3.

Nota:

Actualmente, Azure Digital Twins Explorer es totalmente compatible con modelos DTDL v2 y admite funcionalidad limitada para los modelos DTDL v3.

Los modelos de DTDL v3 se pueden ver en el panel Modelos y los gemelos creados con modelos de DTDL v3 se pueden ver y editar (incluidos los que tienen propiedades de matriz). Sin embargo, los modelos DTDL v3 no se mostrarán en el panel Gráfico de modelos y no se pueden importar mediante Azure Digital Twins Explorer. Para importar modelos DTDL v3 a la instancia, use otra interfaz de desarrollador, como las API y los SDK o la CLI de Azure.

Pasos siguientes

Vea cómo crear y administrar instancias de Digital Twins basadas en los modelos: