API y 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 (mediante una herramienta como Postman) 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 ejercer las API del plano de control mediante la interacción con Azure Digital Twins a través del 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 de trabajos permite administrar una acción asincrónica de larga duración para importar modelos, gemelos y relaciones de forma masiva.
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 ejercer las API del plano de datos mediante la interacción con Azure Digital Twins a través de la CLI.
Notas de uso
Esta sección contiene información más detallada sobre el uso de las API y los SDK.
Aquí tiene información de carácter general:
- El SDK subyacente es
Azure.Core. Consulte la documentación del espacio de nombres de Azure como referencia sobre los tipos y la infraestructura del SDK. - Puede usar una herramienta de prueba de REST de HTTP como Postman 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 mediante Postman.
- 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.
Aquí tiene algunos detalles sobre la autenticación:
- Para usar el SDK, 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. - Las solicitudes a las API de Azure Digital Twins requieren un usuario o una entidad de servicio que forme parte del mismo inquilino de Azure Active Directory (Azure AD) donde existe 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 Azure AD 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.
Aquí tiene algunos detalles 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 masiva con la API de trabajos
Jobs API 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 API de trabajos también se incluyen con los comandos de la CLI y los SDK del plano de datos. El uso de jobs API requiere el uso de Azure Blob Storage.
Compruebe los permisos.
Para usar la API de trabajos, 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 la 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 Trabajos. Esto puede incluir
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*y/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 más información sobre los roles en Azure Digital Twins, consulte Seguridad para soluciones de Azure Digital Twins.
Nota
Si intenta realizar una llamada api de trabajos y faltan permisos de escritura en uno de los tipos de elementos de grafo 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 relaciones, un intento de importación masiva de 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.
Por último, 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 Storage Blob 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
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 Header sección, seguida de las secciones opcionales Models, Twinsy Relationships. No es necesario incluir los tres tipos de datos de grafos en el archivo, pero las secciones que estén presentes deben seguir ese orden. Los gemelos y las relaciones creados con esta API pueden incluir opcionalmente 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 compatible con la API de importación, consulte Generador de NDJSON de importación masiva de NDJSON 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 el método de carga preferido (algunas opciones son el comando AzCopy, la CLI de Azure o el Azure Portal). Usará la dirección URL de almacenamiento de blobs del archivo NDJSON en el cuerpo de la llamada API de trabajos.
Ejecución del trabajo de importación
Ahora puede continuar con la llamada a la API de trabajos. Para obtener instrucciones detalladas sobre cómo importar un grafo completo en una llamada API, consulte Carga de modelos, gemelos y relaciones de forma masiva con jobs API. También puede usar jobs API para importar cada tipo de recurso de forma independiente. Para más información sobre el uso de jobs API con tipos de recursos individuales, consulte Instrucciones de api de trabajos para modelos, gemelos y relaciones.
En el cuerpo de la llamada API, proporcionará la dirección URL de almacenamiento de blobs 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 tiene los permisos de RBAC del blob de almacenamiento que se describen en la sección Comprobar 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 en anexos en el contenedor de blobs, en la ubicación de la dirección URL que especificó para el blob de salida en la solicitud. Este es un registro de salida de ejemplo para un trabajo correcto importando 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 jobs API. Una vez cancelado el trabajo 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:
- Actualmente, la API de trabajos solo admite operaciones de "creació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 de importación masiva a la vez dentro de una instancia de Azure Digital Twins. Puede ver esta información y otros límites numéricos de jobs API en los 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 más 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 mediante Postman:
O bien, practique el uso del SDK de .NET mediante la creación de una aplicación cliente con este tutorial: