Se usó la API de Cloud Translation para traducir esta página.

Protege el tráfico a un servicio con gcloud CLI

En esta página, se muestra cómo implementar una API en API Gateway para proteger el tráfico a un servicio de backend.

Sigue estos pasos para implementar una API nueva para acceder a un servicio de backend en funciones de Cloud Run con Google Cloud CLI. En esta guía de inicio rápido, también se describe cómo usar una clave de API para proteger tu backend del acceso no autorizado.

Antes de comenzar

En la consola de Google Cloud, ve a la página Panel y selecciona o crea un proyecto de Google Cloud.
Ir al panel

Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto nuevo en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.
Confirma que la facturación esté habilitada para tu proyecto.
Habilitar la facturación
Asegúrate de que Google Cloud CLI se haya descargado e instalado en tu máquina.
Descarga la CLI de gcloud
Actualiza los componentes de gcloud:
```
gcloud components update
```
Configura el proyecto predeterminado. Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.
```
gcloud config set project PROJECT_ID
```

Habilita los servicios obligatorios

API Gateway requiere que habilites los siguientes servicios de Google:

Nombre	Título
`apigateway.googleapis.com`	API de API Gateway
`servicemanagement.googleapis.com`	API de Administración de servicios
`servicecontrol.googleapis.com`	API de Service Control

Para confirmar que los servicios obligatorios están habilitados, haz lo siguiente:

gcloud services list

Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Para obtener más información sobre los servicios de gcloud, consulta Servicios de gcloud.

Implementa un backend de API

API Gateway se posiciona frente a un servicio de backend implementado y controla todas las solicitudes entrantes. En esta guía de inicio rápido, API Gateway enruta las llamadas entrantes a un backend de funciones de Cloud Run llamado helloGET que contiene la siguiente función:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Sigue los pasos de la Guía de inicio rápido: Usa Google Cloud CLI para descargar el código de muestra de las funciones de Cloud Run y, luego, implementar el servicio de backend de la función de Cloud Run.

Crea una API

Ahora estás listo para crear tu API en API Gateway.

Ingresa el siguiente comando, donde:
- API_ID especifica el nombre de tu API. Consulta los requisitos de ID de API para conocer los lineamientos de nombres de las APIs.
- PROJECT_ID especifica el nombre del proyecto de Google Cloud.
```
gcloud api-gateway apis create API_ID --project=PROJECT_ID
```
Por ejemplo:
```
gcloud api-gateway apis create my-api --project=my-project
```

Cuando el proceso finalice correctamente, puedes usar el siguiente comando para ver los detalles de la nueva API:

gcloud api-gateway apis describe API_ID --project=PROJECT_ID

Por ejemplo:

gcloud api-gateway apis describe my-api --project=my-project

Este comando muestra lo siguiente:

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Ten en cuenta el valor de la propiedad managedService. Este valor se usa para habilitar tu API en un paso posterior.

Crea una configuración de API

Antes de que se pueda usar API Gateway para administrar el tráfico al backend de tu API implementada, necesita una configuración de API.

Puedes crear una configuración de API con una especificación de OpenAPI que contenga anotaciones especializadas para definir el comportamiento elegido de API Gateway. La especificación de OpenAPI que se usa para esta guía de inicio rápido contiene instrucciones de enrutamiento a nuestro backend de funciones de Cloud Run:

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Para subir esta especificación de OpenAPI y crear una configuración de API con gcloud CLI, haz lo siguiente:

En la línea de comandos, crea un archivo nuevo llamado openapi2-functions.yaml.
Copia y pega el contenido de la especificación de OpenAPI que se muestra arriba en el archivo recién creado.
Edita el archivo de la siguiente manera:
1. En el campo title, reemplaza API_ID por el nombre de tu API y reemplaza optional-string por una breve descripción de tu elección. El valor de este campo se usa cuando se emiten claves de API que otorgan acceso a esta API.
2. En el campo address, reemplaza GCP_REGION por la región de Google Cloud de la función implementada y PROJECT_ID por el nombre de tu proyecto de Google Cloud.
Ingresa el siguiente comando, donde:
- CONFIG_ID especifica el nombre de la configuración de tu API.
- API_ID especifica el nombre de tu API.
- API_DEFINITION especifica el nombre del archivo de la especificación de OpenAPI.
- PROJECT_ID especifica el nombre del proyecto de Google Cloud.
- SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens para backends con autenticación configurada. Para obtener más información, consulta Cómo configurar una cuenta de servicio.
  Nota: La cuenta de servicio que se usa para crear una configuración de API para un backend de funciones de Cloud Run debe tener asignado el rol cloudfunctions.invoker.
```
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
```
Por ejemplo:
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
Esta operación puede tardar varios minutos en completarse, ya que la configuración de la API se propaga a los sistemas downstream. La creación de una configuración de API compleja puede tardar hasta diez minutos en completarse correctamente.

Nota: Si ejecutas este comando y recibes un error en el formulario FAILED_PRECONDITION: Service Account ... does not exist, consulta Configura una cuenta de servicio para asegurarte de que una cuenta de servicio esté habilitada para tu proyecto.
Nota: Solo se puede crear una configuración de API a la vez para una API determinada. Espera hasta que finalice la creación de la configuración antes de intentar crear una nueva para la misma API.

Después de crear la configuración de la API, puedes ver sus detalles. Para ello, ejecuta este comando:

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

Por ejemplo:

gcloud api-gateway api-configs describe my-config \
  --api=my-api --project=my-project

En el resultado, se muestran los detalles de configuración de la API, incluidos el nombre y el estado, como en el siguiente ejemplo:

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Cómo crear una puerta de enlace

Ahora implementa la configuración de la API en una puerta de enlace. La implementación de una configuración de API en una puerta de enlace define una URL externa que los clientes de API pueden usar para acceder a la API.

Ejecuta el comando siguiente para implementar la configuración de la API que acabas de crear en API Gateway:

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 nombre de la puerta de enlace.
API_ID especifica el nombre de la API de API Gateway asociada a esta puerta de enlace.
CONFIG_ID especifica el nombre de la configuración de API implementada en la puerta de enlace.
GCP_REGION es la región de Google Cloud para la puerta de enlace implementada.
Nota:
Los valores permitidos son los siguientes:
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
PROJECT_ID especifica el nombre del proyecto de Google Cloud.

Por ejemplo:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1 --project=my-project

Cuando el proceso finalice correctamente, usa 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

Por ejemplo:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 --project=my-project

Este comando muestra lo siguiente:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.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 que usas para probar tu implementación en el siguiente paso.

Prueba la implementación de tu API

Ahora puedes enviar solicitudes a tu API mediante la URL generada después de la implementación de tu puerta de enlace.

Ingresa el siguiente comando curl, donde:

DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
hello es la ruta de acceso que se especifica en la configuración de la API.

curl https://DEFAULT_HOSTNAME/hello

Por ejemplo:

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

El resultado es el siguiente:

Hello World!

Creaste e implementaste una API Gateway con éxito.

Protege el acceso mediante una clave de API

Para proteger el acceso al backend de la API, genera una clave de API asociada con tu proyecto y otorga a esa clave acceso para llamar a tu API. Consulta Cómo restringir el acceso a la API con claves de API para obtener más información.

Si aún no tienes una clave de API asociada con el proyecto de Google Cloud que usas en esta guía de inicio rápido, puedes agregar una mediante los pasos que se indican en Crea una clave de API.

Para proteger el acceso a tu puerta de enlace con una clave de API, sigue estos pasos:

Habilita la compatibilidad con claves de API para tu servicio. Ingresa el siguiente comando, donde:
- MANAGED_SERVICE_NAME especifica el nombre del servicio administrado que se creó cuando implementaste la API. Esto se puede ver en la propiedad Managed Service que se muestra con el comando gcloud apigee-gateway apis describe.
- PROJECT_ID especifica el nombre del proyecto de Google Cloud.
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
Por ejemplo:
```
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
```

Modifica las especificaciones de OpenAPI que se usan para crear la configuración de la API a fin de incluir instrucciones de modo que se pueda aplicar una política de seguridad de validación de claves de API en todo el tráfico. Agrega el tipo security y securityDefinitions como se muestra a continuación:

  # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

El securityDefinition configura tu API para que requiera una clave de API pasada como un parámetro de consulta llamado key cuando se solicita acceso a todas las rutas de acceso definidas en la especificación.

Usa el siguiente comando para crear una nueva configuración de API con la especificación de OpenAPI modificada:

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

Por ejemplo:

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

Ejecuta el siguiente comando para actualizar la puerta de enlace existente con la nueva configuración de API:

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

Por ejemplo:

gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Prueba tu clave de API

Una vez que hayas creado e implementado la API modificada, intenta enviarle una solicitud.

Ingresa el siguiente comando curl, donde:

DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
hello es la ruta de acceso que se especifica en la configuración de la API.

curl https://DEFAULT_HOSTNAME/hello

Por ejemplo:

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

Esto debería mostrar el siguiente error:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Ahora, ingresa el siguiente comando curl, en el que:

DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
hello es la ruta de acceso que se especifica en la configuración de la API.
API_KEY especifica la clave de API que creaste en el paso anterior.

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Ahora deberías ver Hello World! en la respuesta de tu API.

¡Felicitaciones! Protegiste correctamente el backend de tu API con una API Gateway. Ahora puedes comenzar a integrar nuevos clientes de API mediante la generación de claves de API adicionales.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta guía de inicio rápido, puedes hacer lo siguiente:

Como alternativa, también puedes borrar el proyecto de Google Cloud que se usó para este instructivo.

¿Qué sigue?

Obtén más información sobre API Gateway.
Revisa Configura el entorno de desarrollo.
Obtén información sobre la autenticación entre servicios.