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.
También se muestran los modelos de objetos de la API de administración.
Puede seleccionar cada modelo de objetos de la lista para obtener un resumen más detallado de los atributos clave.
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.
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.
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.
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.
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.
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.
Agregue el siguiente URI de redirección al registro de la aplicación de Azure Active Directory:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlNombre 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/swaggerActive 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.
Copie el Id. del cliente de la aplicación de Azure Active Directory.
Después de completar el registro de Azure Active Directory:
Seleccione el botón Autorizar botón en la página de Swagger.
Pegue el identificador de la aplicación en el campo client_id.
Se le redirigirá al siguiente cuadro de diálogo modal de operación correcta.
Para obtener más información sobre las solicitudes de pruebas interactivas protegidas por OAuth 2.0, lea la documentación oficial.
Pasos siguientes
Para más información sobre los modelos de objeto de Azure Digital Twins y el grafo de inteligencia espacial, lea Descripción de los modelos de objetos de Azure Digital Twins.
Para aprender cómo autenticar con Management API, lea Autenticación con las API.