1. Crear una instancia de gateway

Una instancia de gateway es el motor que procesa las solicitudes de API.

1. Inicie sesión en la consola de Cloud-native API Gateway. En el panel de navegación izquierdo, haga clic en Instance.

2. Seleccione una región en la barra de navegación superior.

   Importante

   La región debe ser la misma que la de su espacio de trabajo de DataWorks.

3. En la página Instance, haga clic en Create Instance.

4. En la página de compra, configure los siguientes parámetros:

   • Commodity Type: se admiten Pay-as-you-go y Subscription. Para fines de prueba, puede seleccionar pay-as-you-go.

   • Gateway Name: introduzca un nombre personalizado fácil de identificar, como dataservice-prod.

   • Gateway Specification: seleccione nodo único para pruebas o multinodo para cumplir con el SLA de producción.

   • Network Access Type: seleccione Public o Public + Private para habilitar el acceso a Internet. El uso de acceso público genera cargos por tráfico.

   • VPC: seleccione una VPC.

     Importante

     Se recomienda encarecidamente utilizar la misma VPC que el resource group serverless mencionado en los requisitos previos. Si las VPC son diferentes, deberá crear manualmente un servicio backend más adelante.

   • Zone Selection: puede seleccionar Auto Assign o asignar manualmente instancias en distintas zonas y vSwitches.

   • Resource Group: seleccione un resource group según su política de gestión de recursos.

5. Haga clic en Buy Now y complete el pago. La creación de la instancia tarda entre 1 y 5 minutos aproximadamente. La instancia estará lista cuando su estado cambie a Running.

Create a gateway instance .

2. Agregar un nombre de dominio

Si solo necesita acceder a la API dentro de una VPC, no es necesario solicitar un nombre de dominio.

Un nombre de dominio funciona como punto de entrada de acceso público para la API.

1. En el panel de navegación izquierdo de la consola de Cloud-native API Gateway, haga clic en Domain Name. Asegúrese de que la región en la parte superior coincida con la de la instancia de gateway.

2. Haga clic en Add Domain Name y configure la siguiente información:

   • Domain Name: introduzca su propio nombre de dominio, como api.example.com. Los nombres de dominio independientes utilizados en regiones de China deben completar ICP filing.

   • Protocol: seleccione HTTPS para garantizar una transmisión segura de datos. También debe seleccionar un certificado SSL existente.

   • Other Settings: habilite Force HTTPS y Enable HTTP/2, y seleccione una TLS Version según sus requisitos de seguridad.

Add a domain name .

3. Crear una API REST

Una API REST agrupa APIs bajo una Base Path compartida. Un flujo de trabajo de DataWorks se vincula a una API REST.

En comparación con la versión anterior de API Gateway, una API REST equivale a un grupo de API.

1. En el panel de navegación izquierdo de la consola de Cloud-native API Gateway, haga clic en API. Verifique que la región en la parte superior sea la correcta.

2. Haga clic en Create API. En la página Create API, seleccione Create en la tarjeta REST API.

3. En el panel Create REST API, configure los siguientes ajustes:

   • API Name: asigne un nombre a su colección de APIs. El nombre debe ser único a nivel global dentro de la región actual, por ejemplo, dataservice-user-api.

   • Base Path: la ruta base de la API, que forma parte de la URL. Por ejemplo, establézcala en /v1. La ruta de acceso final será Protocol://DomainName/BasePath/APIPath.

   • Version Management: habilítelo según sea necesario.

Create a REST API .

1. Crear un flujo de trabajo

Un flujo de trabajo organiza APIs relacionadas y las asocia con una API REST en API Gateway.

1. Vaya a la consola de DataWorks. En el panel de navegación izquierdo, diríjase a Data Services > Service Development.

2. Haga clic en el icono de creación en la esquina superior izquierda y seleccione Create Workflow.

3. En el cuadro de diálogo Create Workflow, configure los siguientes ajustes:

   • Workflow Name: introduzca un nombre personalizado que sea único dentro del espacio de trabajo, como User Query Workflow. El nombre debe tener entre 4 y 50 caracteres.

   • Gateway Type: seleccione Cloud-native API Gateway.

   • REST API: en la lista desplegable, seleccione la API REST que creó en el Paso 1 (por ejemplo, dataservice-user-api). Si no aparece, haga clic en el botón Refresh.

     Importante

     Una vez que un flujo de trabajo se asocia con una API REST, el vínculo no se puede modificar. Proceda con precaución.

2. Generar una API en modo asistente

1. En la página Service Development, pase el cursor sobre el icono de creación en la esquina superior izquierda y haga clic en Create API > Generate API.

2. En el cuadro de diálogo Generate API, seleccione Wizard Mode y configure la información básica de la API:

   • Location: seleccione el Workflow creado en el paso anterior (User Query Workflow).

   • API Name: introduzca un nombre para la API específica, como Query User by User ID.

   • APIPath: la ruta específica de la API, por ejemplo, /user/info. Se concatena con la Base Path para formar la ruta URL completa. La ruta de la API debe comenzar con / y no puede exceder los 200 caracteres.

   • Request Method: seleccione GET o POST. Al seleccionar GET, los parámetros de solicitud solo se pueden colocar en la cadena QUERY.

   • Response Type: seleccione JSON.

3. Haga clic en Create para ir a la página gráfica de edición de API.

   Nota

   Para crear una API en modo script, consulte Create an API in script mode.

3. Configurar la API

En la página de edición de API, siga el flujo Select Table > Select Parameters > Configure Parameters para definir su API.

1. Seleccionar una tabla (origen de datos y tabla)

   En la sección Select Table del lado izquierdo de la página, configure los siguientes ajustes:

   • Data Source Type: seleccione MaxCompute(ODPS).

   • Data Source Name: seleccione el origen de datos que configuró en los requisitos previos.

   • Data Table Name: seleccione la tabla user_info.

   • Si utiliza un origen de datos de MaxCompute, debe configurar el Acceleration Method para mejorar el rendimiento.

2. Seleccionar parámetros (solicitud y respuesta)

   Después de seleccionar una tabla, la sección Select Parameters que se encuentra debajo enumera todas las columnas de la tabla.

   • Configurar parámetros de solicitud: seleccione la columna user_id y haga clic en Set as Req Param.

   • Configurar parámetros de respuesta: seleccione las columnas user_id y user_name, y haga clic en Set as Resp Param.

3. Configurar detalles de parámetros de solicitud: en la pestaña Request Parameters del lado derecho de la página, establezca el Sample Value para el parámetro user_id (por ejemplo, 10001). Esto facilita las pruebas posteriores.

   Mejor práctica : Establezca columnas indexadas como parámetros de solicitud para optimizar el rendimiento de las consultas.

4. Configurar resource group de servicio y entorno

   En la sección Service Resource Group del lado derecho de la página, configure los siguientes ajustes:

   • Resource Group Type: debe seleccionar Exclusive Resource Group for Data Service y elegir un resource group asociado al espacio de trabajo actual en la lista desplegable.

   • Environment Configuration:

     • Timeout: tiempo máximo que Cloud-native API Gateway espera una respuesta de DataWorks, por ejemplo, 3 segundos.

     • Maximum Number of Data Records for a Single Request: número máximo de registros devueltos por una sola llamada a la API, por ejemplo, 2000.

5. Configurar autenticación de seguridad

   En la sección de autenticación de seguridad de la derecha, habilite la autenticación de consumidor y seleccione un tipo de autenticación.

   Nota

   DataWorks crea automáticamente un consumidor con el mismo nombre que el espacio de trabajo en Cloud-native API Gateway. No es necesario crear uno manualmente.

   Método de autenticación	Descripción	Escenario aplicable
   API Key	El cliente incluye credenciales en cada solicitud, y el gateway verifica su validez y permisos. Adecuado para operaciones no sensibles. Es menos seguro que JWT y HMAC; proteja las credenciales con cuidado.	Adecuado para escenarios de integración ligera y rápida con requisitos de seguridad moderados.
   JWT	JSON Web Token (JWT) utiliza firmas HMAC, RSA o ECDSA para transmitir afirmaciones verificables entre cliente y servidor, lo que permite la verificación de identidad y el control de acceso en el gateway.	Adecuado para sistemas distribuidos y escenarios de inicio de sesión único (SSO).
   HMAC	El cliente firma el contenido de la solicitud con una clave de firma y envía la firma junto con la solicitud para su verificación en el servidor.	Adecuado para escenarios con altos requisitos de integridad de datos y prevención de manipulación.

6. Guardar la API: después de completar todas las configuraciones, haga clic en el icono Save en la barra de herramientas superior.

1. Probar la API

Una API debe pasar las pruebas antes de poder enviarse.

1. En la página de edición de API, haga clic en el botón Test APIs de la barra de herramientas.

2. En el cuadro de diálogo Test APIs, introduzca un valor de muestra existente para el parámetro de solicitud user_id (por ejemplo, 10001) y luego haga clic en Start Test.

3. Consulte los Response Details del lado derecho para verificar si los datos cumplen con lo esperado. La Response Duration sirve para evaluar el rendimiento.

4. Si la prueba falla, revise las configuraciones del origen de datos, la tabla, los parámetros o el resource group según el mensaje de error.

2. Enviar la API

Después de una prueba exitosa, envíe la API para generar una versión desplegable.

1. En la página de edición de API, haga clic en el botón Submission de la barra de herramientas.

2. Tras el envío, el sistema genera una versión de la API, visible en la pestaña Version Management del lado derecho.

3. Si hay un proceso de aprobación configurado para su espacio de trabajo, el estado de la versión de la API será To Be Requested. Deberá hacer clic en Request to Publish para iniciar una solicitud. Una vez que el aprobador autorice la solicitud, el estado cambiará a Can Be Published.

   Si no hay ningún proceso de aprobación configurado, el estado de la versión suele ser Can Be Published directamente.

3. Desplegar la API en Cloud-native API Gateway

Despliegue la API en el entorno de producción.

1. En la pestaña Version del lado derecho de la página de edición de API, busque la versión con estado Can Be Published y haga clic en Publish en la columna Actions.

2. En el cuadro de diálogo Publish API to Cloud-native API Gateway, configure los siguientes tres ajustes obligatorios:

   • Domain Name: seleccione el nombre de dominio que agregó en el Paso 1.

     Importante

     Todas las APIs bajo la misma API REST comparten el mismo nombre de dominio. Cambiar el nombre de dominio durante el despliegue afectará al nombre de dominio utilizado para invocar todas las APIs bajo la misma API REST.

   • Gateway Instance: seleccione la instancia de gateway que creó en el Paso 1.

   • Backend Service:

     • Si la VPC de la instancia de gateway es la misma que la VPC del resource group de DataWorks, seleccione Default.

     • Si las VPC son diferentes, debe seleccionar un servicio backend creado en Cloud-native API Gateway.

       Create a backend service

       Realice este paso solo si la VPC seleccionada al crear la instancia de gateway en el Paso 1 es diferente de la VPC del resource group serverless. Si las VPC son iguales, omita esta sección.

       Un servicio backend establece la conectividad entre dos VPC diferentes para las solicitudes de Data Service.

       1. En la lista de Instance de la consola de Cloud-native API Gateway, haga clic en el ID de la instancia destino.

       2. En el panel de navegación izquierdo de la página de detalles de la instancia, haga clic en Service.

       3. Haga clic en Create Service. Si se le solicita, primero cree un origen en la pestaña Source.

       4. Al crear un servicio, configure el nombre del servicio y asócielo con el origen que creó.

       Create a backend service .

Desplegar una API en varias instancias de gateway

En el panel Version, haga clic en Publish para la versión con estado Can Be Published. En el cuadro de diálogo Publish API to Cloud-native API Gateway, seleccione una Gateway Instance diferente para desplegar la API en la instancia de gateway correspondiente. Puede repetir este proceso para desplegar la misma API en varias instancias.

Dentro de la misma instancia de gateway, desplegar una nueva versión anula automáticamente el despliegue de la anterior. Las versiones en diferentes instancias de gateway son independientes y pueden coexistir en estado deployed.

Visualización de múltiples versiones en la gestión de servicios

Después de desplegar una API en varias instancias de gateway, la visualización en la página Service Management cambia de la siguiente manera.