Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Integración de la especificación OpenAPI
Con la integración de las especificaciones de OpenAPI, puede crear integraciones personalizadas basadas en esquemas de OpenAPI. Esto le permite conectarse a cualquier API que proporcione una especificación de OpenAPI. Esta integración solo admite la ejecución de acciones y requiere el nivel Amazon Quick Pro o superior.
Qué puede hacer
La integración de las especificaciones de OpenAPI proporciona conectividad basada en esquemas para ayudarle a trabajar con soluciones personalizadas. APIs
- Conector de acción
-
Realice acciones según las especificaciones de OpenAPI. Ejecute llamadas a la API, gestione los recursos e interactúe con servicios personalizados mediante acciones generadas dinámicamente en función del esquema proporcionado.
- Configuración basada en esquemas
-
Importe las especificaciones de OpenAPI para generar automáticamente las acciones y acciones disponibles. Support para la validación de esquemas JSON y el mapeo de parámetros.
Antes de empezar
Antes de configurar la integración de las especificaciones de OpenAPI, asegúrese de tener lo siguiente:
-
Especificación de OpenAPI (versión 3.0.0 o superior) para la API de destino.
-
Credenciales de autenticación de la API (clave de OAuth API u otra).
-
Amazon Quick Author o superior.
-
Documentación de la API y acceso al punto final.
Preparar la especificación y la autenticación de OpenAPI
Antes de configurar la integración en Amazon Quick, prepare la especificación de OpenAPI y las credenciales de autenticación. Su especificación de OpenAPI debe cumplir requisitos específicos para una integración satisfactoria.
Requisitos básicos
La especificación de OpenAPI debe cumplir estos requisitos básicos.
-
Versión OpenAPI: se requiere la versión 3.0.0 o superior.
-
Formato de archivo: solo formato JSON (application/json).
-
Límite de tamaño de archivo: máximo 1 MB para toda la especificación de OpenAPI.
-
Límite de operación: mínimo 1 y máximo 100 operaciones de API por conector.
Campos de esquema obligatorios
La especificación de OpenAPI debe incluir estas secciones obligatorias.
- openapi
-
La versión de OpenAPI que se utiliza (debe ser «3.0.0" o superior).
- info
-
Información del servicio, incluidos el título, la descripción y la versión.
- servidores
-
URL base e información del servidor para la conectividad de la API.
- rutas
-
Definiciones de puntos finales de API con métodos y operaciones HTTP.
Esquemas de autenticación compatibles
Prepare las credenciales de autenticación en función de los métodos de autenticación admitidos en las especificaciones de OpenAPI.
- OAuth 2.0
-
Admite los flujos de concesión de códigos de autorización y de concesión de credenciales de cliente. Requiere las definiciones de AuthorizationURL, TokenURL y scopes en el esquema de seguridad.
- Clave de API
-
La autenticación mediante clave de API se transfiere a los parámetros o encabezados de las consultas.
- Sin autenticación
-
Opción predeterminada cuando no hay ningún esquema de seguridad definido en la especificación.
nota
Se ignorarán los esquemas de autenticación no admitidos en la especificación OpenAPI y el conector pasará a no autenticarse de forma predeterminada.
Configurar la integración de las especificaciones de OpenAPI
Tras preparar la especificación de OpenAPI y las credenciales de autenticación, siga estos pasos para crear la integración de la especificación OpenAPI.
-
En la consola Amazon Quick, selecciona Integraciones.
-
Haz clic en Añadir (más el botón «+»).
-
En la página Añadir esquema, selecciona Importar esquema y elige el esquema que quieras importar.
-
Seleccione Siguiente.
-
Complete los detalles de la integración, incluidos el nombre y la descripción.
-
Revise las acciones disponibles generadas a partir de su especificación de OpenAPI.
-
Selecciona Crear y continuar.
-
Elige los usuarios con los que compartir la integración.
-
Haga clic en Next (Siguiente).
Resultados esperados
Tras una configuración correcta, la integración de la especificación OpenAPI aparecerá en la lista de integraciones con acciones generadas dinámicamente en función de su esquema. La integración está disponible para su uso en los flujos de trabajo, automatizaciones y agentes de IA de Amazon Quick, con tareas correspondientes a los puntos de enlace definidos en su especificación de OpenAPI.
Requisitos de formato y patrón
Su especificación de OpenAPI debe cumplir estos requisitos de formato.
-
Patrones de ruta: debe seguir el patrón
^/[^/]*(/[^/]*)*$y empezar con una barra inclinada (/). -
Funcionamiento IDs: debe seguir el patrón:
^[a-zA-Z0-9_ ]{1,256}$. -
Descripciones: obligatorias para todas las operaciones y parámetros, máximo 5000 caracteres.
-
Tipo de contenido: solo application/json es compatible con los organismos de solicitud y respuesta.
Características no admitidas
Las siguientes funciones de OpenAPI no son compatibles y provocarán errores de validación.
-
Tipos de matrices: no se admiten esquemas con tipos de matriz (por ejemplo,
{"type": "array", "items": {"string"}}). -
No se admiten palabras clave de composición: AllOf, OneOf, anyOf y no se admiten las palabras clave.
-
Referencias circulares: no se admiten las referencias circulares o cíclicas ($ref dentro de $ref).
-
Estructuras anidadas complejas: evite las estructuras de objetos profundamente anidadas siempre que sea posible.
Prácticas recomendadas sobre esquemas
Siga estas prácticas recomendadas al crear su especificación de OpenAPI.
Escribe descripciones eficaces
Usa estas pautas para escribir descripciones claras y útiles.
-
Descripciones de las operaciones: describa lo que hace la operación, cuándo utilizarla y cómo se comporta.
-
Descripciones de los parámetros: explique de forma concisa el propósito del parámetro y su impacto en el comportamiento de la operación.
-
Contenido autónomo: asegúrese de que las descripciones proporcionen una orientación suficiente sin referencias externas.
-
Claridad de las dependencias: explicite las dependencias entre las operaciones en las descripciones.
-
Referencias de operaciones: utilice OperationID cuando haga referencia a otras operaciones, no a las rutas de API.
Recomendaciones de estructura de parámetros
Estructura tus parámetros para una usabilidad óptima.
-
Aplane objetos complejos: en lugar de objetos anidados, utilice parámetros separados (por ejemplo, start_date, start_time, end_time).
-
Utilice formatos estándar: utilice valores de formato estándar como «fecha y hora» para las fechas y horas de la norma ISO-8601.
-
Nombres de parámetros claros: utilice nombres de parámetros descriptivos que indiquen claramente su propósito.
-
Marcar los campos obligatorios: marca correctamente los parámetros como obligatorios u opcionales en función del comportamiento de la API.
Extensiones compatibles
Admitimos extensiones OpenAPI personalizadas para mejorar la experiencia del usuario.
- x-amzn-form-display-nombre
-
Úselo a nivel de parámetro para anular el nombre de campo predeterminado que se muestra en los formularios de confirmación. Actualmente solo se admite para los parámetros del cuerpo de la solicitud.
"x-amzn-form-display-name": "User Name" - x-amzn-operation-type
-
Defina si una operación debe tratarse como «lectura» o «escritura». De forma predeterminada, los métodos GET son operaciones de «lectura» y todos los demás métodos HTTP son operaciones de «escritura».
"x-amzn-operation-type": "read"
Validación de esquemas y manejo de errores
Cuando subes una especificación de OpenAPI, realizamos una validación exhaustiva.
-
Validación del tamaño del archivo: garantiza que la especificación no supere 1 MB.
-
Validación del recuento de operaciones: verifica que se hayan definido entre 1 y 100 operaciones.
-
Validación de la estructura del esquema: comprueba los campos obligatorios y el formato correcto.
-
Validación del esquema de seguridad: valida los métodos de autenticación compatibles.
-
Validación del tipo de contenido: garantiza que solo application/json se utilice.
Los errores de validación aparecen debajo del editor de esquemas y deben resolverse antes de poder crear la integración. Los problemas de validación más comunes incluyen:
-
Faltan campos obligatorios (openapi, información, servidores, rutas).
-
Patrones de ruta u operación IDs no válidos.
-
Características del esquema no compatibles (matrices, palabras clave de composición).
-
Descripciones faltantes o demasiado largas.
-
Referencias circulares en las definiciones de los esquemas.
Gestione la integración de las especificaciones de OpenAPI
Tras crear la integración de la especificación OpenAPI, puede gestionarla mediante varias opciones.
Compartir la integración
Puede compartir los conectores de acción de la especificación OpenAPI con otros usuarios de su organización.
-
En la página de detalles de la integración de OpenAPI, selecciona Compartir.
-
Configura las opciones de uso compartido:
-
Compartir con usuarios específicos: introduzca los nombres de usuario o las direcciones de correo electrónico.
-
Compartir con la organización: póngalo a disposición de todos los usuarios de su organización.
-
-
Establece los niveles de permisos para el acceso compartido.
-
Seleccione Compartir integración para aplicar la configuración de uso compartido.
Eliminación de integración
Sigue estos pasos para eliminar permanentemente tu integración con OpenAPI.
-
En la página de detalles de la integración de OpenAPI, selecciona Eliminar.
-
Revisa el impacto de la eliminación, incluidos los flujos de trabajo o las automatizaciones que utilizan esta integración.
-
Escriba el nombre de la integración para confirmar la eliminación.
-
Elija Eliminar integración para eliminarla permanentemente.
Solucionar problemas de integración de la especificación OpenAPI
Utilice estos consejos de solución de problemas para resolver problemas comunes de integración de la especificación OpenAPI.
- Errores de validación de esquemas
-
Asegúrese de que su especificación de OpenAPI siga el formato correcto e incluya todos los campos obligatorios. Utilice un validador de OpenAPI para comprobar el esquema antes de importarlo.
- No se generó ninguna tarea
-
Compruebe que la especificación de OpenAPI incluye definiciones de rutas con métodos y operaciones HTTP. IDs Las acciones se generan en función de las operaciones definidas en el esquema.
- Errores de autenticación
-
Comprueba que el esquema de autenticación definido en tu especificación de OpenAPI coincide con los requisitos reales de la API y que las credenciales están configuradas correctamente.
- Fallos en la ejecución de acciones
-
Revise los parámetros de acción y asegúrese de que coincidan con las definiciones de parámetros de su especificación de OpenAPI, incluidos los campos obligatorios y los tipos de datos.
