Comienza a usar Cloud Endpoints para el entorno flexible de App Engine con el ESP

Este instructivo te muestra cómo configurar y, luego, implementar una API de muestra y el Proxy de servicio extensible (ESP) en una instancia del entorno flexible de App Engine. La API de REST del código de muestra se describe mediante la Especificación de OpenAPI. En el instructivo también se muestra cómo crear una clave de API y usarla en solicitudes a la API.

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

Objetivos

Usa la siguiente lista de tareas de alto nivel a medida que avanzas en el instructivo. Todas las tareas son necesarias para enviar solicitudes a la API con éxito.

  1. Configura un proyecto de Google Cloud, instala el software requerido y crea una aplicación de App Engine. Consulta Antes de comenzar.
  2. Descarga el código de muestra. Consulta Cómo descargar el código de muestra.
  3. Configura el archivo openapi-appengine.yaml, que se usa para configurar Endpoints. Consulta Cómo configurar Endpoints.
  4. Implementa la configuración de Endpoints para crear un servicio de este sistema. Consulta Cómo configurar Endpoints.
  5. Implementa la API y el ESP en App Engine. Consulta Implementa el backend de la API.
  6. Envía una solicitud a la API. Consulta Enviar una solicitud a la API.
  7. Realiza un seguimiento de la actividad de la API. Consulta Cómo realizar un seguimiento de la actividad de la API.
  8. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Limpiar.

Costos

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

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

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Toma nota del ID del proyecto, ya que será necesario más tarde.

  7. Necesitas una aplicación para enviar solicitudes a la API de muestra.

    • Usuarios de Linux y macOS: En este instructivo se proporciona un ejemplo del uso de curl, que suele venir preinstalado en el sistema operativo. Si no tienen curl, pueden descargarlo de la curl página de actualizaciones y descargas.
    • Usuarios de Windows: En este instructivo se proporciona un ejemplo del uso de Invoke-WebRequest, que es compatible con PowerShell 3.0 y versiones posteriores.
  8. Descarga Google Cloud CLI.
  9. Actualiza la CLI de gcloud y, luego, instala los componentes de Endpoints. 
    gcloud components update
  10. Asegúrate de que Google Cloud CLI (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud: 
    gcloud auth login
     En la nueva pestaña del navegador que se abre, selecciona una cuenta.
  11. Configura el proyecto predeterminado con el ID de tu proyecto.
    gcloud config set project YOUR_PROJECT_ID

    Reemplaza YOUR_PROJECT_ID con el ID del proyecto. Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta Administrar gcloud CLI de gcloud

  12. Selecciona la región en la que deseas crear tu aplicación de App Engine. Ejecuta el siguiente comando para obtener una lista de regiones: 
    gcloud app regions list
  13. Crea una aplicación de App Engine. Reemplaza YOUR_PROJECT_ID por tu ID del proyecto de Google Cloud y YOUR_REGION por la región en la que deseas crear la aplicación de App Engine. 
      gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION

Obtén el código de muestra

Java

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. El código de muestra utiliza Maven. Si no tienes Maven 3.3.9 o una versión superior, descárgalo y, luego, instálalo.
  2. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera: 
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Como alternativa, descarga la muestra como un archivo zip y extráelo.

  3. Ve al directorio que contiene el código de muestra:
    cd java-docs-samples/endpoints/getting-started
Python

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local: 
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Como alternativa, descarga la muestra como un archivo zip y extráelo.

  2. Ve al directorio que contiene el código de muestra:
    cd python-docs-samples/endpoints/getting-started
Go

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. Asegúrate de que esté configurada tu variable de entorno de GOPATH.
  2. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente forma:
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Ve al directorio que contiene el código de muestra:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local: 
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Como alternativa, descarga la muestra como un archivo zip y extráelo.

  2. Ve al directorio que contiene el código de muestra:
    cd php-docs-samples/endpoints/getting-started
Ruby

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local: 
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Como alternativa, descarga la muestra como un archivo zip y extráelo.

  2. Ve al directorio que contiene el código de muestra:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

Para clonar o descargar la API de muestra, haz lo siguiente:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local: 
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Como alternativa, descarga la muestra como un archivo zip y extráelo.

  2. Ve al directorio que contiene el código de muestra:
    cd nodejs-docs-samples/endpoints/getting-started

Configura Endpoints

El código de muestra incluye el archivo de configuración de OpenAPI, openapi-appengine.yaml, que se basa en Especificación de OpenAPI v2.0.

Para configurar Endpoints, sigue estos pasos:
  1. En el directorio del código de muestra, abre el archivo de configuración openapi-appengine.yaml.

    Java
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Python
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Go
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    PHP
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Ruby
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    NodeJS
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"

    Ten en cuenta lo siguiente:

    • En la configuración de ejemplo, se muestran las líneas cercanas al campo host, que debes modificar. Para implementar openapi-appengine.yaml en Endpoints, se necesita el documento de OpenAPI completo.
    • El ejemplo openapi-appengine.yaml contiene una sección para configurar una autenticación que no se necesita para este instructivo. No necesitas configurar las líneas con YOUR-SERVICE-ACCOUNT-EMAIL y YOUR-CLIENT-ID.
    • OpenAPI es una especificación independiente del lenguaje. Para mayor comodidad, el mismo archivo openapi-appengine.yaml se encuentra en la muestra getting-started en el repositorio de GitHub correspondiente a cada lenguaje.

  2. En la línea con el campo host, reemplaza YOUR-PROJECT-ID por el ID de tu proyecto de Google Cloud. Por ejemplo: 
    host: "example-project-12345.appspot.com"

Endpoints usa el texto configurado en el campo host como nombre del servicio. Cuando implementas la API en el backend de App Engine, se crea una entrada DNS con un nombre con el formato YOUR-PROJECT-ID.appspot.com de forma automática.

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

Cómo implementar 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 que estés en el directorio endpoints/getting-started.
  2. Sube la configuración y crea un servicio administrado.
    gcloud endpoints services deploy openapi-appengine.yaml

Entonces, el comando gcloud llama a la API de Administración de servicios para crear un servicio administrado con el nombre que especificaste en el campo host del archivo openapi-appengine.yaml. La Administración de servicios configura el servicio de acuerdo con la configuración del archivo openapi-appengine.yaml. Cuando realizas cambios en openapi-appengine.yaml, debes volver a implementar el archivo para actualizar el servicio de Endpoints.

Mientras se crea y configura el servicio, la Administración de servicios exporta la información a la terminal. Puedes ignorar sin riesgo las advertencias que indican que las rutas de acceso en el archivo openapi-appengine.yaml no requieren una clave de API. Cuando termina de configurarse el servicio, la Administración de servicios muestra un mensaje con el ID de configuración del servicio y el nombre del servicio, de manera similar a este ejemplo:

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y example-project-12345.appspot.com es el servicio de Endpoints. El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si implementas el archivo openapi-appengine.yaml otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio. Puedes ver la configuración del servicio de Endpoints en Endpoints > Servicios en 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 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 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
gcloud services enable endpoints.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.

Cómo implementar el backend de la API

Hasta ahora, implementaste la configuración de OpenAPI en Service Management, pero aún no has implementado el código que entregará el backend de la API. En esta sección se explica cómo implementar el ESP y la API de muestra en App Engine.

Para implementar el backend de la API, haz lo siguiente:

  1. Agrega tu nombre de servicio al archivo app.yaml de la siguiente manera:

    Java

    Abre el archivo endpoints/getting-started/src/main/appengine/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Python

    Abre el archivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Go

    Abre el archivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    PHP

    Abre el archivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  #
  #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
  #
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Ruby

    Abre el archivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    NodeJS

    Abre el archivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Reemplaza ENDPOINTS-SERVICE-NAME por el nombre de tu servicio de Endpoints. Este es el mismo nombre que configuraste en el campo host de tu documento de OpenAPI. Por ejemplo: 

    endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

    La opción rollout_strategy: managed configura el ESP para que use la última configuración del servicio implementada. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP.

  2. Guarda el archivo app.yaml.

    3. Debido a que la sección endpoints_api_service se incluye en el archivo app.yaml, el comando gcloud app deploy implementa y configura el ESP en un contenedor separado en tu entorno flexible de App Engine. Todo el tráfico de solicitudes se enruta a través del ESP, y procesa solicitudes y respuestas hacia el contenedor, y desde este, el cual ejecuta el código de servidor de backend.

  3. Asegúrate de que estés en el directorio endpoints/getting-started. Aquí es donde se ubica tu archivo de configuración openapi-appengine.yaml.
  4. Ejecuta el siguiente comando para implementar la API y el ESP de muestra en App Engine:

    5. Java

    Implementar con Maven:

    mvn appengine:stage
gcloud app deploy target/appengine-staging
    Python
    gcloud app deploy
    Go
    gcloud app deploy
    PHP
    gcloud app deploy
    Ruby
    gcloud app deploy
    NodeJS
    gcloud app deploy

    Con el comando gcloud app deploy, se crea un registro DNS en el formato YOUR_PROJECT_ID, que se usa cuando envías solicitudes a la API. Te recomendamos que esperes unos minutos antes de enviar solicitudes a tu API mientras App Engine se inicializa del todo.

Si recibes un mensaje de error, consulta Solucionar problemas en la implementación de App Engine Flexible.

Para obtener más información, consulta Cómo implementar el backend de la API.

Cómo enviar solicitudes a la API

Ahora que el servicio se ejecuta en App Engine, puedes enviarle solicitudes.

Crear una clave de API y configurar una variable del entorno

El código de muestra requiere una clave de API. La solicitud es más simple si configuras una variable de entorno para la clave de API.

  1. En el mismo proyecto de Google Cloud que usaste para tu API, crea una clave de API en la página de credenciales de la API. Si quieres crear una clave de API en un proyecto de Google Cloud diferente, consulta la sección sobre cómo habilitar una API en tu proyecto de Google Cloud.

    Ir a la página Credenciales

  2. Haz clic en Crear credenciales y selecciona Clave de API.
  3. Copia la clave al portapapeles.
  4. Haz clic en Cerrar.
  5. En tu computadora local, pega la clave de API para asignarla a una variable de entorno:
    • En Linux o macOS: export ENDPOINTS_KEY=AIza...
    • En Windows PowerShell, haz lo siguiente: $Env:ENDPOINTS_KEY="AIza..."

Envía la solicitud

Linux o macOS

  1. Crea una variable de entorno para la URL de tu proyecto de App Engine. Reemplaza YOUR_PROJECT_ID por tu ID del proyecto de Google Cloud de la siguiente manera:

    export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com

  2. Envía una solicitud HTTP con las siguientes variables de entorno ENDPOINTS_HOST y ENDPOINTS_KEY que configuraste anteriormente:

    curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

En el curl anterior, sucede lo siguiente:

  • La opción --data especifica los datos que se publicarán en la API.
  • La opción --header especifica que los datos están en formato JSON.

PowerShell

  1. Crea una variable de entorno para la URL de tu proyecto de App Engine. Reemplaza YOUR_PROJECT_ID por tu ID del proyecto de Google Cloud de la siguiente manera:

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. Envía una solicitud HTTP con las siguientes variables de entorno ENDPOINTS_HOST y ENDPOINTS_KEY que configuraste anteriormente:

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "$Env:ENDPOINTS_HOST/echo?key=$Env:ENDPOINTS_KEY").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 la solicitud:

  • Selecciona POST como el verbo HTTP.
  • Para el encabezado, selecciona la clave content-type y el valor application/json.
  • Para el cuerpo, ingresa lo siguiente:
    {"message":"hello world"}
  • En la URL, usa la dirección appspot.com y la clave de API reales en lugar de las variables de entorno. Por ejemplo:
    https://example-project-12345.appspot.com/echo?key=AIza...

La API repite el mensaje que le enviaste y responde lo siguiente:

{
  "message": "hello world"
}

Si no obtuviste una respuesta correcta, consulta Soluciona errores de respuesta.

¡Acabas de implementar y probar una API en Endpoints!

Realiza un seguimiento de la actividad de la API

  1. Revisa los grafos de actividad de tu API en la página de Endpoints.

    Ir a la página Servicios de Endpoints

    Es posible que la solicitud tarde unos minutos en reflejarse en los grafos.

  2. Revisa los registros de solicitud de tu API en la página Explorador de registros.

    Ir a la página Explorador de registros

Crea un portal de desarrolladores para la API

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

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

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?