DataWorks:Pruebas, publicación y gestión de versiones de API

Probar una API en desarrollo

Probar una API en desarrollo significa realizar la prueba en la página Service Development (el entorno de desarrollo). Antes de probar la API, debe generarla primero en modo asistente o modo script, o bien registrar un servicio existente como API.

Procedimiento:

1. Inicie sesión en la consola de DataWorks. En la región objetivo, haga clic en Data Analysis and Service > DataService Studio en el panel de navegación izquierdo. Seleccione un workspace de la lista desplegable y haga clic en Go to DataService Studio.

2. En la lista de API de la izquierda, haga doble clic en el nombre de la API que desea probar para abrir su página de edición.

3. En la página de edición de la API, localice y haga clic en el botón Test para abrir el cuadro de diálogo Test APIs.

4. En el panel izquierdo del cuadro de diálogo, introduzca un valor de prueba para cada parámetro de solicitud.

5. Haga clic en Start Test para activar la llamada a la API.

Consulta de resultados de prueba:

Una vez completada la prueba, puede consultar la siguiente información en el panel derecho del cuadro de diálogo:

• Request Details: La información completa de la solicitud para la llamada a la API, incluida la ruta de solicitud, los encabezados y el cuerpo. Utilice esta información para verificar que la solicitud esté estructurada correctamente.

• Response Details: Los datos de respuesta de la API (el resultado real de la consulta). Compare esto con el resultado esperado para verificar que la lógica de la API sea correcta.

• Response Duration: La latencia de respuesta de extremo a extremo de la solicitud de API. Si la latencia es alta, considere optimizar la lógica de consulta o la configuración del origen de datos.

Si la prueba falla, revise cuidadosamente el mensaje de error devuelto, realice las modificaciones necesarias y vuelva a probar.

Probar una API publicada

Probar una API publicada significa realizar la prueba en la página Service Management (el entorno de producción). Esto verifica el comportamiento real de ejecución de la API después de la publicación. Antes de realizar esta prueba, debe publicar primero la API.

Procedimiento:

1. En la página Data Services, haga clic en Service Management en la barra de navegación superior.

2. En el panel de navegación izquierdo, haga clic en Test APIs.

3. En la lista desplegable, seleccione la API que desea probar y asegúrese de que los valores de los parámetros de solicitud estén completamente configurados.

4. Haga clic en Start Test y consulte los detalles de Request Details y Response Details en el panel derecho.

Notas:

• La página Test APIs solo proporciona funcionalidad de prueba de API en línea. No admite la actualización del ejemplo de respuesta normal de una API.

• Si se configura Pagination for Return Results para una API, el orden de los datos devueltos depende del comportamiento del origen de datos subyacente. Si necesita ordenamiento, puede configurar un Sort field para la API en modo asistente, o agregar una cláusula ORDER BY al código SQL en modo script.

Interpretación de resultados de prueba y sugerencias de optimización

Un resultado completo de prueba de API consta de tres partes. Comprender cada parte le ayuda a identificar problemas rápidamente:

Una vez que los resultados de la prueba cumplan con las expectativas, puede proceder a publicar la API en API Gateway.

Requisitos previos

Antes de publicar una API, asegúrese de cumplir las siguientes condiciones:

• API Gateway está activado: Active el servicio en la consola de API Gateway.

  Importante

  Debido a limitaciones de arquitectura de red entre DataWorks y API Gateway, al adquirir una instancia de API Gateway, solo se admiten instancias dedicadas tradicionales para Instance Type. Las instancias integradas con VPC no son compatibles.

• Se ha creado un grupo de API: Al publicarse, la API se despliega en el grupo correspondiente en API Gateway según la asociación del flujo de trabajo. Asegúrese de que el flujo de trabajo esté asociado correctamente con un grupo de API Gateway. Puede verificar el nombre del grupo haciendo clic con el botón derecho en Workflow > Change.

Proceso de publicación

La publicación de API sigue un proceso de tres pasos: Enviar → Aprobación → Publicar:

Paso 1: Enviar la API

1. Vaya a la página Data Services. En la página Service Development, haga doble clic en el nombre de la API que desea publicar en la lista de API para abrir su página de edición.

2. Haga clic en el botón Submission en la esquina superior derecha.

3. Después de enviarla correctamente, el sistema genera automáticamente una versión de la API (como V1 o V2). Puede consultar el estado de la versión en el panel Version que aparece a la derecha.

Paso 2: Solicitar publicación y esperar aprobación

1. En el panel Version de la derecha, localice la versión de la API que se va a publicar y haga clic en el botón Publish.

2. Siga las instrucciones en pantalla para introducir el motivo de la solicitud y haga clic en Requested Permissions para enviar la solicitud de publicación.

3. Si el workspace tiene configurado un proceso de aprobación, la solicitud de publicación debe aprobarse en el centro de aprobaciones. El aprobador puede consultar los detalles de la solicitud y procesar la aprobación en la página Approval Center > To Be Processed.

4. Una vez otorgada la aprobación, el estado de la API en el panel Version cambia de To Be Requested a Can Be Published.

Si el workspace no tiene configurado un proceso de aprobación, puede continuar directamente con el paso de publicación después del envío, sin esperar aprobación. Para obtener más información, consulte Configure an approval process.

Paso 3: Ejecutar la publicación

1. Una vez otorgada la aprobación, en la barra de navegación derecha de la página de edición de la API, haga clic en Version y localice la versión de la API con el estado Can Be Published.

2. Haga clic en el botón Publish y espere hasta que el sistema indique que la publicación fue exitosa.

3. Después de publicar la API, DataWorks la despliega en el grupo correspondiente en API Gateway según el grupo asociado del flujo de trabajo al que pertenece la API.

Verificación posterior a la publicación

Después de la publicación, puede verificar y gestionar la API de las siguientes maneras:

• Consultar en API Gateway: Inicie sesión en la consola de API Gateway. Consulte la información de la API publicada en Manage APIs > Service List y configure políticas como limitación de tasa y control de acceso.

• Llamadas desde aplicaciones: Si su propia aplicación invoca la API, cree una aplicación en API Gateway, autorice la API para la aplicación y luego utilice AppKey y AppSecret para llamadas cifradas basadas en firma. API Gateway también proporciona SDK para los principales lenguajes de programación. Para obtener más información, consulte Authorize and call an API. Para la integración de SDK, consulte SDK integration.

• Cambio de protocolo: Para una API publicada, en la pestaña Service Management > Published APIs, haga clic en More > Change Protocol para la API correspondiente a fin de modificar el protocolo de acceso (por ejemplo, de HTTP a HTTPS). El cambio de protocolo surte efecto inmediatamente. Sin embargo, si se elimina el protocolo original, las llamadas a la API que utilicen ese protocolo fallarán. Proceda con precaución.

Listar en Alibaba Cloud API Marketplace (opcional)

Alibaba Cloud API Marketplace abarca varias categorías y puede ayudarle a monetizar sus datos.

Una vez que las API generadas o registradas en Data Service se publican en API Gateway, puede listarlas en Alibaba Cloud API Marketplace para su venta con un solo clic, ayudando a las empresas a monetizar el valor de los datos.

Requisitos previos:

• Solo se admiten identidades empresariales para registrarse en Alibaba Cloud API Marketplace.

• Antes de listar, debe registrarse en Alibaba Cloud Marketplace como proveedor de servicios. Para conocer el proceso, consulte Register as a service provider.

Procedimiento:

1. Vaya a la Plataforma de proveedores de servicios de Alibaba Cloud.

2. En el panel de navegación izquierdo, haga clic en Commodity > Product Management.

3. Haga clic en Publish Product.

4. En la página Access Information, configure los parámetros según las instrucciones (incluido el nombre del producto, la estrategia de precios y la vinculación de API) para completar el proceso de listado de la API.

Consultar historial de versiones

1. Inicie sesión en la consola de DataWorks. En la región objetivo, haga clic en Data Analysis and Service > DataService Studio en el panel de navegación izquierdo. Seleccione un workspace de la lista desplegable y haga clic en Go to DataService Studio.

2. En la página Service Development, haga doble clic en el nombre de la API que desea consultar en la lista de API para abrir su página de edición.

3. Haga clic en el botón Version en el lado derecho de la página para abrir el panel de versiones y consultar la información y los detalles de las versiones. El panel de versiones muestra toda la información histórica de versiones de la API actual, incluyendo:

   Nota

   Cada versión proporciona un enlace API Details en la columna Acciones. Haga clic en él para consultar la información de configuración completa de esa versión, incluidos los parámetros de solicitud, los parámetros de respuesta y la configuración del origen de datos.

   Columna	Descripción
   API ID	El identificador único de la API actual.
   Version	El número de versión, que se incrementa en orden de envío (V1, V2, V3, etc.).
   Submitted By	El usuario que envió esta versión.
   Submitted At	La hora de publicación de esta versión, precisa al segundo.
   Status	Publish (la versión más reciente actualmente vigente en línea) Can Be Published (una versión que ha pasado las pruebas y ha sido enviada) Batch Synchronization (una versión histórica antigua)

Comparación de versiones

Después de múltiples iteraciones de una API, es posible que necesite comparar versiones para comprender los cambios específicos.

Procedimiento:

1. En el panel Version, seleccione dos versiones cualesquiera que desee comparar.

2. Haga clic en el botón Compare en la parte inferior del panel.

3. En el cuadro de diálogo History Version Contrast que aparece, consulte las diferencias entre las dos versiones.

Contenido de la comparación:

• API en modo asistente: Muestra diferencias en los parámetros de solicitud y respuesta, incluidos cambios en atributos como nombre del parámetro, tipo y si un parámetro es obligatorio.

• API en modo script: Muestra diferencias de texto en scripts SQL, con líneas agregadas, eliminadas y modificadas resaltadas.

La comparación de versiones es especialmente útil en escenarios de colaboración en equipo, ya que ayuda a los revisores a comprender rápidamente el contenido de cada cambio.

Reversión de versión

Cuando una nueva versión presenta anomalías o no cumple con las expectativas, puede revertir la API a una versión estable anterior.

Procedimiento:

1. En el panel Version, localice la versión histórica objetivo.

2. Haga clic en el botón Roll Back en la columna Acciones de esa versión.

3. En el cuadro de diálogo Confirm Rollback que aparece, haga clic en Confirm.

Una vez completada la reversión, la configuración de la API se restaura al contenido de la versión histórica seleccionada y la versión actual en línea se actualiza inmediatamente. Se recomienda utilizar la función de comparación de versiones para confirmar la configuración de la versión objetivo antes de realizar una reversión y evitar cambios no deseados.

Estrategia de gestión de versiones

Las buenas prácticas de gestión de versiones pueden reducir significativamente el riesgo de incidentes en producción.

• Registros de cambios: Cada vez que envíe una versión, describa claramente los cambios y los motivos en las notas de envío para que los miembros del equipo puedan comprender el contexto mediante la comparación de versiones.

• Verificación de despliegue gradual: Para cambios importantes, se recomienda verificar completamente en el entorno de prueba antes de publicar en el entorno de producción.

• Reversión rápida: Cuando se detecta un problema en línea, utilice la reversión de versión para restaurar el servicio primero y luego investigue la causa raíz. La reversión es más rápida que modificar y volver a publicar, lo que minimiza el impacto en el negocio.

• Limpieza periódica: Para las API que no se han utilizado durante mucho tiempo, retire su publicación y límpielas oportunamente para reducir la complejidad de gestión y los posibles riesgos de seguridad.

Flujo de trabajo de colaboración para pruebas y publicación

En escenarios de colaboración en equipo, se recomienda el siguiente flujo de trabajo:

1. Los desarrolladores crean y configuran la API en la página Service Development.

2. Los desarrolladores prueban la API en el entorno de desarrollo para verificar la funcionalidad.

3. Los desarrolladores envían la API para generar una nueva versión e inician una solicitud de publicación.

4. Los aprobadores revisan la solicitud de publicación en el centro de aprobaciones y pueden usar la función de comparación de versiones para consultar los cambios.

5. Después de la aprobación, los desarrolladores ejecutan la operación final de publicación.

6. Los operadores realizan pruebas en línea y monitoreo de la API publicada en la página Service Management.

7. Si se encuentran problemas, restaure rápidamente la API mediante la reversión de versión o retire su publicación para repararla.

Este flujo de trabajo ayuda a los equipos a lograr una gestión eficiente del ciclo de vida completo de la API, garantizando al mismo tiempo la calidad de la publicación.

Limitaciones de los ejemplos de respuesta

La página de edición de API admite la configuración de un ejemplo de respuesta normal para mostrar la estructura de datos de respuesta esperada en la documentación de la API. Tenga en cuenta lo siguiente:

• Sin sincronización automática: Los resultados de prueba de la página de prueba de API no se actualizan automáticamente como ejemplo de respuesta normal. Debe editar o pegar manualmente el ejemplo de respuesta en la página de edición de la API.

• Límite de tamaño: El ejemplo de respuesta normal tiene un límite máximo de caracteres. Si los datos de ejemplo son demasiado grandes (por ejemplo, contienen cientos de registros), el guardado puede fallar. Mantenga solo de 2 a 3 registros típicos como ejemplo.

• Surte efecto después de la publicación: Después de modificar el ejemplo de respuesta normal, debe volver a enviar y publicar la API para que los cambios surtan efecto en la documentación de API Gateway.

Manejo de cambios en la estructura de tablas del origen de datos

Cuando cambia la estructura de tabla del origen de datos asociado con una API (como agregar columnas, eliminar columnas o modificar tipos de columna), las API publicadas no detectan estos cambios automáticamente. Si no se aborda, pueden ocurrir los siguientes problemas:

Procedimiento:

1. Vaya a la página de edición de la API y modifique la configuración de la API según los cambios en la estructura de la tabla.

   1. Modo asistente: Vuelva a seleccionar la tabla y el sistema actualizará automáticamente la lista de columnas.

   2. Modo script: Modifique manualmente los nombres de columna o el nombre de la tabla en la sentencia SQL.

2. Después de guardar la configuración, vuelva a probar para verificar los cambios.

3. Envíe y vuelva a publicar la API.

Para las API en modo asistente, después de clonar, si la estructura de tabla asociada con la API original ha cambiado, la API clonada puede seguir utilizando la información antigua de la estructura de tabla. Se recomienda volver a entrar al modo asistente para actualizar la configuración de columnas después de clonar.