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 use, por lo que use las pestañas siguientes para seleccionar entre las API del plano de datos y del plano de control.

    Para obtener un token que se va a usar 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 otro inquilino de Microsoft Entra de la instancia, deberá solicitar un token desde el inquilino "home" 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.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

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. La configuración común puede simplificar considerablemente la autorización si planea crear más de una solicitud en 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 manera rápida de empezar a trabajar con Azure Digital Twins en Postman es importar una colección pregenerada de solicitudes 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. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. En la ventana Importar que aparece a continuación, seleccione Vincular 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.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

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

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

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.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

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.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  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.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    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.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  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 la captura de pantalla siguiente se muestra la API Add API de DigitalTwinModels. 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.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  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 cero. 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.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Elija un tipo de colección.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  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.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

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.

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

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

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

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.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

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.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Elija un tipo de Solicitud.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  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.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

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

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

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 POSThttps://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.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  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 del elemento 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:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    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. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

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.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

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.