Esta página se ha traducido con Cloud Translation API.

Configurar Cloud Endpoints OpenAPI para funciones de Cloud Run con ESPv2

En esta página se explica cómo configurar Cloud Endpoints en funciones de Cloud Run. Endpoints usa el proxy de servicios extensible V2 (ESPv2) como pasarela de APIs. Para gestionar las APIs de las funciones de Cloud Run, debes desplegar el contenedor ESPv2 prediseñado en Cloud Run. A continuación, protege tus funciones con gestión de identidades y accesos de Cloud Run Functions para que ESPv2 pueda invocarlas.

Con esta configuración, ESPv2 intercepta todas las solicitudes a tus funciones y realiza las comprobaciones necesarias (como la autenticación) antes de invocar la función. Cuando la función responde, ESPv2 recoge y registra la telemetría, como se muestra en la siguiente figura. Puedes ver las métricas de tu función en la página Endpoints > Services (Endpoints > Servicios) de la Google Cloud consola.

Arquitectura de Endpoints

Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y Arquitectura de Endpoints.

Migrar a ESPv2

En versiones anteriores de Cloud Endpoints, se podía usar Extensible Service Proxy (ESP) con funciones de Cloud Run. Si tienes APIs que quieres migrar a ESPv2, consulta Migrar a Extensible Service Proxy V2 para obtener más información.

Lista de tareas

Usa la siguiente lista de tareas mientras sigues el tutorial. Debes completar todas las tareas para seguir este tutorial.

Crea un Google Cloud proyecto y, si no has desplegado tus propias funciones de Cloud Run, despliega una función de backend de ejemplo. Consulta la sección Antes de empezar.
Reserva un nombre de host de Cloud Run para el servicio ESPv2. Consulta Reservar un nombre de host de Cloud Run.
Crea un documento de OpenAPI que describa tu API y configura las rutas a tus funciones de Cloud Run. Consulta Configurar Endpoints.
Implementa el documento de OpenAPI para crear un servicio gestionado. Consulta Desplegar la configuración de Endpoints.
Crea una imagen Docker de ESPv2 con la configuración de tu servicio Endpoints. Consulta Crear una imagen de ESPv2.
Despliega el contenedor ESPv2 en Cloud Run. A continuación, concede a ESPv2 el permiso de gestión de identidades y accesos (IAM) para invocar tu servicio. Consulta Desplegar el contenedor de ESPv2.
Invoca una función. Consulta Enviar una solicitud a la API.
Monitorizar la actividad de tus funciones. Consulta Seguimiento de la actividad de las APIs.
Evita que se te apliquen cargos en tu cuenta de Google Cloud . Consulta Liberar espacio.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

Antes de usar Endpoints para funciones de Cloud Run, te recomendamos que hagas lo siguiente:

Crea un proyecto de Google Cloud para usarlo cuando despliegues el contenedor de ESPv2 en Cloud Run.
Crea un proyecto o selecciona uno que ya tengas para tus funciones de Cloud Run.

Para configurarlo, sigue estos pasos:

En la Google Cloud consola, ve a la página Gestionar recursos y crea un proyecto.
Ir a la página Gestionar recursos
Comprueba que la facturación esté habilitada en tu proyecto.
Descubre cómo habilitar la facturación.
Anota el ID del proyecto, ya que lo necesitarás más adelante. En el resto de esta página, este ID de proyecto se denomina ESPv2_PROJECT_ID.
Anota el número de proyecto, ya que lo necesitarás más adelante. En el resto de esta página, este número de proyecto se denomina ESPv2_PROJECT_NUMBER.
Descarga e instala Google Cloud CLI.
Descargar gcloud CLI
Si no has desplegado tus propias funciones de Cloud Run de backend, sigue los pasos que se indican en la guía de inicio rápido para usar la CLI de Google Cloud para seleccionar o crear un proyecto Google Cloud y desplegar una función de ejemplo. Anota la región y el ID del proyecto en los que se han desplegado tus funciones. En el resto de esta página, este ID de proyecto se denomina FUNCTIONS_PROJECT_ID.

Reservar un nombre de host de Cloud Run

Debes reservar un nombre de host de Cloud Run para el servicio ESPv2 para configurar el documento OpenAPI o la configuración del servicio gRPC. Para reservar un nombre de host, desplegarás un contenedor de ejemplo en Cloud Run. Más adelante, desplegarás el contenedor de ESPv2 en el mismo servicio de Cloud Run.

Asegúrate de que la CLI de gcloud tenga autorización para acceder a tus datos y servicios.
1. Inicia sesión.
```
gcloud auth login
```
2. En la nueva pestaña del navegador que se abre, elige una cuenta que tenga el rol Editor u Propietario en el Google Cloud proyecto que has creado para implementar ESPv2 en Cloud Run.

Selecciona la región.

gcloud config set run/region us-central1

Despliega la imagen de ejemplo gcr.io/cloudrun/hello en Cloud Run. Sustituye ESPv2_CLOUD_RUN_SERVICE_NAME por el nombre que quieras usar para el servicio.

gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESPv2_PROJECT_ID

Si se completa correctamente, el comando muestra un mensaje similar al siguiente:

Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Por ejemplo, si asignas ESPv2_CLOUD_RUN_SERVICE_NAME a gateway:

Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

En este ejemplo, https://gateway-12345-uc.a.run.app es el CLOUD_RUN_SERVICE_URL y gateway-12345-uc.a.run.app es el v2_CLOUD_RUN_HOSTNAME.

Anota ESPv2_CLOUD_RUN_SERVICE_NAME y ESPv2_CLOUD_RUN_HOSTNAME. Más adelante, desplegarás ESPv2 en el servicio de ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. Especifique ESPv2_CLOUD_RUN_HOSTNAME en el campo host de su documento OpenAPI.

Configurar Endpoints

Debes tener un documento OpenAPI basado en la especificación de OpenAPI v2.0 que describa la superficie de tus funciones y los requisitos de autenticación. También debe añadir un campo específico de Google que contenga la URL de cada función para que ESPv2 tenga la información que necesita para invocar una función. Si no conoces OpenAPI, consulta la información general sobre OpenAPI para obtener más información.

Crea un archivo de texto llamado openapi-functions.yaml. (Por comodidad, en esta página se hace referencia al documento de OpenAPI con ese nombre de archivo, pero puedes darle otro nombre si lo prefieres).

Cada una de tus funciones debe figurar en la sección paths del archivo openapi-functions.yaml. Por ejemplo:

swagger: '2.0'
info:
  title: Cloud Endpoints + GCF
  description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
  version: 1.0.0
host: HOST
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
        protocol: h2
      responses:
        '200':
          description: A successful response
          schema:
            type: string

La indentación es importante para el formato YAML. Por ejemplo, el campo host debe estar al mismo nivel que info.

En el campo address de la sección x-google-backend, sustituya REGION por la Google Cloud región en la que se encuentra su función, FUNCTIONS_PROJECT_ID por el Google Cloud ID de su proyecto y FUNCTIONS_NAME por el nombre de su función. Por ejemplo:
```
x-google-backend:
  address: https://us-central1-myproject.cloudfunctions.net/helloGET
```
Si quieres proteger tu función de Cloud Run para que solo ESPv2 pueda invocarla, asegúrate de que el campo address incluya el nombre de la función si no se especifica jwt_audience. Por ejemplo:
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: CONSTANT_ADDRESS
```
Si se especifica jwt_audience, su valor también debe incluir el nombre de la función. Por ejemplo:
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
  jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: APPEND_PATH_TO_ADDRESS
```
ESPv2 genera un token de ID al llamar a la función de Cloud Run para la autenticación. El token de ID debe tener un audience adecuado que especifique el host y el nombre de la función. ESPv2 define el audience del token de ID con el valor del campo jwt_audience si se especifica. De lo contrario, usa el campo address.
En el campo host, especifica CLOUD_RUN_HOSTNAME, la parte del nombre de host de la URL que se ha reservado más arriba en Reservar un nombre de host de Cloud Run. No incluyas el identificador de protocolo, https://. Por ejemplo:
```
swagger: '2.0'
  info:
    title: Cloud Endpoints + GCF
    description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
    version: 1.0.0
  host: gateway-12345-uc.a.run.app
```
Toma nota del valor de la propiedad title en el archivo openapi-functions.yaml:
```
title: Cloud Endpoints + GCF
```
El valor de la propiedad title se convierte en el nombre del servicio Endpoints después de implementar la configuración.
Guarda el documento de OpenAPI.

Para obtener información sobre los campos del documento OpenAPI que requiere Endpoints, consulta Configurar Endpoints.

Desplegar la configuración de Endpoints

Para desplegar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Management para crear un servicio gestionado.

Para desplegar la configuración de Endpoints, sigue estos pasos:

Asegúrate de que estás en el directorio que contiene tu documento OpenAPI.
Sube la configuración y crea un servicio gestionado.
```
gcloud endpoints services deploy openapi-functions.yaml \
    --project ESPv2_PROJECT_ID
```
De esta forma, se crea un servicio de Endpoints con el nombre que hayas especificado en el campo host del archivo openapi-functions.yaml. El servicio se configura según tu documento de OpenAPI.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Cuando se complete la implementación, se mostrará un mensaje similar al siguiente:
```
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
```
CONFIG_ID es el ID único de configuración del servicio Endpoints que se crea durante la implementación. Por ejemplo:
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
El ID de configuración del servicio consta de una marca de fecha seguida de un número de revisión. Si vuelve a implementar openapi-functions.yaml el mismo día, el número de revisión se incrementará en el ID de configuración del servicio. Puedes ver la configuración del servicio y el historial de implementaciones en la página Endpoints > Services (Endpoints > Servicios) de la consola de Google Cloud .

Si aparece un mensaje de error, consulta Solucionar problemas de despliegue de la configuración de Endpoints.

Comprobando los servicios necesarios

Como mínimo, Endpoints y ESP requieren que los siguientes servicios de Google estén habilitados:

Nombre	Título
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

En la mayoría de los casos, el comando gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa correctamente, pero no habilita los servicios necesarios en las siguientes circunstancias:

Si has usado una aplicación de terceros, como Terraform, y no incluyes estos servicios.
Has desplegado la configuración de Endpoints en unGoogle Cloud proyecto en el que estos servicios se han inhabilitado explícitamente.

Usa el siguiente comando para confirmar que los servicios necesarios están habilitados:

gcloud services list

Si no ves los servicios necesarios, habilítalos:

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

También debes habilitar el servicio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar el ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

Después de desplegar la configuración de Endpoints, ve a la página Endpoints de la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.
En OpenAPI, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo host de tu especificación de OpenAPI. En gRPC, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo name de tu configuración de endpoints de gRPC.

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

Crear una imagen de ESPv2

Crea la configuración del servicio Endpoints en una nueva imagen de Docker de ESPv2. Más adelante, desplegarás esta imagen en el servicio de Cloud Run reservado.

Nota:

Este paso es obligatorio.

La configuración del servicio debe compilarse en una nueva imagen de Docker porque Cloud Run es un servicio de escalado a cero. Esto significa que, cuando no hay tráfico, se eliminan todas las instancias. Cuando el tráfico aumenta, se crean nuevas instancias bajo demanda. Este tipo de creación de instancias de servicio también se denomina inicio en frío. Consulta más información en la documentación sobre simultaneidad de Cloud Run.

Si la imagen de Docker no tuviera la configuración del servicio integrada, Cloud Run tendría que hacer dos llamadas a la API de Google Service Management al iniciar en frío. Estas llamadas se contabilizan en tu cuota de la API Service Management de Google.

Al compilar la configuración del servicio en la imagen de Docker de ESPv2, se eliminan las dos llamadas a la API y no se afecta al recuento de cuota del servicio Service Management de Google. Este paso también acelera la creación de la nueva instancia de servicio y reduce la latencia de las solicitudes que esperan la nueva instancia.

Debe volver a ejecutar todo este paso y volver a implementar el nuevo contenedor:

Cada vez que modifiques y vuelvas a desplegar la configuración del servicio Endpoints. De lo contrario, los cambios en la configuración del servicio no se propagarán a ESPv2.
Cuando se lanza una nueva versión de ESPv2. De lo contrario, se mantendrá desplegada la versión anterior de ESPv2.

Para compilar la configuración del servicio en una nueva imagen de Docker de ESPv2, haz lo siguiente:

Descarga esta secuencia de comandos en tu máquina local, donde esté instalada la CLI de gcloud.

Nota:
Este script requiere bash. Si no usas macOS o Linux, puedes ejecutarlo en Cloud Shell, Compute Engine o el subsistema de Windows para Linux.
Ejecuta la secuencia de comandos con el siguiente comando:
```
chmod +x gcloud_build_image

./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESPv2_PROJECT_ID
```
Nota:
Este script está diseñado para crear una carpeta en el directorio /tmp. Asegúrate de que tienes acceso de escritura al directorio /tmp al ejecutar esta secuencia de comandos.

Si no tienes acceso de escritura al directorio /tmp, debes modificar la secuencia de comandos para especificar un directorio alternativo en el que tengas el acceso necesario para crear carpetas.

En ESPv2_CLOUD_RUN_HOSTNAME, especifica el nombre de host de la URL que has reservado anteriormente en Reservar un nombre de host de Cloud Run. No incluyas el identificador de protocolo, https://.

Por ejemplo:
```
chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id
```
La secuencia de comandos usa el comando gcloud para descargar la configuración del servicio, compilarla en una nueva imagen de ESPv2 y subir la nueva imagen al registro de contenedores de tu proyecto. La secuencia de comandos usa automáticamente la versión más reciente de ESPv2, que se indica con el símbolo ESPv2_VERSION en el nombre de la imagen de salida. La imagen de salida se sube a:
```
gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Por ejemplo:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Nota:
Pasa la marca -z a la secuencia de comandos para generar la imagen en otra ubicación del registro.

Por ejemplo, para enviar la imagen de ESPv2 generada a un centro de datos de la Unión Europea, pasa -z eu a la secuencia de comandos.

Desplegar el contenedor de ESPv2

Despliega el servicio de Cloud Run de ESPv2 con la nueva imagen que has creado anteriormente. Sustituye CLOUD_RUN_SERVICE_NAME por el mismo nombre de servicio de Cloud Run que usaste cuando reservaste el nombre de host anterior en Reservar un nombre de host de Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID
```
Nota:
Si quieres que ESPv2 gestione el acceso, usa la marca --allow-unauthenticated para asegurarte de que ESPv2 verifique el token JWT. Si no se usa la marca, el token JWT se intercepta y lo verifica el servidor de gestión de identidades y accesos de Cloud Run <a=" docs="" managing-access"="" run="" securing="">control de acceso</a>. Como IAM y ESPv2 usan el mismo encabezado Authorization, no funcionan juntos. Asegúrate de usar solo uno de ellos. Recomienda usar IAM en lugar de ESPv2 para gestionar el acceso.</a=">
Si quieres configurar Endpoints para que use opciones de inicio de ESPv2 adicionales, como habilitar CORS, puedes transferir los argumentos en la variable de entorno ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESPv2_PROJECT_ID
```
Para obtener más información y ejemplos sobre cómo definir la variable de entorno ESPv2_ARGS, incluida la lista de opciones disponibles e información sobre cómo especificar varias opciones, consulta Extensible Service Proxy V2 Beta flags (Banderas de la versión beta de Extensible Service Proxy V2).
Concede permiso a ESPv2 para llamar a Service Management y Service Control.

En la Google Cloud consola, ve a la página Cloud Run.

Ir a la página de Cloud Run

Puedes ver la instancia de Cloud Run que has desplegado y la cuenta de servicio asociada.
Concede los permisos necesarios a la cuenta de servicio:

gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/servicemanagement.serviceController

¿Qué son los roles y los permisos?

Concede permiso a ESPv2 para invocar tus funciones. Ejecuta el siguiente comando para cada función. En el siguiente comando:

Nota:
Este paso no es necesario si el servicio de Cloud Run de ESPv2 se implementa sin usar la marca --service-account y el servicio backend BACKEND_SERVICE_NAME se implementa en el proyecto ESPv2_PROJECT_NUMBER.
- Sustituye FUNCTION_NAME por el nombre de tu función y FUNCTION_REGION por la región en la que se ha desplegado la función. Si usas la función creada en la guía de inicio rápido sobre el uso de la CLI de Google Cloud, usa helloGET como nombre.
- Sustituye ESPv2_PROJECT_NUMBER por el número del proyecto que has creado para ESPv2. Una forma de encontrarlo es ir a la página IAM de la consola de Google Cloud y buscar la cuenta de servicio de Compute predeterminada, que es la cuenta de servicio que se usa en la marca member.
```
gcloud functions add-iam-policy-binding FUNCTION_NAME \
   --region FUNCTION_REGION \
   --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role "roles/cloudfunctions.invoker" \
   --project FUNCTIONS_PROJECT_ID
```

Para obtener más información, consulta Gestionar el acceso mediante IAM.

Enviar solicitudes a la API

En esta sección se muestra cómo enviar solicitudes a tu API.

Crea una variable de entorno para el nombre de tu servicio Endpoints. Es el nombre que has especificado en el campo host de tu documento de OpenAPI. Por ejemplo:
- Linux o macOS:
  
  export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
- Windows PowerShell:
  
  $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux o macOS

Usa curl para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_HOST que has definido en el paso anterior.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

PowerShell

Usa Invoke-WebRequest para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_HOST que has definido en el paso anterior.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

En el ejemplo anterior, las dos primeras líneas terminan en una comilla inversa. Cuando pegues el ejemplo en PowerShell, asegúrate de que no haya ningún espacio después de las comillas inversas. Para obtener información sobre las opciones que se usan en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

Aplicación de terceros

Puedes usar una aplicación de terceros, como la extensión del navegador Chrome Postman, para enviar una solicitud.

Selecciona GET como verbo HTTP.
En el encabezado, selecciona la clave content-type y el valor application/json.
Usa la URL real en lugar de la variable de entorno. Por ejemplo:
```
https://gateway-12345-uc.a.run.app/hello
```

Si no has recibido una respuesta correcta, consulta la sección Solucionar problemas de errores de respuesta.

Acabas de desplegar y probar una API en Endpoints.

Monitorizar la actividad de la API

Consulta los gráficos de actividad de tu API en la página Endpoints > Service ( Google Cloud consola).

Ver gráficos de actividad de Endpoints

La solicitud puede tardar unos instantes en reflejarse en los gráficos.
Consulta los registros de solicitudes de tu API en la página Explorador de registros. Ver los registros de solicitudes de Endpoints

Limpieza

Para evitar que se apliquen cargos en tu cuenta de Google Cloud por los recursos utilizados en esta página, sigue estos pasos.

Consulta Eliminar una API y sus instancias para obtener información sobre cómo detener los servicios que se usan en este tutorial.