Envío de solicitudes a las API de Azure Digital Twins mediante Visual Studio

Visual Studio 2022 admite archivos .http, que se pueden usar para estructurar, almacenar y enviar directamente solicitudes HTTP desde la aplicación. El uso de esta funcionalidad de Visual Studio es una manera de crear solicitudes HTTP y enviarlas a las API de REST de Azure Digital Twins. En este artículo se describe cómo configurar un archivo .http en Visual Studio que puede interactuar con las API de Azure Digital Twins.

Este artículo contiene información sobre los pasos siguientes:

1. Configure un proyecto y un archivo .http de Visual Studio, con variables que representan la instancia de Azure Digital Twins.
2. Use la CLI de Azure para obtener un token de portador que puede usar para realizar solicitudes de API en Visual Studio.
3. Use la documentación de la API de REST de Azure Digital Twins como recurso para crear solicitudes en el archivo .http y enviarlas a las API de Azure Digital Twins.

Azure Digital Twins tiene dos conjuntos de API con los que puede trabajar: el plano de datos y el plano de control. Para obtener más información sobre la diferencia entre estos conjuntos de API, consulte API y SDK de Azure Digital Twins. Este artículo contiene instrucciones para ambos conjuntos de API.

Para obtener más información sobre la compatibilidad con archivos .http en Visual Studio, consulte Uso de archivos .http en Visual Studio 2022.

Requisitos previos

Para realizar solicitudes a las API de Azure Digital Twins mediante Visual Studio, debe configurar una instancia de Azure Digital Twins y descargar Visual Studio 2022. Esta sección es para estos pasos.

Configuración de la instancia de Azure Digital Twins

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.

Descarga de Visual Studio 2022

A continuación, descargue Visual Studio 2022. Asegúrese de incluir la carga de trabajo ASP.NET y de desarrollo web en la instalación.

Configuración del proyecto de Visual Studio

En esta sección, configurará el proyecto en Visual Studio que se usará para crear solicitudes HTTP.

Abra Visual Studio en el equipo y cree un nuevo proyecto. Use la plantilla de proyecto ASP.NET Core Empty.

Siga las instrucciones de Crear un archivo .http para crear un nuevo archivo .http en el proyecto.

Agregar variables

A continuación, agregue algunas variables en la parte superior del archivo .http que se usará para conectarse al recurso de Azure Digital Twins.

El conjunto de variables necesario depende del conjunto de API que esté usando, por lo que debe usar las pestañas siguientes para seleccionar entre las API del plano de datos y del plano de control.

Plano de datos

Agregue las siguientes variables para las solicitudes del plano de datos. Hay un marcador de posición para el nombre de host de la instancia de Azure Digital Twins (termina en digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Plano de control

Agregue las siguientes variables para las solicitudes del plano de control. Contienen marcadores de posición para los valores de recursos.

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

Adición de un token de portador

Ahora que ha configurado la instancia de Azure Digital Twins y el proyecto de Visual Studio, debe obtener un token de portador que las solicitudes HTTP pueden usar para autorizarse en las API de Azure Digital Twins.

Hay varias maneras de obtener este token. En este artículo se usa la CLI de Azure para iniciar sesión en su cuenta de Azure y obtener así un token.

Si tiene una CLI de Azure instalada localmente, puede iniciar un símbolo del sistema en la máquina para ejecutar los siguientes comandos. De lo contrario, puede abrir una ventana de Azure Cloud Shell en el explorador y ejecutar los comandos en ella.

1. En primer lugar, asegúrese de que ha iniciado sesión en Azure con las credenciales correctas. Para ello, ejecute este comando:

   az login
   

2. Luego, use el comando az account get-access-token para obtener un token de portador con acceso al servicio Azure Digital Twins. En este comando, pasa el id. de recurso del punto de conexión del servicio Azure Digital Twins, con el fin de obtener un token de acceso que pueda acceder a los recursos de Azure Digital Twins.

   El contexto necesario para el token depende del conjunto de API que esté usando, por lo que debe usar las pestañas siguientes para seleccionar entre las API del plano de datos y del plano de control.

   Plano de datos

   Para obtener un token y usarlo con las API del plano de datos, use el siguiente valor estático para el contexto del token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Este valor es el identificador de recurso del punto de conexión del servicio Azure Digital Twins.

   az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0
   

   Plano de control

   Para obtener un token que se va a usar con las API del plano de control, use el siguiente valor para el contexto del token: https://management.azure.com/.

   az account get-access-token --resource https://management.azure.com/
   

   Nota:

   Si necesita acceder a la instancia de Azure Digital Twins mediante una entidad de servicio o una cuenta de usuario que pertenezca a un inquilino distinto de Microsoft Entra de la instancia, necesita solicitar un token del inquilino "principal" de la instancia de Azure Digital Twins. Para obtener más información sobre este proceso, consulte Escritura de código de autenticación de aplicación.

3. Copie el valor de accessToken en el resultado. Este valor es el valor de token que pegará en Visual Studio para autorizar las solicitudes.

   

Sugerencia

Este token es válido durante un mínimo de 5 minutos y un máximo de 60. Si se agota el tiempo asignado al token actual, puede repetir los pasos de esta sección para obtener uno nuevo.

Adición de un token al archivo .http

En el archivo .http de Visual Studio, agregue otra variable que contenga el valor del token.

Plano de datos

@token=<paste-data-plane-token>

Las variables deben tener ahora un aspecto similar al siguiente:

Plano de control

@token=<paste-control-plane-token>

Las variables deben tener ahora un aspecto similar al siguiente:

Adición de solicitudes

Ahora que el archivo .http está configurado, puede agregar solicitudes a las API de Azure Digital Twin.

Para empezar, abra la referencia de la API de REST de Azure Digital Twins. Esta documentación contiene detalles de todas las operaciones cubiertas por las API. Vaya a la página de referencia de la solicitud que desea ejecutar.

En este artículo se usará la API de actualización de DigitalTwins desde el plano de datos como ejemplo.

1. Agregar plantilla de solicitud: copie la solicitud HTTP que se muestra en la documentación de referencia.

   

   En Visual Studio, pegue la solicitud en una nueva línea debajo de las variables del archivo .http.

2. Agregar parámetros: examine la sección Parámetros de URI de la documentación de referencia para ver qué valores de parámetro necesita la solicitud. Puede reemplazar algunas por las variables que creó anteriormente y rellenar otros valores de parámetro según corresponda. Para hacer referencia a una variable, coloque el nombre de la variable en llaves dobles, como {{variable}}. Para más información, consulte Variables.

   Nota:

   En el caso de las solicitudes del plano de datos, digitaltwins-hostname también es un parámetro. Reemplace esto por {{hostName}} para usar el valor de la variable de nombre de host.

   Este es el aspecto de este paso en una solicitud de ejemplo:

   

3. Agregar autorización: agregue la siguiente línea (exactamente como está escrita) directamente debajo de la solicitud, para especificar la autenticación con la variable de token de portador.

   Authorization: Bearer {{token}}
   

   Este es el aspecto de este paso en una solicitud de ejemplo:

   

4. Agregar encabezados adicionales: examine la sección Encabezado de solicitud de la documentación de referencia para ver qué valores de encabezado pueden acompañar a la solicitud. También puede incluir encabezados HTTP tradicionales, como Content-Type. Agregue cada encabezado en su propia línea con el formato HeaderName: Value. Para obtener más información, consulte Encabezados de solicitud.

   Este es el aspecto de este paso en una solicitud de ejemplo:

   

5. Agregar cuerpo: examine la sección Cuerpo de la solicitud de la documentación de referencia para ver qué información del cuerpo podría necesitar la solicitud. Agregue el cuerpo de la solicitud después de una línea en blanco. Para obtener más información, consulte Cuerpo de la solicitud.

   Este es el aspecto de este paso en una solicitud de ejemplo:

6. Cuando la solicitud esté lista, seleccione Enviar solicitud encima de la solicitud para enviarla.

   

Visual Studio abre un panel con los detalles de la respuesta. Examine la sección Respuestas de la documentación de referencia para interpretar el código de estado y los datos del cuerpo de la respuesta.

Adición de solicitudes adicionales

Para agregar más solicitudes al archivo .http, separe con ### como delimitador.

Pasos siguientes

Para obtener más información sobre el envío de solicitudes con archivos .http en Visual Studio, incluidos los detalles de sintaxis y los escenarios avanzados, consulte Uso de archivos .http en Visual Studio 2022.

Para obtener más información sobre las API de Digital Twins, lea API y SDK de Azure Digital Twins o consulte la documentación de referencia de las API REST.