API y SDK de Azure Digital Twins

  • Artículo
  • 9 minutos para leer

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. Los SDK de plano de control están disponibles en .NET (C#) y Java, mientras que los SDK de plano de datos están disponibles en .NET (C#), Java, JavaScript y Python.

Información general: 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.

La versión más reciente de la API de plano de control es 2020-12-01.

Para usar las API de plano de control:

También puede ejercitar las API de plano de control interactuando con Azure Digital Twins mediante Azure Portal y la CLI.

Información general: 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 las 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 las 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 buscar conjuntos de gemelos digitales en el grafo de gemelos entre las relaciones.
  • Event Routes: la categoría Event Routes contiene las API para enrutar datos, en el sistema y a los servicios de bajada.

La versión más actual de la API de plano de datos es 2020-10-31.

Para usar las API de plano de datos:

También puede probar las API de plano de fecha interactuando con Azure Digital Twins a través de la CLI.

SDK de .NET (C#) (plano de datos)

El SDK de .NET (C#) para Azure Digital Twins forma parte del SDK de Azure para .NET. Es de código abierto y se basa en las API del plano de datos de Azure Digital Twins.

Nota

Para más información sobre el diseño del SDK, consulte los principios de diseño generales para los SDK de Azure y las directrices de diseño de .NET específicas.

Para usar el SDK, incluya el paquete NuGet Azure.DigitalTwins.Core con el proyecto. También necesitará la versión más reciente del paquete Azure.Identity. En Visual Studio, puede agregar estos paquetes con el administrador de paquetes NuGet (al que se accede a través de Herramientas > Administrador de paquetes NuGet > Administrar paquetes NuGet para la solución). También puede usar la herramienta de línea de comandos de .NET con los comandos que se encuentran en los siguientes vínculos de paquetes NuGet para agregarlos al proyecto:

Para un tutorial detallado sobre el uso de las API en la práctica, consulte Programación de una aplicación cliente.

Asistentes de serialización

Las aplicaciones auxiliares de serialización son funciones auxiliares disponibles en el SDK 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 propiedades Contents de un elemento BasicDigitalTwin.
  • 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.

Notas generales sobre el uso de la API o del SDK

Nota

Tenga en cuenta que Azure Digital Twins no admite actualmente el uso compartido de recursos entre orígenes (CORS) . Para más información sobre las estrategias de impacto y resolución, consulte la sección Uso compartido de recursos entre orígenes (CORS) de Conceptos: Seguridad para las soluciones de Azure Digital Twins.

En la lista siguiente se proporcionan más detalles y directrices generales para usar las API y los 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 Realización de solicitudes de API con Postman.
  • 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 de Azure.Identity. Para más información sobre Azure.Identity, consulte la documentación del espacio de nombres.
  • Es posible que encuentre útil InteractiveBrowserCredential al 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 sobre InteractiveBrowserCredential, 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.
  • 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 try y de capturar al menos RequestFailedExceptions. 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), donde T es 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 campo Value.
  • Los métodos de servicio con los resultados paginados devuelven Pageable<T> o AsyncPageable<T> como resultados. Para más información sobre la clase Pageable<T>, vea su documentación de referencia; para más información sobre AsyncPageable<T>, vea su documentación de referencia.
  • Puede recorrer en iteración los resultados paginados mediante un bucle await foreach. Para más información sobre este proceso, consulte la documentación pertinente.
  • 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.

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.

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.

En la página principal del portal, busque la instancia de Azure Digital Twins para ver sus detalles. Seleccione la opción Métricas en el menú de la instancia de Azure Digital Twins para abrir la página Métricas.

Captura de pantalla que muestra la página de métricas de Azure Digital Twins

Desde aquí, puede ver las métricas de la instancia y crear vistas personalizadas.

Pasos siguientes

Vea cómo se hacen solicitudes directas a las API mediante Postman:

O bien, practique el uso del SDK de .NET mediante la creación de una aplicación cliente con este tutorial: