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, confirma que tienes lo siguiente:

Requisitos del ID de configuración de la API

Muchos de los comandos gcloud que se muestran en este instructivo 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

Usa Google Cloud CLI para subir la definición de la API y crear una configuración de la 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.

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

  1. Cambia el directorio al 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: Implementa una API en API Gateway.

    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 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. Para obtener más detalles, consulta Cómo configurar una cuenta de servicio.

    Mientras se crean la API y la configuración de 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: 1111111@developer.gserviceaccount.com
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.

Google Cloud CLI admite muchas opciones, incluidas las que se describen en la Referencia de gcloud. 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 la configuración de la API

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 la API y los IDs 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.

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

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

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

¿Qué sigue?