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, se creará cuando se cree la configuración de la API.

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

Requisitos del ID de configuración de la 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 siguiente 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

Crea una configuración de API subiendo 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 campo managedService en la definición de tu API está configurado como un servicio de ESPv2 Beta, asegúrate de que el campo host (OpenAPI 2.0) o el campo server.url (OpenAPI 3.x) estén configurados como una extensión x-google-endpoint en la configuración de tu API.

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

Consola de Google Cloud

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 su nombre. 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 tu definición de 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 Inicio rápido: Protege el tráfico a un servicio con la CLI de gcloud.

   Para obtener más información sobre cómo crear una definición y configuración de servicio de gRPC para tu definición de 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 ID del proyecto Google Cloud 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 back-ends con autenticación configurada. Consulta Cómo configurar la cuenta de servicio que se usa para crear configuraciones de API para obtener más detalles.

   Mientras se crean 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 posteriores. 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 el proceso finalice con éxito, puedes usar el siguiente comando para ver los detalles de la nueva configuración de la API:

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

   Este comando devuelve 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 las 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 admite muchas opciones, incluidas las que se describen en la Referencia de la CLI de Google Cloud. Además, en 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. En su lugar, usa guiones y guiones bajos. 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 la API

Enumera todas las puertas de enlace de API implementadas en tu proyecto de Google Cloud .

Consola de Google Cloud

Para enumerar los parámetros de configuración de la API para una API específica en un proyecto, haz lo siguiente:

1. En la consola de Google Cloud , 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 Configs.

Verás la lista de parámetros de configuración de la API disponibles en la página.

Google Cloud CLI

Para enumerar los parámetros de configuración de la API de un proyecto específico, haz lo siguiente:

gcloud api-gateway api-configs list 

Este comando devuelve 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 los parámetros de configuración de la 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 la API y de la 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 configuración de API nueva que usaste para crear la configuración de API inicial, como se muestra en Crea una configuración de API.

Consola de Google Cloud

1. En la consola de Google Cloud , 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 Configs.
4. Haz clic en la configuración de API requerida.
5. Haz clic en editar Editar.
6. Edita el Nombre visible o las Etiquetas.
7. Haz clic en Guardar.

Google Cloud CLI

Usa el siguiente comando `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 API en una puerta de enlace, es posible que no se borre hasta que la puerta de enlace deje de usarla.

Antes de borrar una configuración de API que está en uso, debes hacer una de las siguientes acciones:

• Implementa una configuración de API diferente en la puerta de enlace.
• Borra la puerta de enlace.

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

Consola de Google Cloud

1. En la consola de Google Cloud , 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 Configs.
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