Empezar a usar Cloud Endpoints para Compute Engine con ESPv2

OpenAPI   |  gRPC

En este tutorial se explica cómo configurar y desplegar una API de ejemplo y Extensible Service Proxy V2 (ESPv2) que se ejecuta en contenedores Docker prediseñados en Compute Engine.

La API REST del código de ejemplo se describe mediante la especificación de OpenAPI. En el tutorial también se explica cómo crear una clave de API y usarla en las solicitudes a la API.

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

Crear una instancia de Compute Engine

Para crear una instancia de Compute Engine, sigue estos pasos:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. En la sección Cortafuegos, selecciona Permitir el tráfico HTTP y Permitir el tráfico HTTPS.
3. Para crear la VM, haz clic en Crear.



Espera un poco para que la instancia se inicie. Cuando esté lista, aparecerá en la página Instancias de VM con un icono de estado verde.

4. Asegúrate de que puedes conectarte a tu instancia de VM.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Ahora puedes usar el terminal para ejecutar comandos de Linux en tu instancia de Debian.
   3. Escribe exit para desconectarte de la instancia.
5. Anota el nombre de la instancia, la zona y la dirección IP externa, ya que los necesitarás más adelante.

Descargar el código de ejemplo

Descarga el código de ejemplo en tu máquina local.

Java

Para clonar o descargar la API de ejemplo, sigue estos pasos:

1. Clona el repositorio de aplicaciones de muestra en la máquina local:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples

   También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.

2. Accede al directorio que contiene el código de muestra:

   cd java-docs-samples/endpoints/getting-started

Python

Para clonar o descargar la API de ejemplo, sigue estos pasos:

1. Clona el repositorio de aplicaciones de muestra en la máquina local:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples

   También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.

2. Accede al directorio que contiene el código de muestra:

   cd python-docs-samples/endpoints/getting-started

Ir

Para clonar o descargar la API de ejemplo, sigue estos pasos:

1. Asegúrate de que la variable de entorno GOPATH esté definida.
2. Clona el repositorio de aplicaciones de muestra en la máquina local:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Accede 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 ejemplo, sigue estos pasos:

1. Clona el repositorio de aplicaciones de muestra en la máquina local:

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples

   También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.

2. Accede al directorio que contiene el código de muestra:

   cd php-docs-samples/endpoints/getting-started

Ruby

Para clonar o descargar la API de ejemplo, sigue estos pasos:

1. Clona el repositorio de aplicaciones de muestra en la máquina local:

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

   También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.

2. Accede al directorio que contiene el código de muestra:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

Para clonar o descargar la API de ejemplo, sigue estos pasos:

1. Clona el repositorio de aplicaciones de muestra en la máquina local:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

   También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.

2. Accede al directorio que contiene el código de muestra:

   cd nodejs-docs-samples/endpoints/getting-started

Configurar Endpoints

El código de ejemplo incluye el archivo de configuración de OpenAPI, openapi.yaml, que se basa en la especificación de OpenAPI v2.0. Configuras e implementas openapi.yaml en tu máquina local. Para configurar Endpoints, haz lo siguiente:

1. En el directorio de código de ejemplo, abre el archivo de configuración openapi.yaml.
   Java

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Python

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ir

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   PHP

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ruby

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   NodeJS

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ten en cuenta lo siguiente:

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

2. En el campo host, sustituye el texto por el nombre del servicio Endpoints, que debe tener el siguiente formato:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

   Sustituye YOUR_PROJECT_ID por el ID de tu proyecto. Google Cloud Por ejemplo:

   host: "echo-api.endpoints.example-project-12345.cloud.goog"

Ten en cuenta que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog es el nombre del servicio Endpoints. No es el nombre de dominio completo (FQDN) que usas para enviar solicitudes a la API.

Para obtener información sobre los campos del documento OpenAPI que requiere Endpoints, consulta Configurar Endpoints. Una vez que hayas completado todos los pasos de configuración que se indican a continuación para poder enviar solicitudes a la API de ejemplo mediante una dirección IP, consulta Configurar el DNS de los endpoints para obtener información sobre cómo configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para que sea el FQDN.

Desplegar la configuración de Endpoints

Para desplegar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Gestión de servicios para crear un servicio gestionado.

Para desplegar la configuración de Endpoints, sigue estos pasos:

1. Asegúrate de que estás en el directorio endpoints/getting-started.
2. Sube la configuración y crea un servicio gestionado:

   gcloud endpoints services deploy openapi.yaml
   

El comando gcloud llama a la API Service Management para crear un servicio gestionado con el nombre que has especificado en el campo host del archivo openapi.yaml. Gestión de servicios configura el servicio según los ajustes del archivo openapi.yaml. Cuando hagas cambios en openapi.yaml, debes volver a implementar el archivo para actualizar el servicio Endpoints.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Puedes ignorar las advertencias sobre las rutas del archivo openapi.yaml que no requieren una clave de API. Cuando termine de configurar el servicio, Service Management mostrará un mensaje con el ID de configuración del servicio y el nombre del servicio, similar al siguiente:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el servicio Endpoints. El ID de configuración del servicio consta de una marca de fecha seguida de un número de revisión. Si vuelves a implementar el archivo openapi.yaml el mismo día, el número de revisión se incrementará en el ID de configuración del servicio. Puedes ver la configuración del servicio Endpoints en la página Endpoints > Services (Servicios) de la consola de Google Cloud .

Si aparece un mensaje de error, consulta Solucionar problemas de despliegue de la configuración de Endpoints.

Comprobando los servicios necesarios

Como mínimo, Endpoints y ESP requieren que los siguientes servicios de Google estén habilitados:

Nombre	Título
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control

En la mayoría de los casos, el comando gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa correctamente, pero no habilita los servicios necesarios en las siguientes circunstancias:

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

• Has desplegado la configuración de Endpoints en unGoogle Cloud proyecto en el que estos servicios se han inhabilitado explícitamente.

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

gcloud services list

Si no ves los servicios necesarios, habilítalos:

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

También debes habilitar el servicio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar el ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

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

• En OpenAPI, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo host de tu especificación de OpenAPI. En gRPC, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo name de tu configuración de endpoints de gRPC.

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

Desplegar el backend de la API

Hasta ahora, has implementado el documento OpenAPI en Service Management, pero aún no has implementado el código que sirve de backend de la API. En esta sección se explica cómo configurar Docker en tu instancia de VM y ejecutar el código backend de la API y ESPv2 en un contenedor Docker.

Comprobando los permisos necesarios

Nota:

No es necesario realizar este paso si la instancia de Compute Engine se crea con la cuenta de servicio predeterminada de Compute Engine y se le han concedido todos los permisos necesarios.

• En la consola de Google Cloud , ve a la página de instancias de Compute Engine.

  Ir a la página de Compute Engine

• Selecciona tu instancia en la lista.
• Puedes ver la cuenta de servicio asociada y los permisos que tiene.

• Concede 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 los roles y los permisos?

Instalar Docker en la instancia de máquina virtual

Para instalar Docker en la instancia de VM, sigue estos pasos:

1. Define la zona de tu proyecto ejecutando el siguiente comando:

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Sustituye YOUR_INSTANCE_ZONE por la zona en la que se ejecuta tu instancia.

2. Conéctate a tu instancia con el siguiente comando:

   gcloud compute ssh INSTANCE_NAME
   

   Sustituye INSTANCE_NAME por el nombre de tu instancia de VM.

3. Consulta la documentación de Docker para configurar el repositorio de Docker. Sigue los pasos que correspondan a la versión y la arquitectura de tu instancia de VM:
   • Jessie o una versión posterior
   • x86_64 / amd64

Ejecutar la API y ESPv2 en un contenedor Docker

ESPv2 es un proxy basado en Envoy que se encuentra delante del código de backend. Procesa el tráfico entrante para proporcionar autenticación, gestión de claves de API, registro y otras funciones de gestión de APIs de Endpoints. Para instalar y ejecutar la API de muestra y ESPv2 en un contenedor Docker, sigue estos pasos:

1. Crea tu propia red de contenedores llamada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Ejecuta el servidor Echo de ejemplo que sirve a la API de ejemplo:
   Java

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
   

   Python

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
   

   Ir

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
   

   PHP

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
   

   Ruby

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
   

   NodeJS

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
   

3. Ejecuta el contenedor Docker público de ESPv2 preempaquetado. En las opciones de inicio del ESPv2, sustituye SERVICE_NAME por el nombre de tu servicio. Es el mismo nombre que has configurado en el campo host de tu documento OpenAPI.

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:2 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --listener_port=9000 \
       --backend=http://echo:8080
   

   La opción --rollout_strategy=managed configura ESPv2 para que use la última configuración de servicio implementada. Si especificas esta opción, un minuto después de desplegar una nueva configuración de servicio, ESPv2 detectará el cambio y empezará a usarlo automáticamente. Te recomendamos que especifiques esta opción en lugar de proporcionar un ID de configuración específico para que lo use ESPv2. Para obtener información sobre las otras opciones de ESPv2 que se han usado anteriormente, consulta Opciones de inicio del ESPv2.

Si aparece un mensaje de error, consulta Solucionar problemas de Endpoints en Compute Engine. Consulta más información en el artículo sobre desplegar el backend de la API.

Enviar una solicitud mediante una dirección IP

Una vez que la API de ejemplo y ESPv2 se estén ejecutando en la instancia de Compute Engine, podrás enviar solicitudes a la API desde tu máquina local.

Crear una clave de API y definir una variable de entorno

El código de ejemplo requiere una clave de API. Para simplificar la solicitud, puedes definir una variable de entorno para la clave de API.

1. En el mismo Google Cloud proyecto 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 otro Google Cloud proyecto, consulta el artículo sobre cómo habilitar una API en tu Google Cloud proyecto.

   Ir a la página Credenciales

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

Enviar la solicitud

Linux o macOS

Usa curl para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_KEY que has definido anteriormente. Sustituye IP_ADDRESS por la dirección IP externa de tu instancia.

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

En los curl anteriores:

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

PowerShell

Usa Invoke-WebRequest para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_KEY que has definido anteriormente. Sustituye IP_ADDRESS por la dirección IP externa de tu instancia.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

En el ejemplo anterior, las dos primeras líneas terminan en una comilla inversa. Cuando pegues el ejemplo en PowerShell, asegúrate de que no haya ningún espacio después de las comillas inversas. Para obtener información sobre las opciones que se usan en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

Aplicación de terceros

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

• Selecciona POST como verbo HTTP.
• En el encabezado, selecciona la clave content-type y el valor application/json.
• En el cuerpo, introduce lo siguiente:
  {"message":"hello world"}
• En la URL, usa la clave de API real en lugar de la variable de entorno. Por ejemplo:
  http://192.0.2.0:80/echo?key=AIza...

La API devuelve el mensaje que envías y responde con lo siguiente:

{
  "message": "hello world"
}

Si no has recibido una respuesta correcta, consulta el artículo Solucionar problemas de errores de respuesta.

Acabas de desplegar y probar una API en Endpoints.

Nota: Si quieres decirnos qué te ha gustado de este tutorial, puedes enviarnos tus comentarios en la parte inferior de esta página. Tus comentarios nos ayudan a mejorar estos tutoriales.
Si has recibido un error, únete al google-cloud-endpoints grupo de Google e infórmanos de lo que ha ido mal. Este grupo recibe respuestas de otros usuarios de Endpoints y de ingenieros de Google, que monitorizan el grupo.

Configurar DNS para Endpoints

Como el nombre del servicio Endpoints de la API está en el dominio .endpoints.YOUR_PROJECT_ID.cloud.goog, puedes usarlo como nombre de dominio completo (FQDN) haciendo un pequeño cambio de configuración en el archivo openapi.yaml. De esta forma, puedes enviar solicitudes a la API de ejemplo mediante echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog en lugar de la dirección IP.

Para configurar el DNS de Endpoints, sigue estos pasos:

1. Abre el archivo de configuración de OpenAPI, openapi.yaml, y añade la propiedad x-google-endpoints en el nivel superior del archivo (sin sangría ni anidación), como se muestra en el siguiente fragmento:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"

2. En la propiedad name, sustituye YOUR_PROJECT_ID por el ID de tu proyecto.
3. En la propiedad target, sustituya IP_ADDRESS por la dirección IP que usó cuando envió una solicitud a la API de ejemplo.
4. Despliega el archivo de configuración de OpenAPI actualizado en Service Management:

   gcloud endpoints services deploy openapi.yaml
   

Por ejemplo, supongamos que el archivo openapi.yaml tiene la siguiente configuración:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Cuando implementas el archivo openapi.yaml con el comando gcloud anterior, Service Management crea un registro A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que se resuelve en la dirección IP de destino, 192.0.2.1. La nueva configuración de DNS puede tardar unos minutos en propagarse.

Configurar SSL

Para obtener más información sobre cómo configurar DNS y SSL, consulta Habilitar SSL para endpoints.

Enviar una solicitud mediante el FQDN

Ahora que has configurado el registro DNS de la API de ejemplo, envíale una solicitud mediante el FQDN (sustituye YOUR_PROJECT_ID por el ID de tu proyecto) y la variable de entorno ENDPOINTS_KEY que has definido anteriormente:

• En Linux o macOS:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• En Windows PowerShell:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

Monitorizar la actividad de la API

Para monitorizar la actividad de la API, siga estos pasos:

1. Consulta los gráficos de actividad de tu API en la página Endpoints > Services (Endpoints > Servicios).
   

   Ir a la página Servicios de Endpoints

   
   La solicitud puede tardar unos instantes en reflejarse en los gráficos.
2. Consulta los registros de solicitudes de tu API en la página Explorador de registros.
   

   Ir a la página Explorador de registros