Compartir a través de


Documentación de referencia de Swagger de Azure Digital Twins

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades ampliadas del nuevo servicio, se ha retirado el servicio Azure Digital Twins original (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

Cada instancia aprovisionada de Azure Digital Twins incluye su propia documentación de referencia de Swagger generada automáticamente.

Swagger (u OpenAPI) reúne información compleja de las API en un recurso de referencia interactivo e independiente del lenguaje. Swagger proporciona material de referencia crítico sobre qué cargas JSON, métodos HTTP y puntos de conexión concretos se deben usar para realizar operaciones en una API.

Resumen de Swagger

Swagger proporciona un resumen interactivo de la API, en el que se incluye:

  • Información de la API y del modelo de objetos.
  • Los puntos de conexión de API REST con especificación de las cargas de solicitud necesarias, encabezados, parámetros, las rutas de acceso de contexto y los métodos HTTP.
  • Pruebas de las funcionalidades de la API.
  • Información de respuesta de ejemplo usada para comprobar y confirmar las respuestas HTTP.
  • Información de código de error.

Swagger es una herramienta muy útil para ayudar con el desarrollo y las pruebas de las llamadas realizadas a Management API de Azure Digital Twins.

Sugerencia

Se proporciona un preestreno de Swagger para demostrar el conjunto de características de la API. Se hospeda en docs.westcentralus.azuresmartspaces.net/management/swagger.

Puede acceder a su propia documentación de Management API generada con Swagger en:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
Nombre Reemplazar por
YOUR_INSTANCE_NAME El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION La región de servidor en la que está hospedada la instancia

Material de referencia

El material de referencia de Swagger generado automáticamente proporciona una introducción rápida a los conceptos importantes, puntos de conexión de API de administración disponibles, así como una descripción de cada modelo de objetos para ayudar en el desarrollo y las pruebas.

Un breve resumen describe la API.

Información general de resumen y API de Swagger

También se muestran los modelos de objetos de la API de administración.

Modelos de Swagger enumerados en la parte inferior de la interfaz de usuario de Swagger

Puede seleccionar cada modelo de objetos de la lista para obtener un resumen más detallado de los atributos clave.

Modelos de Swagger expandidos para leer el contenido de los modelos

Los modelos de objetos de Swagger generados resultan prácticos para leer todos los objetos y las API de Azure Digital Twins que están disponibles. Los desarrolladores utilizar recurso al crear soluciones en Azure Digital Twins.

Resumen de puntos de conexión

Swagger también proporciona un resumen exhaustivo de todos los puntos de conexión que componen las API de administración.

Cada punto de conexión de la lista también incluye la información de solicitud necesaria, como:

  • Parámetros obligatorios.
  • Tipos de datos de parámetro obligatorios.
  • Método HTTP para acceder al recurso.

Puntos de conexión de Swagger mostrados en la interfaz de usuario de Swagger

Seleccione cada uno de los recursos para mostrar su contenido adicional y obtener información general más detallada.

Uso de Swagger para probar los puntos de conexión

Una de las funcionalidades más eficaces de Swagger proporciona la capacidad de probar un punto de conexión de la API directamente mediante la interfaz de usuario de la documentación.

Después de seleccionar un punto de conexión específico, se mostrará el botón Probar.

Botón Probar de Swagger

Al expandir esa sección se muestran los campos de entrada para cada parámetro obligatorio y opcional. Escriba los valores correctos y seleccione Ejecución.

Ejemplo de resultado de la prueba de Swagger

Después de ejecutar la prueba, puede comprobar los datos de respuesta.

Datos de respuesta de Swagger

Cada punto de conexión en la lista también incluye datos del cuerpo de respuesta para comprobar desarrollo y pruebas. Estos ejemplos incluyen los códigos de estado y JSON para las solicitudes correctas de HTTP.

Ejemplo de respuesta JSON de Swagger

Los ejemplos incluyen también los códigos de error para ayudar a depurar o mejorar los errores de las pruebas.

Autorización de Swagger OAuth 2.0

Nota

  • La entidad de seguridad de usuario que creó el recurso de Azure Digital Twins tendrá una asignación del rol Administrador de espacio y podrá crear asignaciones de roles adicionales para otros usuarios. Estos usuarios y sus roles se pueden autorizar para llamar a las API.
  1. Siga los pasos de la guía de inicio rápido para crear y configurar una aplicación de Azure Active Directory. También puede volver a usar un registro de aplicación existente.

  2. Agregue el siguiente URI de redirección al registro de la aplicación de Azure Active Directory:

    Registrar la dirección URL de redireccionamiento de Swagger en AAD

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    
    Nombre Reemplazar por Ejemplo
    YOUR_SWAGGER_URL La dirección URL de documentación de API REST de administración que se encuentra en el portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
  3. Active la casilla Tokens deacceso de concesión> implícita para permitir que se use el flujo de concesión implícita de OAuth 2.0. Seleccione Configurar y, a continuación, Guardar.

  4. Copie el Id. del cliente de la aplicación de Azure Active Directory.

Después de completar el registro de Azure Active Directory:

  1. Seleccione el botón Autorizar botón en la página de Swagger.

    Seleccione el botón Autorizar de Swagger.

  2. Pegue el identificador de la aplicación en el campo client_id.

    Campo client_id swagger

  3. Se le redirigirá al siguiente cuadro de diálogo modal de operación correcta.

    Modal de redirección de Swagger

Para obtener más información sobre las solicitudes de pruebas interactivas protegidas por OAuth 2.0, lea la documentación oficial.

Pasos siguientes