Compartir a través de

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

  • Artículo

Postman es una herramienta de pruebas REST que proporciona funcionalidades clave de solicitud HTTP en una interfaz gráfica de usuario basada en escritorio y complementos. Puede usarla para elaborar solicitudes HTTP y enviarlas a las API REST de Azure Digital Twins. En este artículo se describe cómo configurar el cliente REST de Postman para interactuar con las API de Azure Digital Twins. Esta información es específica del servicio Azure Digital Twins.

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

  1. Use la CLI de Azure para obtener un token de portador que se usará para realizar solicitudes de API en Postman.
  2. Configure una colección de Postman y el cliente de REST de Postman para que use el token de portador para la autenticación. Al configurar la colección, puede elegir cualquiera de estas opciones:
    1. Importar una colección precompilada de solicitudes de Azure Digital Twins API.
    2. Crear su propia colección desde cero.
  3. Agregar solicitudes a la colección configurada y enviarlas a Azure Digital Twins API.

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 información de ambos conjuntos de API.

Requisitos previos

Para continuar con el uso de Postman para acceder a las API de Azure Digital Twins, es preciso configurar una instancia de Azure Digital Twins y descargar Postman. El resto de esta sección le guía a través de 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.

Descargue Postman.

A continuación, descargue la versión de escritorio del cliente de Postman.

Obtención de un token de portador

Ahora que ha configurado Postman y su instancia de Azure Digital Twins, deberá obtener un token de portador que las solicitudes de Postman puedan usar para la autorización en las API de Azure Digital Twins.

Este token se puede obtener de varias formas. En este artículo se usa la CLI de Azure para iniciar sesión en su cuenta de Azure y obtener 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 apropiadas. 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, pasará 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.

    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

    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, necesitará 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 y guárdelo para usarlo en la siguiente sección. Este es el valor del token que proporcionará a Postman para autenticar las solicitudes.

    Recorte de pantalla de la consola que muestra el resultado del comando az account get-access-token. Campo accessToken con su valor de ejemplo resaltado.

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.

A continuación, configurará Postman para usar este token y realizar solicitudes de API a Azure Digital Twins.

Acerca de las colecciones de Postman

En Postman, las solicitudes se guardan en colecciones (grupos de solicitudes). Al crear una colección para agrupar las solicitudes, puede aplicar una configuración común a muchas solicitudes a la vez. Los ajustes comunes pueden simplificar considerablemente la autorización si planea crear más de una solicitud con las API de Azure Digital Twins, ya que solo tiene que configurar estos detalles una vez para toda la colección.

Al trabajar con Azure Digital Twins, puede empezar importando una colección precompilada de todas las solicitudes de Azure Digital Twins. Es posible que quiera importar esta colección si está explorando las API y quiere configurar un proyecto rápidamente con ejemplos de solicitudes.

Como alternativa, también puede empezar desde cero creando su propia colección vacía y rellenándola con solicitudes individuales que solo llamen a las API que necesite.

Las siguientes secciones describen ambos procesos. El resto del artículo se lleva a cabo en la aplicación Postman local, por lo que debe abrirla en el equipo.

Importación de la colección de API de Azure Digital Twins

Una forma rápida de comenzar a usar Azure Digital Twins en Postman es importar una colección de solicitudes predefinidas para las API. Siga los pasos siguientes para importar una colección de solicitudes populares de API del plano de datos de Azure Digital Twins que contienen datos de solicitud de ejemplo.

  1. En la ventana principal de Postman, seleccione el botón Importar. Recorte de pantalla de una ventana de Postman recién abierta. El botón

  2. En la ventana Importar siguiente, seleccione Vínculo y escriba la siguiente dirección URL: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. A continuación, seleccione Importar para confirmar.

    Captura de pantalla de la ventana

La colección recién importada se puede ver desde la vista principal de Postman, en la pestaña Colecciones.

Recorte de pantalla de la ventana principal de Postman. La colección recién importada está resaltada en la pestaña

Sugerencia

Para importar el conjunto completo de llamadas API para una determinada versión de las API de Azure Digital Twins (incluido el plano de control o el plano de datos), también puede importar archivos de Swagger como colecciones. Para obtener vínculos a los archivos de Swagger para las API del plano de control y del plano de datos, consulte API y SDK de Azure Digital Twins.

A continuación, vaya a la sección siguiente para agregar un token de portador a la colección para la autorización y conectarlo a la instancia de Azure Digital Twins.

Configuración de la autorización

A continuación, edite la colección que ha creado para configurar algunos detalles de acceso. Resalte la colección que ha creado y seleccione el icono Ver más acciones para mostrar las opciones de acción. Seleccione Editar.

Recrte de pantalla de Postman. El icono

Siga estos pasos para agregar un token de portador a la colección para la autorización. Use el valor del token que apuntó en la sección Obtención de un token de portador para usarlo en todas las solicitudes de API de la colección.

  1. En el cuadro de diálogo Editar de la colección, asegúrese de que se encuentra en la pestaña Autorización.

    Captura de pantalla del cuadro de diálogo de edición de la colección importada en Postman, que muestra la pestaña

  2. Establezca el tipo en OAuth 2.0 y pegue el token de acceso en el cuadro Token de acceso. Debe usar el token correcto para el tipo de API que usa, ya que hay diferentes tokens para las API del plano de datos frente a las API del plano de control. Seleccione Guardar.

    Recorte de pantalla del cuadro de diálogo de edición de Postman para la colección importada, en la pestaña

    Sugerencia

    Puede optar por activar el uso compartido de tokens si desea almacenar el token con la solicitud en la nube de Postman y, posiblemente, compartir el token con otros usuarios.

Otra configuración

Puede ayudar a que la recopilación se conecte fácilmente a los recursos de Azure Digital Twins estableciendo algunas variables proporcionadas con la colección. Cuando muchas solicitudes de una colección necesitan el mismo valor (como el nombre de host de la instancia de Azure Digital Twins), puede almacenar el valor en una variable que se aplique a todas las solicitudes de la colección. La colección de Azure Digital Twins incluye variables creadas previamente que puede establecer en el nivel de colección.

  1. Asimismo, en el cuadro de diálogo Editar de la colección, desplácese a la pestaña Variables.

  2. Use la tabla siguiente para establecer los valores de las variables de la colección:

    Variable Conjunto de API Descripción
    digitaltwins-hostname Plano de datos el nombre de host de la instancia de Azure Digital Twins. Puede encontrar este valor en la página de información general de la instancia en el portal.
    subscriptionId Plano de control Su identificador de suscripción de Azure.
    digitalTwinInstance Plano de control Nombre de la instancia de Azure Digital Twins.

    Recorte de pantalla del cuadro de diálogo de edición de la colección importada en Postman, que muestra la pestaña

  3. Si la colección tiene variables adicionales, rellene y guarde también esos valores.

  4. Seleccione Guardar.

Cuando haya terminado con los pasos anteriores, habrá terminado de configurar la colección. Si lo desea, puede cerrar la pestaña de edición de la colección.

Exploración de solicitudes

A continuación, explore las solicitudes de la colección de API de Azure Digital Twins. Puede expandir la colección para ver las solicitudes creadas previamente (ordenadas por categoría de operación).

Las distintas solicitudes requieren información diferente sobre su instancia y sus datos. Para ver toda la información necesaria para elaborar una solicitud determinada, consulte los detalles de la solicitud en la documentación de referencia de la API de REST de Azure Digital Twins.

Puede editar los detalles de una solicitud en la colección de Postman mediante estos pasos:

  1. Selecciónela en la lista para extraer sus detalles editables.

  2. La mayoría de las solicitudes de la colección de muestras están preconfiguradas para ejecutarse sin realizar más cambios.

  3. En el recorte de pantalla siguiente se muestra la API DigitalTwinModels Add. En la pestaña Cuerpo puede ver la carga JSON que define el nuevo modelo que se va a agregar:

  4. Rellene los valores de las variables que aparecen en la pestaña Parámetros en Variables de la ruta de acceso.

    Recrte de pantalla de Postman. La colección se expande para mostrar la pestaña cuerpo de una solicitud.

  5. Para ejecutar la solicitud, use el botón Enviar.

También puede agregar sus propias solicitudes a la colección mediante el proceso descrito en la sección Agregar una solicitud individual.

Creación de sus propias colecciones

En lugar de importar la colección existente de las API de Azure Digital Twins, también puede crear su propia colección desde el principio. A continuación, puede rellenarla con solicitudes individuales mediante la documentación de referencia de la API de REST de Azure Digital Twins.

Crear una colección Postman

  1. Para crear una colección, seleccione el botón Nueva en la ventana principal de Postman.

    Recorte de pantalla de la ventana principal de Postman. El botón

    Elija un tipo de colección.

    Recorte de pantalla del cuadro de diálogo

  2. Se abre una pestaña. Rellene los detalles de la colección nueva. Seleccione el icono de edición situado junto al nombre predeterminado de la colección (Nueva colección) para reemplazarlo por un nombre de su elección.

    Recorte de pantalla del cuadro de diálogo de edición de la nueva colección en Postman. El icono Editar junto al nombre

Luego, vaya a la sección siguiente para agregar un token de portador a la colección para la autorización.

Configuración de la autorización

Siga estos pasos para agregar un token de portador a la colección para la autorización. Use el valor del token que apuntó en la sección Obtención de un token de portador para usarlo en todas las solicitudes de API de la colección.

  1. Todavía en el cuadro de diálogo Editar de la nueva colección, vaya a la pestaña Autorización.

    Captura de pantalla del cuadro de diálogo de edición de la nueva colección en Postman, que muestra la pestaña

  2. Establezca el tipo en OAuth 2.0 y pegue el token de acceso en el cuadro Token de acceso y seleccione Guardar.

    Recorte de pantalla del cuadro de diálogo de edición de Postman para la nueva colección, en la pestaña

Cuando haya terminado con los pasos anteriores, habrá terminado de configurar la colección. Si lo desea, puede cerrar la pestaña de edición de la colección nueva.

La nueva colección se puede ver desde la vista principal de Postman, en la pestaña Colecciones.

Recorte de pantalla de la ventana principal de Postman. La colección personalizada recién creada está resaltada en la pestaña

Adición de una solicitud individual

Ahora que la colección está configurada, puede agregar sus propias solicitudes a las API de Azure Digital Twins.

  1. Para crear una solicitud, pulse el botón Nueva.

    Recorte de pantalla de la ventana principal de Postman. El botón

    Elija un tipo de Solicitud.

    Recorte de pantalla del cuadro de diálogo

  2. Esta acción abre la ventana GUARDAR SOLICITUD, donde puede especificar el nombre de la solicitud, darle una descripción opcional y elegir la colección de la que forma parte. Rellene los detalles y guarde la solicitud en la colección que creó anteriormente.

Recorte de pantalla de la ventana

Ahora puede ver la solicitud en la colección y seleccionarla para extraer sus detalles editables.

Recrte de pantalla de Postman. La colección Azure Digital Twins se amplía para mostrar los detalles de la solicitud.

Establecimiento de los detalles de la solicitud

Para realizar una solicitud de Postman en una de las API de Azure Digital Twins, necesitará la dirección URL de la API e información sobre los detalles que requiere. Esta información se puede encontrar en la documentación de referencia de la API REST de Azure Digital Twins.

Para continuar con una consulta de ejemplo, en este artículo se usará la API de consulta de Azure Digital Twins para consultar todos los gemelos digitales de una instancia.

  1. Obtenga la dirección URL y el tipo de la solicitud en la documentación de referencia. En el caso de la API de consulta, actualmente es POST https://digitaltwins-host-name/query?api-version=2020-10-31.

  2. En Postman, establezca el tipo de la solicitud y escriba la dirección URL de la solicitud, rellenando los marcadores de posición en la dirección URL según sea necesario. Use el nombre de host de la instancia de la sección de requisitos previos.

    Recorte de pantalla de los detalles de la nueva solicitud en Postman. La dirección URL de la documentación de referencia se ha rellenado en el cuadro de la dirección URL de la solicitud.

  3. Compruebe que los parámetros que se muestran para la solicitud en la pestaña Params (Parámetros) coinciden con los descritos en la documentación de referencia. En el caso de esta solicitud en Postman, el parámetro api-version se rellenó automáticamente al escribir la dirección URL de la solicitud en el paso anterior. Para Query API, este es el único parámetro necesario, por lo que este paso ha terminado.

  4. En la pestaña Autorización, establezca el tipo en Heredar autenticación de primario. Esto indica que esta solicitud usará la autorización que configuró anteriormente para toda la colección.

  5. Compruebe que los encabezados que se muestran para la solicitud en la pestaña Headers (Encabezados) coinciden con los descritos en la documentación de referencia. Para esta solicitud, se han rellenado automáticamente varios encabezados. Para Query API, no se requiere ninguna de las opciones de encabezado, por lo que este paso ha finalizado.

  6. Compruebe que el cuerpo que se muestra para la solicitud en la pestaña Body (Cuerpo) coincide con las necesidades descritas en la documentación de referencia. Para Query API, se requiere un cuerpo JSON que proporcione el texto de la consulta. Este es un cuerpo de ejemplo para esta solicitud que consulta todos los gemelos digitales de la instancia:

    Recorte de pantalla de los detalles de la nueva solicitud en Postman, en la pestaña Cuerpo. Contiene un cuerpo JSON sin formato con una consulta de

    Para obtener más información sobre cómo crear consultas de Azure Digital Twins, consulte Consulta del grafo de gemelos.

  7. Consulte en la documentación de referencia otros campos que pueden ser necesarios para su tipo de solicitud. En el caso de Query API, ahora se han cumplido todos los requisitos en la solicitud de Postman, por lo que este paso ha finalizado.

  8. Use el botón Send (Enviar) para enviar la solicitud completada. Recorte de pantalla de Postman que muestra los detalles de la nueva solicitud. El botón Enviar está resaltado.

Después de enviar la solicitud, los detalles de la respuesta aparecerán en la ventana de Postman debajo de la solicitud. Puede ver el código de estado de la respuesta y cualquier texto del cuerpo.

Recorte de pantalla de la solicitud enviada en Postman. Debajo de los detalles de la solicitud, se muestra la respuesta. El estado es

También puede comparar la respuesta con los datos de respuesta esperados que se proporcionan en la documentación de referencia para comprobar el resultado u obtener más información sobre los errores que surjan.

Pasos siguientes

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.