Crea una configuración de API

En esta página, se describe cómo crear una configuración de API para implementar en API Gateway.

Antes de comenzar

Antes de crear una configuración de API, haz lo siguiente:

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

• Crea una definición de API como una especificación de OpenAPI.

• Si usas Google Cloud CLI, puedes crear una API de forma opcional. Si la API no existe, la creación de la configuración de la API la crea.

  Nota: Cuando se usa la Google Cloud consola, la API y la configuración de la API se crean cuando se implementa la API en una puerta de enlace.

Requisitos del ID de configuración de API

Muchos de los comandos de gcloud CLI que se muestran requieren que especifiques el ID de la configuración de la API, con el formato CONFIG_ID. API Gateway aplica los siguientes requisitos para el ID de configuración de la API:

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

Crea una configuración de API

Para crear una configuración de API, sube la definición de tu API.

Nota: API Gateway admite la creación de definiciones de API como especificaciones de OpenAPI para todos los servicios de backend disponibles. API Gateway también admite el uso de definiciones y configuraciones de servicios de gRPC para servicios de gRPC en Cloud Run.

Si el managedService en la definición de tu API está configurado en un servicio ESPv2 Beta, asegúrate de que el campo host (OpenAPI 2.0) o el campo server.url (OpenAPI 3.x) estén configurados en una extensión x-google-endpoint en la configuración de tu API.

Si la definición de tu API configura cuotas, asegúrate de que las métricas y los límites de cuota sigan siendo coherentes en todas las configuraciones de API activas antes de crear una nueva. API Gateway los aplica a toda la API en lugar de a una configuración de API individual, por lo que cualquier métrica o límite que declare una nueva configuración de API reemplaza la definición de toda la API. Si cambias el nombre de una métrica o la quitas, las puertas de enlace que aún entregan una configuración de API anterior muestran errores para sus métodos con cuotas aplicadas. Para obtener más información, consulta Las cuotas se aplican a toda la API.

Para crear una configuración de API, haz lo siguiente:

Google Cloud Consola de

Crea una configuración de API cuando implementes una API en una puerta de enlace.

Google Cloud CLI

Sube la definición de tu API para crear una configuración de API. Cuando subes la definición de la API, debes especificar el nombre de la API. Si la API aún no existe en API Gateway, este comando también la crea.

Nota: Si deseas usar OpenAPI 3.x, asegúrate de actualizar los componentes de gcloud CLI antes de crear una configuración de API para evitar errores cuando subas la definición de tu API.

1. Cambia al directorio que contiene la definición de tu API.

   Para obtener más información sobre cómo crear la especificación de OpenAPI para la definición de tu API, consulta Descripción general de OpenAPI y Guía de inicio rápido: Protege el tráfico a un servicio con gcloud CLI.

   Para obtener más información sobre cómo crear una definición y configuración de servicio de gRPC para la definición de tu API, consulta Configura un servicio de gRPC y Comienza a usar API Gateway y Cloud Run para gRPC.

2. Valida el ID del proyecto que muestra el siguiente comando para asegurarte de que el servicio 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 Google Cloud ID del proyecto en el que quieres crear el servicio:

   gcloud config set project PROJECT_ID

3. Consulta la ayuda para el comando api-configs create:

   gcloud api-gateway api-configs create --help

4. Ejecuta el siguiente comando para crear la configuración de la API:

   gcloud api-gateway api-configs create CONFIG_ID \
         --api=API_ID --openapi-spec=API_DEFINITION \
         --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   Donde:

   • CONFIG_ID especifica el ID de la nueva configuración de API.
   • API_ID especifica el ID de la API de API Gateway asociada con esta configuración de API. Si la API aún no existe, este comando la crea.
   • API_DEFINITION especifica el nombre de la especificación de OpenAPI que contiene la definición de la API.
   • SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens para backends con autenticación configurada. Consulta Configura la cuenta de servicio que se usa para crear configuraciones de API para obtener más detalles.

   Mientras se crea la API y la configuración de la API, API Gateway envía información a la terminal. Esta operación puede tardar varios minutos en completarse, ya que la configuración de la API se propaga a los sistemas descendentes. La creación de una configuración de API compleja puede tardar hasta diez minutos en completarse correctamente. Mientras se crea una configuración, no intentes crear otra para la misma API. Solo se puede crear una configuración para cualquier API a la vez.

5. Cuando se complete correctamente, puedes usar el siguiente comando para ver los detalles sobre la nueva configuración de API:

   gcloud api-gateway api-configs describe CONFIG_ID \
         --api=API_ID

   Este comando muestra lo siguiente:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
         backendConfig:
           googleServiceAccount: [e-mail]
   labels: ''
   name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   serviceRollout:
         rolloutId: 2020-02-04r2
   state: ACTIVE
   updateTime: '2020-02-04T18:33:12.219323647Z'

6. Habilita la API con el nombre del servicio administrado de la API. Puedes encontrar este valor en la columna Servicio administrado de tu API en la página de destino de APIs:

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   Solo debes ejecutar este comando una vez cuando crees la API. Si modificas la API más adelante, no tendrás que volver a ejecutar el comando.

gcloud CLI toma muchas opciones, incluidas las que se describen en la referencia de Google Cloud CLI. Además, para API Gateway, puedes establecer las siguientes opciones cuando creas una configuración de API:

• --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 configuración de la API, es decir, el nombre que se muestra en la IU. No uses espacios en el nombre. Usa guiones y guiones bajos en su lugar. El valor predeterminado es CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: Especifica etiquetas asociadas con la configuración de la API.

Por ejemplo:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

Puedes ver las etiquetas en el resultado del comando describe que se muestra o en el comando list si incluyes la opción --format:

gcloud api-gateway api-configs list \
  --api=API_ID --format="table(name, labels)"

Enumera las configuraciones de API

Enumera todas las API Gateways implementadas en tu Google Cloud proyecto.

Google Cloud Consola de

Para enumerar las configuraciones de API para una API específica en un proyecto, haz lo siguiente:

1. En la Google Cloud consola de, ve a la página API Gateway.

   Ir a API Gateway

2. Haz clic en la API requerida.
3. Haz clic en la pestaña Configuraciones.

Verás la lista de configuraciones de API disponibles en la página.

Google Cloud CLI

Para enumerar las configuraciones de API para un proyecto específico, haz lo siguiente:

gcloud api-gateway api-configs list 

Este comando muestra lo siguiente:

NAME                                                                                                 DISPLAY_NAME             ROLLOUT_ID    STATE     CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

Para enumerar las configuraciones de API para una API específica en un proyecto, haz lo siguiente:

gcloud api-gateway api-configs list --api=API_ID 

Usa los IDs de API y de configuración para obtener información detallada sobre la configuración de la API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID 

Actualiza una configuración de API

No puedes modificar una configuración de API existente, excepto para actualizar sus etiquetas y su nombre visible.

Nota: Cada vez que subas una definición de API, API Gateway creará una configuración de API nueva.

Para actualizar una definición de API, haz lo siguiente:

1. Actualiza la especificación de OpenAPI que contiene la definición de la API.
2. Sube la definición de la API para crear una nueva configuración de API.

Usa el mismo comando para crear la nueva configuración de API que usaste para crear la configuración de API inicial, como se muestra en Crea una configuración de API.

Google Cloud Consola de

1. En la Google Cloud consola de, ve a la página API Gateway.

   Ir a API Gateway

2. Haz clic en la API requerida.
3. Haz clic en la pestaña Configuraciones.
4. Haz clic en la configuración de API requerida.
5. Haz clic en editar Editar.
6. Edita Nombre visible o Etiquetas.
7. Haz clic en Guardar.

Google Cloud CLI

Usa el siguiente `gcloud` para actualizar una configuración de API existente:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

Por ejemplo:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID \
  --update-labels=a=1,b=2

Usa el siguiente comando para ver todas las opciones de actualización:

gcloud api-gateway api-configs update --help

Borra una configuración de API

Advertencia: Si implementaste la configuración de la API en una puerta de enlace, es posible que no se borre hasta que la puerta de enlace ya no use esa configuración de la API.

Antes de borrar una configuración de API que está en uso, debes hacer lo siguiente:

• Implementar una configuración de API diferente en la puerta de enlace.
• Borrar la puerta de enlace.

Consulta Implementa una API en una puerta de enlace para obtener más información.

Google Cloud Consola de

1. En la Google Cloud consola de, ve a la página API Gateway.

   Ir a API Gateway

2. Haz clic en la API requerida.
3. Haz clic en la pestaña Configuraciones.
4. Haz clic en Más y, luego, en Borrar para borrar la configuración de API elegida.

Google Cloud CLI

Usa el siguiente comando de gcloud CLI para borrar una configuración de API existente:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

¿Qué sigue?

• Implementa una API en una puerta de enlace