Comienza a usar Endpoints para Cloud Functions

En esta página, se muestra cómo configurar Cloud Endpoints para Cloud Functions. Endpoints usa el proxy de servicio extensible V2 Beta (ESPv2 Beta) como puerta de enlace de la API. A fin de proporcionar administración de API para Cloud Functions, implementa el contenedor de ESPv2 Beta previamente compilado en Cloud Run. A continuación, protege tus funciones con la IAM de Cloud Functions para que ESPv2 Beta pueda invocarlas.

Con esta configuración, el ESPv2 Beta intercepta todas las solicitudes a tus funciones y realiza las verificaciones necesarias (como la autenticación) antes de invocar la función. Cuando la función responde, ESPv2 Beta informa y recopila la telemetría. Puedes ver las métricas de tu función en la página Endpoints > Servicios en 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 Beta

Las versiones anteriores de Cloud Endpoints admitían el uso del Extensible Service Proxy (ESP) con Cloud Functions. Si tienes API existentes que deseas migrar a ESPv2 Beta, consulta Migra a Proxy de servicio extensible V2 Beta para obtener más información.

Lista de tareas

Usa la siguiente lista de tareas mientras trabajas en el instructivo. Todas las tareas son obligatorias para completar el instructivo.

  1. Crea un proyecto de Google Cloud y, si no has implementado tu propio Cloud Functions, implementa una función de muestra. Consulta Antes de comenzar.
  2. Implementa el contenedor de ESPv2 Beta en Cloud Run. Consulta Implementa el ESPv2 Beta.
  3. Crea un documento de OpenAPI que describa tu API y configure las rutas a Cloud Functions. Consulta Configura Endpoints.
  4. Implementa el documento de OpenAPI para crear un servicio administrado. Consulta Implementar la configuración de Endpoints.
  5. Compila y, luego, implementa una nueva imagen de Docker de ESPv2 Beta con tu configuración de servicio de Endpoints. Después, otórgale a ESPv2 Beta el permiso de Cloud Identity and Access Management (Cloud IAM) para invocar tus funciones. Consulta la sección sobre cómo crear una imagen de ESPv2 Beta nueva.
  6. Invoca una función. Consulta Enviar una solicitud a la API.
  7. Realiza un seguimiento de la actividad en tus funciones. Consulta Realizar un seguimiento de la actividad de la API.
  8. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Cómo realizar una limpieza.

Antes de comenzar

Debido a que Endpoints para Cloud Functions se encuentra en estado Beta, te recomendamos lo siguiente:

  • Crea un proyecto de Google Cloud nuevo para usarlo cuando implementes el contenedor ESPv2 Beta en Cloud Run.

  • Crea un proyecto nuevo o selecciona uno existente para Cloud Functions.

Para realizar la configuración:

  1. En Cloud Console, 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.

    Aprender 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. Instala el SDK de Cloud.

    Descargar el SDK de Cloud

  6. Si no has implementado tu propia Cloud Functions, sigue los pasos que aparecen en la Guía de inicio rápido: usar la herramienta de línea de comandos de gcloud para seleccionar o crear un proyecto de Google Cloud e implementar una función de muestra. Toma nota de la región y del ID del proyecto donde se implementan tus funciones. En el resto de esta página, este ID del proyecto se denomina FUNCTIONS_PROJECT_ID.

Implementa ESPv2 Beta

Para implementar el contenedor de ESPv2 Beta en Cloud Run, haz lo siguiente:

  1. Asegúrate de que el SDK de Cloud esté autorizado 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 Editor o Propietario en el proyecto de Google Cloud que creaste para implementar ESPv2 Beta en Cloud Run.
  2. Configura la región.
    gcloud config set run/region us-central1
  3. Implementa ESPV2 Beta 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/endpoints-release/endpoints-runtime-serverless:2" \
            --allow-unauthenticated \
            --platform managed \
            --project=ESP_PROJECT_ID
        

    Cuando el proceso finalice con éxito, el comando mostrará un mensaje similar al siguiente:

        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_HOSTNAME. Debes especificar CLOUD_RUN_HOSTNAME en el campo host de tu documento de OpenAPI.
  5. Para verificar si la versión inicial de ESPv2 Beta se implementó en Cloud Run, visita la CLOUD_RUN_SERVICE_URL de tu navegador web. Debería ver un mensaje de advertencia sobre una variable de entorno faltante. Este mensaje de advertencia es esperado y aparecerá hasta que se complete el paso Cómo crear una nueva imagen Beta ESPv2.
  6. Tu servicio de Cloud Run es público en Internet. Si deseas agregar capacidades de autenticación, te recomendamos que uses uno de los métodos de autenticación que admite Endpoints.

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 ESPv2 Beta tenga la información que necesita para invocar una función. Si es la primera vez que usas OpenAPI, consulta Descripción general de OpenAPI para obtener más información.

  1. Crea un archivo de texto denominado openapi-functions.yaml. Por conveniencia, esta página hace referencia al documento de OpenAPI mediante ese nombre de archivo, pero puedes nombrarlo de otra manera si 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/helloGET
                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 en el mismo nivel que info.
  3. En el campo address de la sección x-google-backend, reemplaza REGION con la región de Google Cloud donde se encuentra tu función y FUNCTIONS_PROJECT_ID con el ID de tu proyecto de Google Cloud. Por ejemplo:
        x-google-backend:
                address: https://us-central1-myproject.cloudfunctions.net/helloGET
  4. En el campo host, especifica CLOUD_RUN_HOSTNAME, la parte del nombre de host de la URL que creó Cloud Run cuando implementaste el ESPv2 Beta en Implementa el ESPv2 Beta. 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 requiere Endpoints, consulta Configura Endpoints.

Implementa la configuración de Endpoints

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

Para implementar la configuración de Endpoints:

  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 el 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-01-r0] 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 Cloud Console.

    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 Cargo
servicemanagement.googleapis.com API de Administración de servicios
servicecontrol.googleapis.com API de Control de servicios
endpoints.googleapis.com Google Cloud Endpoints

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 necesarios estén habilitados:

gcloud services list
    

Si no ves los servicios obligatorios, habilítalos:

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

También habilita tu servicio de Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

  • Después de implementar la configuración de Endpoints, ve a la página Endpoints en Cloud Console. La lista de ENDPOINTS_SERVICE_NAME posibles 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 gRPC Endpoints.

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

Compila una nueva imagen de ESPv2 Beta

Compila la configuración del servicio de Endpoints en una nueva imagen de Docker de ESPv2 Beta y vuelve a implementar el servicio ESPv2 Beta de Cloud Run con la imagen. Luego, otórgale a ESPv2 Beta el permiso de Cloud IAM para invocar tus funciones.

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

  1. Descarga esta secuencia de comandos a tu máquina local donde está instalado el SDK de gcloud y ejecútalo como:

        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 Cloud Run creó cuando implementaste ESPv2 Beta en Implementación de ESPv2 Beta. 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-01-r0 -p ESP_PROJECT_ID

    La secuencia de comandos usa el comando de gcloud para descargar la configuración del servicio, compilarla en una imagen ESPv2 Beta nueva y subir la imagen nueva al registro de contenedores del proyecto ubicado aquí:

        gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

    Por ejemplo:

        gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01-r0"
  2. Vuelve a implementar el servicio ESPv2 Beta de Cloud Run con la imagen nueva. Reemplaza CLOUD_RUN_SERVICE_NAME por el mismo nombre de servicio de Cloud Run que usaste cuando lo implementaste originalmente en Implementa ESPv2 Beta:

        gcloud run deploy CLOUD_RUN_SERVICE_NAME \
          --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
          --allow-unauthenticated \
          --platform managed \
          --project=ESP_PROJECT_ID
  3. Si quieres configurar Endpoints para usar opciones adicionales de inicio de ESPv2 Beta, 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: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 una lista de opciones disponibles y también información sobre cómo especificar varias opciones, consulta Marcas del proxy de servicio extensible V2 Beta.

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

        gcloud functions add-iam-policy-binding FUNCTION_NAME \
           --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
           --role "roles/cloudfunctions.invoker" \
           --project FUNCTIONS_PROJECT_ID

Para obtener más información, consulta la página sobre cómo administrar el acceso mediante Cloud 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}/hello"

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/hello").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/hello
        

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 > Servicios de Cloud Console.

    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 Visor de registros.

    Ver los registros de solicitud de Endpoints

Crea un portal de desarrolladores para la API

Puedes usar el Portal de Cloud Endpoints para crear un portal de desarrolladores, un sitio web en el que puedes interactuar con la API de muestra. Si deseas obtener más información, consulta la 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 guía de inicio rápido.

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

Qué sigue