Crear una configuración de API

Requisitos previos

Antes de crear una configuración de API, asegúrate de que tienes lo siguiente:

Requisitos de los IDs de configuración de la API

Muchos de los comandos de gcloud que se muestran a continuación requieren que especifiques el ID de la configuración de la API con el siguiente formato: CONFIG_ID. API Gateway aplica los siguientes requisitos al ID de configuración de la API:

  • Debe tener una longitud máxima de 63 caracteres.
  • Solo debe incluir letras minúsculas, números o guiones.
  • No debe empezar por un guion.
  • No debe contener un guion bajo.

Crear una configuración de API

Usa la CLI de Google Cloud para subir la definición de tu API y crear una configuración de API. Cuando subas la definición de la API, deberás 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, sigue estos pasos:

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

    Para obtener más información sobre cómo crear la especificación de OpenAPI de tu definición de API, consulta la descripción general de OpenAPI y la guía de inicio rápido para desplegar una API en API Gateway.

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

  2. Valida el ID del proyecto devuelto por el siguiente comando para asegurarte de que el servicio no se ha creado en el proyecto incorrecto.

    gcloud config list project

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y sustituye PROJECT_ID por el Google Cloud ID del proyectoPROJECT_ID en el que quieras crear el servicio:

    gcloud config set project PROJECT_ID

  3. Consulta la ayuda del 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 la API.
    • API_ID especifica el ID de la API de API Gateway asociada a 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.
    • PROJECT_ID especifica el Google Cloud ID del proyecto.
    • SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens de back-ends con la autenticación configurada. Para obtener más información, consulta el artículo Configurar una cuenta de servicio.

    Mientras crea la API y la configuración de la API, API Gateway muestra información en 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 cada API a la vez.

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

    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_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 mediante el nombre del servicio gestionado de la API. Puede encontrar este valor en la columna Servicio gestionado de su API en la página de destino de las APIs:

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

    Solo tienes que ejecutar este comando una vez al crear la API. Si modificas la API más adelante, no tendrás que volver a ejecutar el comando.

La CLI de Google Cloud acepta muchas opciones, incluidas las que se describen en la referencia de gcloud. Además, en API Gateway, puedes definir las siguientes opciones al crear una configuración de API:

  • --async: devuelve el control a la terminal inmediatamente, 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 interfaz de usuario. 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 las etiquetas asociadas a la configuración de la API.

Por ejemplo:

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 \
  --async --display-name=MyConfig --labels=a=1,b=2

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

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

Listar configuraciones de API

Para enumerar las configuraciones de API de un proyecto específico, sigue estos pasos:

gcloud api-gateway api-configs list --project=PROJECT_ID

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 las configuraciones de API de una API específica de un proyecto, sigue estos pasos:

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

Usa los IDs de proyecto, API y 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 --project=PROJECT_ID

Actualizar una configuración de API

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

Usa la siguiente gcloud para actualizar una configuración de API:

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

Por ejemplo:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_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

Eliminar una configuración de API

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

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

Siguientes pasos