las API y los SDK de Azure Digital Twins
En este artículo se proporciona información general sobre las API disponibles de Azure Digital Twins y los métodos para interactuar con ellas. Puede usar las API REST directamente con las instancias de Swagger asociadas o mediante un SDK.
Azure Digital Twins incluye API de plano de control, API de plano de datos y SDK para administrar su instancia y sus elementos.
- Las API de plano de control son las API de Azure Resource Manager (ARM) y cubren las operaciones de administración de recursos como la creación y eliminación de la instancia.
- Las API de plano de datos son las API de Azure Digital Twins y se usan para operaciones de administración de datos, como la administración de modelos, gemelos y el grafo.
- Los SDK aprovechan las API existentes para facilitar el desarrollo de aplicaciones personalizadas que usan Azure Digital Twins.
API de plano de control
Las API del plano de control son las API de ARM que se usan para administrar la instancia de Azure Digital Twins como un todo, por lo que cubren operaciones como la creación o eliminación de toda la instancia. También usará estas API para crear y eliminar puntos de conexión.
Para llamar a las API directamente, haga referencia a la carpeta de Swagger más reciente en la repositorio de Swagger del plano de control. Esta carpeta también incluye una carpeta de ejemplos que muestran el uso.
Estos son los SDK disponibles actualmente para las API del plano de control de Azure Digital Twins.
También puede ejercitar las API de plano de control interactuando con Azure Digital Twins mediante Azure Portal y la CLI.
API de plano de datos
Las API de plano de datos son las API de Azure Digital Twins que se usan para administrar los elementos de la instancia de Azure Digital Twins. Incluyen operaciones como la creación de rutas, la carga de modelos, la creación de relaciones y la administración de gemelos, y se pueden dividir ampliamente en las categorías siguientes:
DigitalTwinModels: la categoría DigitalTwinModels contiene API para administrar los modelos en una instancia de Azure Digital Twins. Las actividades de administración incluyen la carga, validación, recuperación y eliminación de modelos creados en DTDL.DigitalTwins: la categoría DigitalTwins contiene API que permiten a los desarrolladores crear, modificar y eliminar gemelos digitales y sus relaciones en una instancia de Azure Digital Twins.Query: la categoría Query permite a los desarrolladores localizar conjuntos de gemelos digitales en el grafo de gemelos entre las relaciones.Event Routes: la categoría Event Routes contiene API para enrutar datos por todo el sistema y hacia servicios de bajada.Import Jobs: La API Import Jobs permite administrar una acción asincrónica de larga duración para importar modelos, gemelos y relaciones de forma masiva.Delete Jobs- La API Delete Jobs le permite administrar una acción asincrónica de larga duración para eliminar todos los modelos, gemelos y relaciones de una instancia.
Para llamar a las API directamente, haga referencia a la carpeta de Swagger más reciente en la repositorio de Swagger del plano de datos. Esta carpeta también incluye una carpeta de ejemplos que muestran el uso. También puede consultar la documentación de referencia de API del plano de datos.
Estos son los SDK disponibles actualmente para las API del plano de datos de Azure Digital Twins.
También puede probar las API de plano de datos interactuando con Azure Digital Twins a través de la CLI.
Notas de uso y autenticación
Esta sección contiene información más detallada sobre el uso de las API y los SDK.
Notas de API
Se muestra información general para llamar directamente a las API de Azure Digital Twins.
- Puede usar una herramienta de prueba de REST de HTTP para realizar llamadas directas a las API de Azure Digital Twins. Para más información sobre este proceso, consulte Llamada a las API de Azure Digital Twins.
- Azure Digital Twins no admite actualmente el uso compartido de recursos entre orígenes (CORS). Para obtener más información sobre el impacto y las estrategias para solucionarlo, consulte Uso compartido de recursos entre orígenes (CORS) de Azure Digital Twins.
A continuación se muestra más información sobre la autenticación para las solicitudes de API.
- Una manera de generar un token de portador para las solicitudes de API de Azure Digital Twins es con el comando az account get-access-token de la CLI. Para obtener instrucciones detalladas, consulte Adición del token de portador.
- Las solicitudes a las API de Azure Digital Twins requieren un usuario o una entidad de servicio que forme parte del mismo inquilino de Microsoft Entra ID donde exista la instancia de Azure Digital Twins. Para evitar exámenes malintencionados de los puntos de conexión de Azure Digital Twins, las solicitudes con tokens de acceso desde fuera del inquilino de origen recibirán un mensaje de error "404 No se ha encontrado el subdominio". Este error se devolverá incluso si al usuario o a la entidad de servicio se le ha concedido un rol de propietario de datos o de lector de datos de Azure Digital Twins mediante la colaboración de Microsoft Entra B2B. Para información sobre cómo lograr el acceso a través de varios inquilinos, consulte Escritura de código de autenticación de aplicación.
Notas del SDK
El SDK subyacente para Azure Digital Twins es Azure.Core. Consulte la documentación del espacio de nombres de Azure como referencia sobre los tipos y la infraestructura del SDK.
A continuación, se muestra más información sobre la autenticación con los SDK.
- Para empezar, cree una instancia de la clase
DigitalTwinsClient. El constructor requiere credenciales que se pueden obtener con diferentes tipos de métodos de autenticación en el paquete deAzure.Identity. Para más información sobreAzure.Identity, consulte la documentación del espacio de nombres. - Es posible que encuentre útil
InteractiveBrowserCredentialal comenzar, pero hay muchas otras opciones, incluidas las credenciales para la identidad administrada, que probablemente va a usar para autenticar las funciones de Azure configuradas con MSI en Azure Digital Twins. Para más información sobreInteractiveBrowserCredential, consulte la documentación de la clase.
A continuación se muestra más información sobre las funciones y los datos devueltos.
- Todas las llamadas de API de servicio se exponen como funciones miembro en la clase
DigitalTwinsClient. - Todas las funciones de servicio se encuentran en versiones sincrónicas y asincrónicas.
- Todas las funciones de servicio inician una excepción en cualquier estado de devolución de 400 o superior. Asegúrese de ajustar las llamadas en una sección
tryy de capturar al menosRequestFailedExceptions. Para más información sobre este tipo de excepción, consulte su documentación de referencia. - La mayoría de los métodos de servicio devuelven
Response<T>o (Task<Response<T>>para las llamadas asincrónicas), dondeTes la clase de objeto de devolución para la llamada de servicio. La clase Responde encapsula la devolución del servicio y presenta los valores devueltos en su campoValue. - Los métodos de servicio con los resultados paginados devuelven
Pageable<T>oAsyncPageable<T>como resultados. Para más información sobre la clasePageable<T>, vea su documentación de referencia; para más información sobreAsyncPageable<T>, vea su documentación de referencia. - Puede recorrer en iteración los resultados paginados mediante un bucle
await foreach. Para obtener más información sobre este proceso, consulte Iterating with Async Enumerables in C# 8 (Iteración con enumerables asincrónicos en C# 8). - Los métodos de servicio devuelven objetos fuertemente tipados siempre que sea posible. Sin embargo, dado que Azure Digital Twins se basa en los modelos configurados de forma personalizada por el usuario en tiempo de ejecución (a través de los modelos DTDL cargados en el servicio), muchas API de servicio toman y devuelven datos gemelos en formato JSON.
Asistentes de serialización en el SDK de .NET (C#)
Los asistentes de serialización son funciones auxiliares disponibles en el SDK de .NET (C#) para crear o deserializar rápidamente datos gemelos para el acceso a información básica. Dado que los métodos principales del SDK devuelven los datos gemelos como JSON de forma predeterminada, puede resultar útil usar estas clases auxiliares para desglosar aún más los datos gemelos.
Las clases de asistente disponibles son:
BasicDigitalTwin: representa genéricamente los datos principales de un gemelo digital.BasicDigitalTwinComponent: representa genéricamente un componente en las propiedadesContentsde un elementoBasicDigitalTwin.BasicRelationship: representa genéricamente los datos principales de una relación.DigitalTwinsJsonPropertyName: contiene las constantes de cadena que se usan en la serialización y deserialización JSON para tipos de gemelos digitales personalizados.
Importación en bloque con la API de trabajos de importación
La API de trabajos de importación es una API de plano de datos que permite importar un conjunto de modelos, gemelos o relaciones en una sola llamada API. Las operaciones de la API de trabajos de importación también se incluyen con los comandos de la CLI y los SDK del plano de datos. El uso de la API de trabajos de importación requiere el uso de Azure Blob Storage.
Compruebe los permisos.
Para usar la API de trabajos de importación, deberá habilitar la configuración de permisos que se describe en esta sección.
En primer lugar, necesitará una identidad administrada asignada por el sistema para la instancia de Azure Digital Twins. Para obtener instrucciones para configurar una identidad administrada por el sistema para la instancia, consulte Habilitación o deshabilitación de una identidad administrada para la instancia.
Deberá tener permisos de escritura en la instancia de Azure Digital Twins para las siguientes categorías de acciones de datos:
Microsoft.DigitalTwins/jobs/*- Cualquier elemento de grafo que desee incluir en la llamada a trabajos. Esto puede incluir
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*oMicrosoft.DigitalTwins/digitaltwins/relationships/*.
El rol integrado que proporciona todos estos permisos es Propietario de datos de Azure Digital Twins. También puede usar un rol personalizado para conceder acceso granular solo a los tipos de datos que necesita. Para obtener más información sobre los roles de Azure Digital Twins, consulte Seguridad para las soluciones de Azure Digital Twins.
Nota:
Si intenta una llamada API de trabajos de importación y faltan permisos de escritura en uno de los tipos de elementos de grafos que intenta importar, el trabajo omitirá ese tipo e importará los demás. Por ejemplo, si tiene acceso de escritura a modelos y gemelos, pero no a las relaciones, un intento de importar en bloque los tres tipos de elemento solo se realizará correctamente en la importación de los modelos y gemelos. El estado del trabajo reflejará un error y el mensaje indicará qué permisos faltan.
También deberá conceder los siguientes permisos de RBAC a la identidad administrada asignada por el sistema de la instancia de Azure Digital Twins para que pueda acceder a los archivos de entrada y salida en el contenedor de Azure Blob Storage:
- Lector de datos de Blob Storage para el contenedor de blobs de entrada de Azure Storage
- Colaborador de datos de Storage Blob para el contenedor de blobs de salida de Azure Storage
Por último, genere un token de portador que se pueda usar en las solicitudes a la API de trabajos. Para obtener instrucciones, consulte Adición del token de portador.
Dar formato a los datos
La API acepta la entrada de información de grafos de un archivo NDJSON, que se debe cargar en un contenedor de Azure Blob Storage. El archivo comienza con una sección Header, seguida de las secciones opcionales Models, Twins y Relationships. No es necesario incluir los tres tipos de datos de grafos en el archivo, pero las secciones presentes deben seguir ese orden. Los gemelos y las relaciones creadas con esta API pueden incluir de manera opcional la inicialización de sus propiedades.
Este es un archivo de datos de entrada de ejemplo para la API de importación:
{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}
Sugerencia
Para ver un proyecto de ejemplo que convierte modelos, gemelos y relaciones en el NDJSON admitido por la API de importación, consulte Generador del NDJSON de importación en bloque de Azure Digital Twins. El proyecto de ejemplo está escrito para .NET y se puede descargar o adaptar para ayudarle a crear sus propios archivos de importación.
Una vez creado el archivo, cárguelo en un blob en bloques en Azure Blob Storage mediante su método de carga preferido (algunas opciones son el comando AzCopy, la CLI de Azure o Azure Portal). Usará la dirección URL de Blob Storage del archivo NDJSON en el cuerpo de la llamada API de trabajos de importación.
Ejecución del trabajo de importación
Ahora puede continuar con la llamada a la API de trabajos de importación. Para obtener instrucciones detalladas sobre cómo importar un grafo completo en una llamada API, consulte Carga de modelos, gemelos y relaciones en bloque con la API de trabajos de importación. También puede usar la API de trabajos de importación para importar cada tipo de recurso de manera independiente. Para obtener más información sobre el uso de la API de trabajos de importación con tipos de recursos individuales, consulte las instrucciones de la API de trabajos de importación para modelos, gemelos y relaciones.
En el cuerpo de la llamada API, proporcionará la dirección URL de Blob Storage del archivo de entrada NDJSON. También proporcionará una nueva dirección URL de Blob Storage para indicar dónde desea que se almacene el registro de salida una vez que el servicio lo cree.
Importante
Asegúrese de que la identidad administrada asignada por el sistema de la instancia de Azure Digital Twins tenga los permisos de RBAC de blob de almacenamiento descritos en la sección Comprobación de permisos.
A medida que se ejecuta el trabajo de importación, el servicio genera un registro de salida estructurado y se almacena como un nuevo blob anexo en el contenedor de blobs, en la ubicación de la dirección URL especificada para el blob de salida en la solicitud. Este es un registro de salida de ejemplo para un trabajo correcto que importa modelos, gemelos y relaciones:
{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}
Una vez completado el trabajo, puede ver el número total de entidades ingeridas mediante la métrica BulkOperationEntityCount.
También es posible cancelar un trabajo de importación en ejecución con la operación Cancelar desde la API de trabajos de importación. Cuando el trabajo se ha cancelado y ya no se está ejecutando, puede eliminarlo.
Límites y consideraciones
Tenga en cuenta las siguientes consideraciones al trabajar con la API de trabajos de importación:
- Los trabajos de importación no son operaciones atómicas. No hay ninguna reversión en caso de error, finalización parcial del trabajo o uso de la operación Cancelar.
- Solo se admite un trabajo en bloque a la vez dentro de una instancia de Azure Digital Twins. Puede ver esta información y otros límites numéricos de las API de trabajos en Límites de Azure Digital Twins.
Eliminación en bloque con la API de trabajos de eliminación
La API de trabajos de eliminación es una API de plano de datos que permite eliminar todos los modelos, gemelos y relaciones de una instancia con una sola llamada API. Las operaciones de la API de trabajos de eliminación también están disponibles como comandos de la CLI. Visite la documentación de la API para ver los detalles de la solicitud para crear un trabajo de eliminación y comprobar su estado.
Para asegurarse de que se eliminan todos los elementos, siga estas recomendaciones al usar la API de trabajos de eliminación:
- Para obtener instrucciones sobre cómo generar un token de portador para autenticar las solicitudes de API, consulte Adición del token de portador.
- Si ha importado recientemente un gran número de entidades al grafo, espere un tiempo y compruebe que todos los elementos estén sincronizados en el grafo antes de comenzar el trabajo de eliminación.
- Detenga todas las operaciones de la instancia, especialmente las operaciones de carga, hasta que se complete el trabajo de eliminación.
En función del tamaño del grafo que se va a eliminar, un trabajo de eliminación puede tardar entre unos minutos y varias horas.
El período de tiempo de espera predeterminado para un trabajo de eliminación es de 12 horas, que se puede ajustar a cualquier valor entre 15 minutos y 24 horas mediante un parámetro de consulta en la API. Esta es la cantidad de tiempo que se ejecutará el trabajo de eliminación antes de que se agote el tiempo de espera, momento en el que el servicio intentará detener el trabajo si aún no se ha completado.
Límites y otras consideraciones
Tenga en cuenta las siguientes consideraciones al trabajar con la API de trabajos de eliminación:
- Los trabajos de eliminación no son operaciones atómicas. No hay ninguna reversión en caso de error, finalización parcial del trabajo o tiempo de espera del trabajo.
- Solo se admite un trabajo en bloque a la vez dentro de una instancia de Azure Digital Twins. Puede ver esta información y otros límites numéricos de las API de trabajos en Límites de Azure Digital Twins.
Supervisión de las métricas de API
Las métricas de API, como las solicitudes, la latencia y la tasa de errores, se pueden ver en Azure Portal.
Para obtener información sobre cómo ver y administrar métricas de Azure Digital Twins, consulte Supervisión de la instancia. Para obtener una lista completa de las métricas de API disponibles para Azure Digital Twins, consulte Métricas de solicitudes API de Azure Digital Twins.
Pasos siguientes
Vea cómo hacer solicitudes directas a las API de Azure Digital Twins:
O bien, practique el uso del SDK de .NET mediante la creación de una aplicación cliente con este tutorial: