Configura OpenAPI de Cloud Endpoints para el entorno estándar con ESPv2

Configura OpenAPI de Cloud Endpoints para el entorno estándar con ESPv2

En esta página, se muestra cómo configurar Cloud Endpoints para App Engine. Endpoints usa el proxy de servicio extensible V2 (ESPv2) como una puerta de enlace de la API. Si deseas proporcionar administración de API para App Engine, debes implementar el contenedor ESPv2 compilado con anterioridad en Cloud Run. Luego, debes proteger tu app con Identity-Aware Proxy (IAP) para que solo ESPv2 pueda invocarlo.

Con esta configuración, el ESPv2 intercepta todas las solicitudes enviadas a tu app y realiza las verificaciones necesarias (como la autenticación) antes de invocar la app. Cuando esta responde, el ESPv2 recopila e informa la telemetría, como se muestra en la siguiente figura. Puedes ver las métricas de tu app en la página Endpoints > Services de Google Cloud Console.

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

Migra a ESPv2

Las versiones anteriores de Cloud Endpoints admiten el uso del proxy de servicio extensible (ESP) con Cloud Run. Si tienes API existentes que deseas migrar a ESPv2, consulta Migra al proxy de servicio extensible V2 para obtener más información.

Lista de tareas

Usa la lista de tareas siguiente a medida que avanzas en el instructivo. Todas las tareas son obligatorias para que Endpoints administre tu app.

1. Crea un proyecto de Google Cloud y, si no has implementado tu propio App Engine, implementa una app de backend de muestra. Consulta Antes de comenzar.
2. Configura IAP para proteger tu app. Consulta la sección sobre cómo configurar IAP.
3. Reserva un nombre de host de Cloud Run para el servicio de ESPv2. Consulta Reserva un nombre de host de Cloud Run.
4. Crea un Documento de OpenAPI que describa tu API y, luego, configura las rutas a App Engine. Consulta Cómo configurar Endpoints.
5. Implementa el documento de OpenAPI para crear un servicio administrado. Consulta Cómo implementar la configuración de Endpoints.
6. Compila una nueva imagen de Docker del ESPv2 con tu configuración de servicio de Endpoints. Consulta Compila una imagen de ESPv2 nueva.
7. Implementa el contenedor de ESPv2 en Cloud Run. Luego, otórgale al ESPv2 el permiso de administración de identidades y accesos (IAM) para invocar tu servicio. Consulta Implementa el contenedor del ESPv2.
8. Invoca la app. Consulta Envía una solicitud a la API.
9. Realiza seguimiento de la actividad de tus apps. Consulta Cómo realizar un seguimiento de la actividad de la API.
10. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Realiza una limpieza.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• App Engine
• Cloud Run
• Endpoints

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Cuando finalices las tareas que se describen en este documento, puedes borrar los recursos que creaste para evitar que continúe la facturación. Para obtener más información, consulta Cómo realizar una limpieza.

Antes de comenzar

Para realizar la configuración, sigue estos pasos:

1. En la consola de Google Cloud, ve a la página Administrar recursos y crea un proyecto.

   Ir a la página Administración de recursos

2. Asegúrate de tener habilitada la facturación para tu proyecto.

   Aprende a habilitar la facturación

3. Toma nota del ID del proyecto, ya que lo necesitarás más tarde. En el resto de la página, este ID del proyecto se denomina ESP_PROJECT_ID.

4. Anota el número del proyecto, ya que será necesario más tarde. En el resto de esta página, este número de proyecto se denomina ESP_PROJECT_NUMBER.

5. Descarga e instala Google Cloud CLI.

   Descarga la CLI de gcloud

6. Si no implementaste tu propia aplicación de App Engine, sigue los pasos de la Guía de inicio rápido de App Engine. Toma nota de la región y del ID del proyecto donde se implementan tus apps. En el resto de esta página, este ID del proyecto se denomina APP_PROJECT_ID.

Configura IAP para proteger tu app

Para proteger tu app de App Engine, debes usar el Identity Aware Proxy (IAP) a fin de asegurarte de que las solicitudes se autentiquen.

Sigue los pasos para habilitar IAP y asegurarte de poder acceder a tu aplicación.

Además, cuando configures el cliente de OAuth, toma nota de client_id de OAuth, que se conoce como IAP_CLIENT_ID en este instructivo.

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.

Nota: Cada servicio de Cloud Run de ESPv2 solo puede asociarse con un documento de OpenAPI o una configuración de servicio de gRPC. Reserva un nombre de host de Cloud Run nuevo para cada documento.

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 OpenAPI Specification v2.0 que describa la superficie de tus apps y cualquier requisito de autenticación. También debes agregar un campo específico de Google que contenga la URL de cada app a fin de que ESPv2 tenga la información necesaria para invocar una app. 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-appengine.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. La app de backend de App Engine se define en la parte superior del archivo openapi-appengine.yaml, en una definición x-google-backend. Por ejemplo:

     swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: CLOUD_RUN_HOSTNAME
     schemes:
       - https
     produces:
       - application/json
     x-google-backend:
       address: https://APP_PROJECT_ID.REGION.r.appspot.com
       jwt_audience: IAP_CLIENT_ID
       protocol: h2
     paths:
       /:
         get:
           summary: Greet a user
           operationId: hello
           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 APP_PROJECT_ID por su ID de proyecto de Google Cloud, REGION con la región de GCP donde implementaste App Engine y IAP_CLIENT_ID por el ID del cliente de OAuth que se creó cuando configuraste IAP.

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 + App Engine
       description: Sample API on Cloud Endpoints with an App Engine 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-appengine.yaml:

   title: Cloud Endpoints + App Engine

   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-appengine.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-appengine.yaml. El servicio se configura según tu documento de OpenAPI.

   Mientras se crea y configura el servicio, Service Management 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-appengine.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

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:

Name	Título
servicemanagement.googleapis.com	API de Administración de servicios
servicecontrol.googleapis.com	Service Control API

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.

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 escala a cero. Esto significa que cuando no hay tráfico, se borran todas las instancias. Cuando el tráfico aumenta, se crean instancias nuevas según se necesiten. Este tipo de creación de instancia de servicio también se denomina inicio en frío. Consulta la documentación sobre simultaneidad de Cloud Run para obtener más información.

Si la imagen de Docker no tuviera incorporada la configuración del servicio integrada, Cloud Run tendría que realizar dos llamadas a la API de Google ServiceManagement en el inicio en frío. Estas llamadas se descuentan de tu cuota de la API de Google ServiceManagement.

Cuando compilas la configuración del servicio en la imagen de Docker de ESPv2, quitas las dos llamadas a la API y no influyes en el recuento de cuotas del servicio de Google ServiceManagement. Con este paso, también se acelera la creación de la nueva instancia de servicio y se reduce la latencia de las solicitudes que esperan la instancia nueva.

Debes volver a ejecutar este paso completo y volver a implementar el contenedor nuevo:

• Cada vez que modificas y vuelves a implementar la configuración del servicio de Endpoints. De lo contrario, los cambios en la configuración del servicio no se propagarán al ESPv2.
• Cuando se lanza una nueva versión del ESPv2. De lo contrario, la versión anterior de ESPv2 permanecerá implementada.

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.

   Nota:

   Para esta secuencia de comandos, se requiere Bash. Si no usas macOS o Linux, puedes ejecutarla en Cloud Shell, Compute Engine o el subsistema de Windows para Linux.

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"

   Nota:

   Pasa la marca -z a la secuencia de comandos para generar la imagen en una ubicación de registro diferente.

   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.

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

   Nota:

   Si deseas que el ESPv2 administre el acceso, usa la marca --allow-unauthenticated para asegurarte que el ESPv2 verifique el token JWT. Si no se usa la marca, el token JWT se intercepta y verifica mediante el servidor de IAM de <a=" docs="" managing-access"="" run="" securing="">control de acceso de Cloud Run. Dado que IAM y ESPv2 usan el mismo encabezado de autorización, no funcionan juntos; por lo tanto, asegúrate de usar solo uno de ellos. Se recomienda usar IAM en lugar del ESPv2 para administrar el acceso.</a=">

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.

3. Otorga permiso al ESPv2 para invocar tu app protegida por IAP. Ejecuta el siguiente comando para cada servicio. Para el siguiente comando, sigue estos pasos:
   • Reemplaza APP_PROJECT_ID por el nombre del ID de tu proyecto de App Engine.
   • Reemplaza ESP_PROJECT_NUMBER por el número del proyecto que creaste para ESPv2. Una forma de hacerlo es ir a la consola de IAM y buscar la cuenta de servicio predeterminada de Compute Engine, que es la cuenta de servicio que se usa en la marca “member”.

     gcloud projects add-iam-policy-binding APP_PROJECT_ID \
         --member "serviceAccount:[e-mail]" \
         --role "roles/iap.httpsResourceAccessor"
       

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"

Linux o macOS

Usa curl para enviar una solicitud HTTP con la variable de entorno ENDPOINTS_HOST que estableciste en el paso anterior.

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

PowerShell

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

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

En el ejemplo anterior, las dos primeras líneas terminan en un acento grave. Cuando pegues el ejemplo en PowerShell, asegúrate de que no quede un espacio después de los acentos graves. Para obtener más información sobre las opciones usadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

App de terceros

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

• Selecciona GET como el verbo HTTP.
• Para 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/
  

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!

Nota: Si quieres contarnos qué te gustó de este instructivo, envíanos tus comentarios al final de esta página. Tus comentarios nos ayudarán a mejorar estos instructivos.
Si recibiste un error, únete al grupo de Google google-cloud-endpoints y cuéntanos cuál fue el problema. En este grupo encontrarás respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

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.

Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página.

Consulta Borrar una API y las instancias de la API para obtener información acerca de cómo detener los servicios que se usan en este instructivo.

¿Qué sigue?

• Obtén más información sobre Cloud Run
• Obtén más información sobre cómo implementar la configuración de Endpoints
• Compartir API protegidas por claves de API
• Obtén más información sobre la autenticación
• Obtener más información sobre las opciones del servicio de asistencia de la comunidad