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

Guía de inicio rápido: 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 y acceder a un servicio de backend en Cloud Run Functions 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
Verifica 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`	Service Control API

Usa los siguientes comandos para habilitar estos servicios:

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 Cloud Run Function 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 nomenclatura de las APIs.
```
gcloud api-gateway apis create API_ID 
```
Por ejemplo:
```
gcloud api-gateway apis create my-api
```

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

gcloud api-gateway apis describe API_ID

Por ejemplo:

gcloud api-gateway apis describe my-api

Este comando devuelve 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'

Toma nota del 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 descripción de OpenAPI que contenga anotaciones especializadas para definir el comportamiento elegido de API Gateway. Para obtener más detalles sobre las extensiones de OpenAPI compatibles, consulta lo siguiente:

La descripción de OpenAPI que se usa para esta guía de inicio rápido contiene instrucciones de enrutamiento a nuestro backend de la función de Cloud Run:

OpenAPI 2.0

# openapi-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://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

Para subir esta descripció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 openapi-functions.yaml.
Copia y pega el contenido de la descripción de OpenAPI 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 optional-string por una breve descripción de tu elección. El valor de este campo se usa cuando se generan claves de API que otorgan acceso a esta API.
2. En el campo address, reemplaza GATEWAY_LOCATION por la región Google Cloud de la función implementada y PROJECT_ID por el nombre de tu proyecto Google Cloud .
Ingresa el siguiente comando, donde:
- CONFIG_ID especifica el nombre de tu configuración de API.
- API_ID especifica el nombre de tu API.
- API_DEFINITION especifica el nombre de archivo de la especificación de OpenAPI.
- 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 Cloud Run Functions debe tener asignado el rol de cloudfunctions.invoker.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --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 \
  --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 posteriores. 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 con el formato FAILED_PRECONDITION: Service Account ... does not exist, consulta Configura una cuenta de servicio para confirmar 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 a que finalice la creación de la configuración antes de intentar crear una nueva configuración 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

Por ejemplo:

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

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'

Crea 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

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 Google Cloud región 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 de tu proyecto Google Cloud .

Por ejemplo:

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

Cuando el proceso finalice con éxito, usa el siguiente comando para ver los detalles de la puerta de enlace:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

Por ejemplo:

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

Este comando devuelve 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'

Toma nota del valor de la propiedad defaultHostname. Esta es la parte del nombre de host de la URL de la puerta de enlace que usarás para probar tu implementación en el siguiente paso.

Prueba tu implementación de la 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 con 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 Restricting API access with API keys para obtener más información.

Si aún no tienes una clave de API asociada con el proyecto Google Cloud que usas en esta guía de inicio rápido, puedes agregar una siguiendo 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. Puedes ver esto en la propiedad de servicio administrado que aparece con el comando gcloud apigee-gateway apis describe.
- PROJECT_ID especifica el nombre de tu proyecto 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 la descripción de OpenAPI que se usa para crear la configuración de la API de modo que incluya instrucciones para 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:

OpenAPI 2.0

  # 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://GATEWAY_LOCATION-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.

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

El securitySchemes 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 \
--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 tu 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

Por ejemplo:

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

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, 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.
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 Google Cloud que se usó para este instructivo.

¿Qué sigue?

Obtén más información sobre API Gateway.
Sigue los pasos para configurar el entorno de desarrollo
Obtén más información sobre la autenticación entre servicios.