Implementar una API en una puerta de enlace

Requisitos previos

Antes de implementar una configuración de API en API Gateway, asegúrate de haber hecho lo siguiente:

• Preparar tu entorno de desarrollo como se describe en Configura tu entorno de desarrollo.

• Crear una API.

• Crear una definición de API.

• Crear una configuración de API a partir de la definición de tu API.

Requisitos de ID de Gateway

Muchos de los comandos gcloud que se muestran a continuación requieren que especifiques el ID de la puerta de enlace, en el formato: GATEWAY_ID. API Gateway aplica los siguientes requisitos para el ID de la puerta de enlace:

• Debe tener una longitud máxima de 49 caracteres.
• Debe contener solo letras en minúscula, números o guiones.
• No debe comenzar con un guion.
• No debe contener un guion bajo.

Define el extremo de la configuración de API implementada

Cuando implementas una configuración de API en una puerta de enlace, API Gateway crea una URL única para la puerta de enlace en el dominio gateway.dev. Luego, tus clientes de API usarán una URL en el siguiente formato para acceder a la configuración de la API implementada:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

donde GATEWAY_ID es el nombre de la puerta de enlace, HASH es el código hash único que se generó cuando se implementó la API y REGION_CODE es el código de la región de GCP en la que implementaste la puerta de enlace.

Por ejemplo:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Implementa una configuración de API en una puerta de enlace

Usa Google Cloud CLI para implementar una configuración de API en una puerta de enlace. Cuando implementes la configuración de la API, deberás especificar el nombre de la API. Si la puerta de enlace aún no existe para la API, este comando también la creará.

Para implementar una configuración de API en una puerta de enlace, sigue estos pasos:

1. Valida el ID del proyecto que muestra el siguiente comando para asegurarte de que la puerta de enlace no se cree en el proyecto equivocado.

   gcloud config list project

   Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y reemplaza PROJECT_ID por el ID del proyecto de Google Cloud en el que quieres crear el servicio:

   gcloud config set project PROJECT_ID

2. Consulta la ayuda del comando gateway create:

   gcloud api-gateway gateways create --help

3. Ejecuta el siguiente comando para implementar la configuración de la API en la puerta de enlace:

   gcloud api-gateway gateways create GATEWAY_ID \
     --api=API_ID --api-config=CONFIG_ID \
     --location=GCP_REGION --project=PROJECT_ID

   Donde:

   • GATEWAY_ID especifica el ID de la nueva puerta de enlace. Si la puerta de enlace aún no existe, este comando la creará.
   • API_ID especifica el ID de la API de API Gateway asociada con esta puerta de enlace.
   • CONFIG_ID especifica el ID de la configuración de la API implementada en la puerta de enlace. Debes especificar una configuración de API cuando creas una puerta de enlace.

   • GCP_REGION especifica la región de GCP para la puerta de enlace implementada.

   • PROJECT_ID especifica el ID del proyecto de Google Cloud.

   Mientras se crea la puerta de enlace, gcloud envía información a la terminal.

4. Cuando el proceso finalice correctamente, puedes usar el siguiente comando para ver los detalles de la puerta de enlace:

   gcloud api-gateway gateways describe GATEWAY_ID \
     --location=GCP_REGION --project=PROJECT_ID

   Este comando muestra lo siguiente:

   apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   createTime: '2020-02-05T13:44:12.997862831Z'
   defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
   displayName: GATEWAY_ID
   name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
   serviceAccount:
     email: gateway-111111@222222-tp.iam.gserviceaccount.com
   state: ACTIVE
   updateTime: '2020-02-05T13:45:00.844705087Z'

   Ten en cuenta el valor de la propiedad defaultHostname. Esta es la parte del nombre de host de la URL de la puerta de enlace. Para acceder a una configuración de API implementada en esta puerta de enlace, usa una URL con el siguiente formato:

   https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Google Cloud CLI admite muchas opciones, incluidas las que se describen en la Referencia de gcloud. Además, en el caso de API Gateway, puedes configurar las siguientes opciones cuando creas una puerta de enlace:

• --async: Devuelve el control a la terminal de inmediato, sin esperar a que se complete la operación.
• --display-name=NAME: Especifica el nombre visible de la puerta de enlace, es decir, el nombre que se muestra en la IU. No uses espacios en el nombre. En su lugar, usa guiones y guiones bajos. El valor predeterminado es GATEWAY_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: Especifica las etiquetas asociadas con la puerta de enlace.

Cómo enumerar puertas de enlace

Para enumerar las puertas de enlace de un proyecto específico, haz lo siguiente:

gcloud api-gateway gateways list --project=PROJECT_ID

Este comando muestra el resultado de la siguiente forma:

GATEWAY_ID        LOCATION       DISPLAY_NAME     STATE     CREATE_TIME          UPDATE_TIME
my-gateway        us-central1    my-gateway       ACTIVE    2021-01-07T00:04:19  2022-05-21T00:33:46

Para enumerar las puertas de enlace de un proyecto y una región específicos, haz lo siguiente:

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Usa una expresión filter para enumerar las puertas de enlace asociadas con una API específica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

O bien usa este filter para enumerar las puertas de enlace de una configuración de API específica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Usa los IDs del proyecto, la región y la puerta de enlace para obtener información detallada sobre la puerta de enlace, incluida la identidad de la configuración de la API implementada en la puerta de enlace:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Cómo actualizar una puerta de enlace

Actualiza una puerta de enlace para lo siguiente:

• Implementa una configuración de API diferente en la puerta de enlace
• Actualiza el nombre visible
• Actualiza las etiquetas

Usa el siguiente comando gcloud para actualizar una puerta de enlace existente, en la que UPDATE_OPTIONS se reemplaza por la marca de opción de puerta de enlace y el valor que deseas actualizar:

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID  

Por ejemplo, para actualizar la configuración de API implementada en la puerta de enlace, haz lo siguiente:

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID 

en el que NEW_CONFIG_ID especifica la nueva configuración de API que se implementará en la puerta de enlace.

Para obtener una lista completa de las marcas y los argumentos de actualización disponibles, consulta la referencia de gcloud api-gateway gateways update o usa el siguiente comando para ver todas las opciones de actualización:

gcloud api-gateway gateways update --help

Borra una puerta de enlace

Usa el siguiente comando de gcloud para borrar una puerta de enlace existente:

gcloud api-gateway gateways delete GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

¿Qué sigue?

• Supervisa tu API
• Transfiere datos hacia y desde el servicio de backend