Comenzar 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 (ESP) como una puerta de enlace de API. Para proporcionar administración de API para Cloud Functions, debes implementar el contenedor del ESP compilado antes en Cloud Run. Luego, protege tus funciones mediante IAM de Cloud Functions para que el ESP pueda invocarlas. Con esta configuración, el ESP 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, el ESP informa y recopila la telemetría. Puedes ver las métricas de tu función en la página Endpoints > Servicios de Google Cloud Platform Console.

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

Lista de tareas

Usa la siguiente lista de tareas mientras trabajas en el instructivo. Todas las tareas son necesarias para que Endpoints administre tus funciones.

  1. Crea un proyecto de Google Cloud Platform (GCP) y, si no has implementado tu propio Cloud Functions, implementa una función de muestra. Consulta Antes de comenzar.
  2. Implementa el contenedor del ESP en Cloud Run. Consulta Implementar el ESP.
  3. Crea un documento de OpenAPI que describa tu API y configure las rutas a Cloud Functions. Consulta Configurar Endpoints.
  4. Implementa el documento de OpenAPI para crear un servicio administrado. Consulta Implementar la configuración de Endpoints.
  5. Configura el ESP para que pueda encontrar la configuración de tu servicio y otorga al ESP el permiso de Cloud Identity and Access Management (Cloud IAM) para invocar tus funciones. Consulta Configurar el ESP.
  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 apliquen cargos a tu cuenta de GCP. Consulta Realizar una limpieza.

Antes de comenzar

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

  • Crea un nuevo proyecto de GCP para usarlo cuando implementes el contenedor del ESP en Cloud Run.

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

Para realizar la configuración, sigue estos pasos:

  1. En GCP Console, dirígete a la página Administrar recursos y crea un proyecto.

    Ir a la página Administrar 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 será necesario más tarde. En el resto de esta 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 propio Cloud Functions, sigue los pasos que aparecen en la guía de inicio rápido sobre cómo usar la herramienta de línea de comandos de gcloud para seleccionar o crear un proyecto de GCP y, luego, 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.

Implementar el ESP

Para implementar el contenedor del ESP 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 del navegador que se abre, elige una cuenta que tenga la función Editor o Propietario en el proyecto de GCP que creaste para implementar el ESP en Cloud Run.
  2. Configura la región. Por el momento, solo us-central1 es compatible con Cloud Run.
    gcloud config set run/region us-central1
  3. Implementa el ESP en Cloud Run. Reemplaza CLOUD_RUN_SERVICE_NAME por el nombre que deseas usar para el servicio.
    gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1" \
        --allow-unauthenticated \
        --project=ESP_PROJECT_ID
    

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

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

    En el ejemplo anterior, gateway es el nombre del servicio de Cloud Run.

  4. Anota el nombre de host en la URL. Especificas el nombre de host en el campo host del documento de OpenAPI.
  5. 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.

Configurar 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 para que el ESP tenga la información que necesita a fin de invocar una función. Si no estás familiarizado con 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/helloGET
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    
    Ten en cuenta que la sangría es importante en el formato yaml. Por ejemplo, el campo “host” debe estar al mismo nivel que “info”.
  3. En el campo address, en la sección x-google-backend, reemplaza REGION por la región de GCP en la que se encuentra tu función y FUNCTIONS_PROJECT_ID por tu ID del proyecto de GCP. (Puedes ejecutar gcloud functions describe para obtener la región).
  4. En el campo host, agrega el nombre de host en la URL activa que Cloud Run creó para el ESP. 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
    

    Endpoints usa el nombre que configuraste en el campo host como el nombre de tu servicio.

  5. Guarda tu documento de OpenAPI.

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

Implementar la configuración de Endpoints

Para implementar la configuración de Endpoints, debes usar 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 tu documento de OpenAPI.

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

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

    Este proceso 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, la Administración de servicios exporta la información a la terminal. Cuando se completa la implementación, se muestra un mensaje similar al siguiente:

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

En el ejemplo anterior, 2019-02-01-r0 es el ID de configuración del servicio y gateway-12345-uc.a.run.app es el nombre del servicio de Endpoints. El ID de configuración del 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, el número de revisión se incrementa 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 en GCP Console.

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

Verificar los servicios requeridos

Como mínimo, Endpoints y el ESP requieren los siguientes servicios:
Nombre Título
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 gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa de manera correcta, pero no habilita los servicios requeridos en las siguientes circunstancias:

  • Si usaste una aplicación de terceros, como Terraform, y no incluyes estos servicios.

  • Si implementaste la configuración de Endpoints en un proyecto de GCP existente en el que se inhabilitaron estos servicios de forma explícita.

Para confirmar que los servicios requeridos estén habilitados, haz lo siguiente:

gcloud services list

Si no ves los servicios requeridos en la lista, habilítalos:

gcloud services enable SERVICE_NAME

Reemplaza SERVICE_NAME por el nombre del servicio para habilitar.

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

Configurar el ESP

Configura el ESP para que pueda encontrar la configuración de tu servicio de Endpoints. Luego, concede al ESP el permiso de Cloud IAM para invocar tus funciones.

Para configurar el ESP, haz lo siguiente:

  1. Configura el nombre del servicio de Endpoints de modo que el ESP pueda localizar y cargar tu configuración de Endpoints. En el siguiente comando, haz lo siguiente:

    • Reemplaza YOUR_SERVICE_NAME por el nombre de tu servicio de Endpoints. Este es el nombre que especificaste en el campo host de tu documento de OpenAPI.
    • Reemplaza CLOUD_RUN_SERVICE_NAME por el nombre de tu servicio de Cloud Run.
    gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
       --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
       --project ESP_PROJECT_ID
    
  2. Si quieres configurar Endpoints para que use opciones de inicio de ESP adicionales, como habilitar CORS, puedes pasar los argumentos en la variable de entorno ESP_ARGS:

    gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
       --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
       --project ESP_PROJECT_ID
    

    Debes incluir el ENDPOINTS_SERVICE_NAME y la --rollout_strategy.

  3. Otorga permiso al ESP para invocar tus funciones. Ejecuta el siguiente comando para cada función. Para el siguiente comando, haz lo siguiente:

    • Reemplaza FUNCTION_NAME por el nombre de tu función.
    • Reemplaza ESP_PROJECT_NUMBER por el número del proyecto que creaste para el ESP. Una forma de encontrarlo es dirigirse a la consola de IAM y buscar la cuenta de servicio de procesamiento predeterminada, que es la cuenta de servicio que se usa en la marca member.
    gcloud beta 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 .

Enviar una solicitud a la API

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

  1. Crea una variable de entorno para tu 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.

Realizar un seguimiento de la actividad de la API

  1. Consulta los grafos de actividad de tu API en la página Endpoints > Servicio en GCP Console.

    Ver los grafos de actividad de Endpoints

    La solicitud puede tardar unos momentos en reflejarse en los grafos.

  2. Consulta los registros de solicitud de tu API en la página Visor de registros.

    Ver los registros de solicitud de Endpoints

Crear 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.

Realizar una limpieza

Sigue estos pasos para evitar que se generen cargos en tu cuenta de GCP por los recursos que usaste en esta guía de inicio rápido.

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.

Próximos pasos

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Cloud Endpoints con OpenAPI
Si necesitas ayuda, visita nuestra página de asistencia.