Configura OpenAPI de Cloud Endpoints para funciones de Cloud Run con ESPv2

Reserva un nombre de host de Cloud Run

Debes reservar un nombre de host de Cloud Run para el servicio ESPv2 a fin de configurar el documento de OpenAPI o la configuración de servicio de gRPC. Para reservar un nombre de host, implementarás un contenedor de muestra en Cloud Run. Luego, implementa el contenedor del ESPv2 en el mismo servicio de Cloud Run.

1. Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y servicios.
   1. Accede.

      gcloud auth login

   2. En la nueva pestaña que se abre, elige una cuenta que tenga la función de Editor o Propietario en el proyecto de Google Cloud que creaste para implementar ESPv2 en Cloud Run.
2. Configura la región.

   gcloud config set run/region us-central1

3. Implementa la imagen de muestra gcr.io/cloudrun/hello en Cloud Run Reemplaza CLOUD_RUN_SERVICE_NAME por el nombre que deseas usar para el servicio.

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

   Cuando el proceso finalice correctamente, el comando mostrará un mensaje similar a este:

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

   Por ejemplo, si configuras CLOUD_RUN_SERVICE_NAME como 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 CLOUD_RUN_SERVICE_URL y gateway-12345-uc.a.run.app es CLOUD_RUN_HOSTNAME.

4. Toma nota de CLOUD_RUN_SERVICE_NAME y CLOUD_RUN_HOSTNAME. Luego, implementarás ESPv2 en el servicio CLOUD_RUN_SERVICE_NAME de Cloud Run. Debes especificar CLOUD_RUN_HOSTNAME en el campo host del documento de OpenAPI.

Configura Endpoints

Debes tener un documento de OpenAPI basado en la especificación de OpenAPI v2.0 que describa la superficie de tus funciones y cualquier requisito de autenticación. También debes agregar un campo específico de Google que contenga la URL de cada función de modo que el ESPv2 tenga la información que necesita para invocar una función. Si eres nuevo en OpenAPI, consulta Descripción general de OpenAPI para obtener más información.

1. Crea un archivo de texto denominado openapi-functions.yaml. (Para mayor comodidad, esta página hace referencia al documento de OpenAPI con ese nombre de archivo, pero puedes darle otro nombre si así lo prefieres).
2. Cada una de tus funciones debe aparecer 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 sangría es importante para el formato yaml. Por ejemplo, el campo host debe estar al mismo nivel que info.
3. En el campo address de la sección x-google-backend, reemplaza REGION por la región de Google Cloud donde se encuentra tu función, FUNCTIONS_PROJECT_ID por el ID de tu proyecto de Google Cloud y FUNCTIONS_NAME por el nombre de tu función. Por ejemplo:

   x-google-backend:
     address: https://us-central1-myproject.cloudfunctions.net/helloGET

   Si deseas proteger tu función de Cloud Run con solo permitir que la versión ESPv2 la invoque, 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

   El ESPv2 genera un token de ID cuando se llama 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. El ESPv2 establece el audience para el token de ID con el valor en el campo jwt_audience si se especifica, de lo contrario, usa el campo address.

4. En el campo host, especifica CLOUD_RUN_HOSTNAME, la parte del nombre de host de la URL que se reservó antes en Reserva un nombre de host de Cloud Run. No incluyas https://, el identificador de protocolo. 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

5. Ten en cuenta el valor de la propiedad title del archivo openapi-functions.yaml:

   title: Cloud Endpoints + GCF

   El valor de la propiedad title se convierte en el nombre del servicio de Endpoints después de que implementas la configuración.

6. Guarda tu documento de OpenAPI.

Para obtener información sobre los campos del documento de OpenAPI que Endpoints requiere, consulta la sección sobre cómo configurar Endpoints.

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa la Administración de servicios para crear un servicio administrado.

Para implementar la configuración de Endpoints, haz lo siguiente:

1. Asegúrate de estar en el directorio que contiene el documento de OpenAPI.

2. Sube la configuración y crea un servicio administrado.

   gcloud endpoints services deploy openapi-functions.yaml \
       --project ESP_PROJECT_ID

   Con este proceso, se crea un servicio de Endpoints nuevo con el nombre que especificaste en el campo host del archivo openapi-functions.yaml. El servicio se configura según tu documento de OpenAPI.

   Mientras se crea y configura el servicio, Administración de servicios exporta la información a la terminal. Cuando se completa la implementación, aparece un mensaje similar al siguiente:

   Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

   CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó la implementación. Por ejemplo:

   Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

   El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si vuelves a implementar openapi-functions.yaml el mismo día, se incrementa el número de revisión 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 > Servicios de la consola de Google Cloud.

   Si recibes un mensaje de error, consulta Cómo solucionar problemas en la implementación de la configuración de Endpoints.

Verifica los servicios requeridos

En la mayoría de los casos, el comando de gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa de manera correcta sin habilitar los servicios requeridos en las circunstancias siguientes:

• Usaste una aplicación de terceros, como Terraform, y no incluiste estos servicios.

• Si implementaste la configuración de Endpoints en un proyecto existente de Google Cloud en el que se inhabilitaron explícitamente estos servicios

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

gcloud services list

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

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

También habilita el servicio de Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar la variable ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

• Después de implementar la configuración de Endpoints, ve a la página Endpoints en la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.

• Para OpenAPI, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo host de tu especificación de OpenAPI. Para gRPC, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo name de tu configuración de Endpoints de gRPC.

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

Compila una imagen de ESPv2 nueva

Compila la configuración de servicio de Endpoints en una nueva imagen de Docker del ESPv2. Luego, implementarás esta imagen en el servicio reservado de Cloud Run.

Si quieres compilar la configuración de servicio en una imagen de Docker de ESPv2 nueva, sigue estos pasos:

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

2. Ejecuta la secuencia de comandos con el siguiente comando:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   Para CLOUD_RUN_HOSTNAME, especifica el nombre de host de la URL que reservaste antes en Reserva un nombre de host de Cloud Run. No incluyas https://, el identificador de protocolo.

   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

3. La secuencia de comandos usa el comando de gcloud para descargar la configuración del servicio, compilarla en una imagen de ESPv2 nueva y subir la imagen nueva al registro de contenedores del proyecto. La secuencia de comandos usa automáticamente la última versión del ESPv2 indicada por ESP_VERSION en el nombre de la imagen de salida. La imagen resultante se sube a la siguiente ubicación:

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-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"

Implementa el contenedor de ESPv2

1. Implementa el servicio ESPv2 de Cloud Run con la imagen nueva que compilaste antes. Reemplaza CLOUD_RUN_SERVICE_NAME por el mismo nombre de servicio de Cloud Run que usaste cuando reservaste el nombre de host anterior en Reserva un nombre de host de Cloud Run:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESP_PROJECT_ID

2. Si quieres configurar Endpoints para usar opciones adicionales de inicio de ESPv2, como habilitar CORS, puedes pasar los argumentos en la variable de entorno ESPv2_ARGS:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESP_PROJECT_ID

   Para obtener más información y ejemplos sobre cómo configurar la variable de entorno ESPv2_ARGS, incluida la lista de opciones disponibles y la información sobre cómo especificar varias opciones, consulta Marcas del proxy de servicio extensible V2 Beta.

3. Otorga permiso a ESPv2 para llamar a Service Management y Control de servicios.

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

Ir a la página Cloud Run

• Puedes ver la instancia de Cloud Run que implementaste y la cuenta de servicio asociada a ella.
• Otorga los permisos necesarios a la cuenta de servicio:

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

Para obtener más información, consulta ¿Qué son las funciones y los permisos?

4. Otórgale a ESPv2 permiso para invocar tus funciones. Ejecuta el siguiente comando para cada función. En el siguiente comando, haz lo siguiente:

   • Reemplaza FUNCTION_NAME por el nombre de tu función y FUNCTION_REGION por la región en la que se implementa la función. Si usas la función creada en la Guía de inicio rápido: Usa Google Cloud CLI, usa helloGET como nombre.
   • Reemplaza ESP_PROJECT_NUMBER por el número del proyecto que creaste para ESPv2. Una forma de hacerlo es ir a la página de IAM en la consola de Google Cloud y buscar la cuenta de servicio de procesamiento 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:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/cloudfunctions.invoker" \
      --project FUNCTIONS_PROJECT_ID
   

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

Envía solicitudes a la API

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

1. Crea una variable de entorno para el nombre de servicio de Endpoints. Este es el nombre que especificaste 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"

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

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

Si no obtuviste una respuesta exitosa, consulta la página sobre cómo solucionar errores de respuesta.

¡Acabas de implementar y probar una API en Endpoints!

Realiza un seguimiento de la actividad de la API

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

   Ver los gráficos de actividad de Endpoints

   La solicitud puede tardar unos minutos en reflejarse en los gráficos.

2. Consulta los registros de solicitud de tu API en la página Explorador de registros. Ver los registros de solicitud de Endpoints

Crea un portal de desarrolladores para la API

Puedes utilizar el Portal de Cloud Endpoints para crear un portal de desarrolladores, un sitio web en el que puedes interactuar con la API de muestra. Para obtener más información, consulta Descripción general del Portal de Cloud Endpoints.