Comenzar a usar Endpoints en Compute Engine con Docker

Este instructivo te muestra cómo configurar e implementar una API de muestra y el Proxy de servicio extensible (ESP) en contenedores de Docker previamente compilados en Google Compute Engine. La API de REST del código de muestra se describe mediante la Especificación de OpenAPI. El instructivo también te 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 Arquitectura de Endpoints.

Lista de tareas

Utiliza 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 Cloud Platform. Consulta Antes de comenzar.
  2. Crea una instancia de VM de Compute Engine. Consulta Crear una instancia de Compute Engine.
  3. Descarga el código de muestra. Consulta Obtener el código de muestra.
  4. Configura el archivo openapi.yaml, que se usa para configurar Endpoints. Consulta Configurar Endpoints.
  5. Implementa la configuración de Endpoints para crear un servicio de Cloud Endpoints. Consulta Implementar la configuración de Endpoints.
  6. Implementa la API y el ESP en la VM de Compute Engine. Consulta Implementar el backend de la API.
  7. Envía una solicitud a la API mediante la dirección IP. Consulta Enviar una solicitud mediante la dirección IP.
  8. Configura un registro DNS para la API de muestra. Consulta Configurar DNS para Endpoints.
  9. Envía una solicitud a la API con el nombre de dominio. Consulta Enviar una solicitud mediante el FQDN.
  10. Realiza un seguimiento de la actividad de la API. Consulta Realizar un seguimiento de la actividad de la API.
  11. Evita que se apliquen cargos a tu cuenta de Google Cloud Platform. Consulta Limpiar.

Antes de comenzar

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Recuerda el ID del proyecto porque lo necesitarás más adelante.
  5. Necesitas una aplicación para enviar solicitudes a la API de muestra.

    • Usuarios de Linux y Mac: este instructivo proporciona un ejemplo del uso de curl, que suele venir instalado en el sistema operativo. Si no tienes curl, puedes descargarlo de la página Actualizaciones y descargas de curl.
    • Usuarios de Windows: este instructivo proporciona un ejemplo del uso de Invoke-WebRequest, que es compatible con PowerShell 3.0 y versiones posteriores.
  6. Descargar el SDK de Google Cloud.
  7. Actualiza el SDK de Cloud y luego instala los componentes de Endpoints.
    gcloud components update
  8. Asegúrate de que el SDK de Cloud (gcloud) tenga autorización para acceder a tus datos y servicios en Google Cloud Platform:
    gcloud auth login
    Se abrirá una nueva pestaña del navegador y se te solicitará que elijas una cuenta.
  9. Configura el proyecto predeterminado como el ID de tu proyecto.
    gcloud config set project [YOUR_PROJECT_ID]

    Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto. No incluyas los corchetes. Si tienes otros proyectos de Cloud Platform y deseas usar gcloud para administrarlos, consulta Administrar configuraciones del SDK de Cloud.

Crear una instancia de Compute Engine

    Sigue estos pasos para crear una instancia de Compute Engine:

  1. En GCP Console, ve a la página VM Instances.

    Ir a la página Instancias de VM

  2. Haz clic en Crear instancia.
  3. En la sección Firewall, selecciona Permitir el tráfico HTTP y Permitir el tráfico HTTPS.
  4. Haz clic en Crear para crear la instancia.
  5. Captura de pantalla de la ventana de creación de la instancia de VM con las opciones requeridas configuradas

    La instancia tardará unos momentos en iniciarse. Cuando esté lista, aparecerá en la página de Instancias de VM con un ícono de estado verde.

  6. Asegúrate de que puedes conectarte a la instancia de VM.
    1. En la lista de instancias de máquinas virtuales, haz clic en el botón SSH de la fila de la instancia a la que quieres conectarte.
    2. Ahora puedes usar la terminal para ejecutar comandos de Linux en la instancia de Debian.
    3. Ingresa exit para desconectarte de la instancia.
  7. 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 muestra

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

Java

Para clonar o descargar la API de muestra:

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

  2. 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:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera:
    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:

  1. Asegúrate de que tu variable del entorno de GOPATH esté configurada.
  2. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera:
    go get -u -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:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera:
    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:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera:
    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:

  1. Clona el repositorio de la aplicación de muestra en tu máquina local de la siguiente manera:
    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

Configurar Endpoints

El código de muestra incluye el archivo de configuración de OpenAPI openapi.yaml, el cual está basado en la Especificación de OpenAPI v2.0. Debes configurar e implementar openapi.yaml en tu máquina local.

Para configurar Endpoints, haz lo siguiente:

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

    Ten en cuenta lo siguiente:

    • En la muestra de configuración, se muestran las líneas cercanas al campo host, el cual debes modificar. Para implementar openapi.yaml en Cloud Endpoints, se necesita el documento de OpenAPI completo.
    • El ejemplo openapi.yaml contiene una sección para configurar la autenticación que no se necesita durante este instructivo. No es necesario que configures 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.yaml se encuentra en la muestra de introducción en el repositorio correspondiente a cada lenguaje en GitHub.
  2. En el campo host, reemplaza el texto por el nombre del servicio de Cloud Endpoints, el cual debería tener el siguiente formato:
    host: "echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog"
    

    Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto. No incluyas los corchetes. 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 de Endpoints. No es el nombre de dominio completo (FQDN) que usas para enviar solicitudes a la API.

Para obtener más información acerca de los campos en el documento de OpenAPI que requiere Cloud Endpoints, consulta Configurar Endpoints.

Después de completar todos los pasos de configuración siguientes de modo que puedas enviar solicitudes a la API de muestra mediante una dirección IP con éxito, consulta Configurar DNS para Endpoints si quieres obtener información sobre cómo configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para que sea el FQDN.

Implementar la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando utiliza Infraestructura de servicios, la plataforma de servicios básica de Google, que Cloud Endpoints y otros servicios usan para crear y administrar las API y los servicios.

Para implementar la configuración de Endpoints, haz lo siguiente:

  1. Ve al directorio endpoints/getting-started.

  2. Invoca el comando siguiente:

    gcloud endpoints services deploy openapi.yaml
    

La primera vez que realizas la implementación, se crea un servicio de Cloud Endpoints nuevo con el nombre que especificaste en el campo host del archivo openapi.yaml. El servicio se configura según la configuración en el archivo openapi.yaml. Cuando realizas cambios en openapi.yaml, debes volver a implementar el archivo para actualizar el servicio de Cloud Endpoints.

Mientras se configura el servicio, verás una gran cantidad de información en la terminal. Puedes ignorar sin riesgo las advertencias que avisan que las rutas de openapi.yaml no requieren una clave de API. Cuando el proceso finalice con éxito, verás una línea como la siguiente que muestra el ID de configuración del servicio y el nombre del servicio:

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, que consta de una marca de fecha seguida de un número de revisión. Si vuelves a implementar openapi.yaml en el mismo día, el número de revisión aumenta en el ID de configuración del servicio.

Si recibes un mensaje de error, consulta Solucionar problemas en la implementación de la configuración de Endpoints.

Consulta Implementar la configuración de Endpoints para obtener información adicional.

Implementar el backend de la API

Hasta ahora, implementaste el documento de OpenAPI en Service Management, pero aún no has implementado el código que entregará el backend de la API. Esta sección te guía en la configuración de Docker en la instancia de VM, y en la ejecución del código del backend de la API y el Proxy de servicio extensible en un contenedor de Docker.

Instalar Docker en la instancia de VM

Para instalar Docker en la instancia de VM, haz lo siguiente:

  1. Configura la zona para tu proyecto invocando el siguiente comando:
    gcloud config set compute/zone [YOUR_INSTANCE_ZONE]
    

    Reemplaza [YOUR_INSTANCE_ZONE] por la zona donde se ejecuta tu instancia. No incluyas los corchetes.

  2. Conéctate a tu instancia usando el siguiente comando:
    gcloud compute ssh [INSTANCE_NAME]
    

    Reemplaza [INSTANCE_NAME] con el nombre de tu instancia de VM. No incluyas los corchetes.

  3. Consulta la documentación de Docker para configurar el repositorio de Docker. Asegúrate de seguir los pasos que correspondan con la versión y la arquitectura de tu instancia de VM:
    • Jessie o posterior
    • x86_64 / amd64

Ejecutar la API y el Proxy de servicio extensible en un contenedor de Docker

El Proxy de servicio extensible es un proxy basado en nginx-based que se posiciona al frente de tu código de backend. Procesa el tráfico entrante para proporcionar autenticación, administración de claves de API, registro y otras funciones de la Administración de API de Endpoints.

Para instalar y ejecutar la API de muestra y el Proxy de servicio extensible en un contenedor de Docker:

  1. Crea tu propia red de contenedores llamada esp_net:
    sudo docker network create --driver bridge esp_net
    
  2. Ejecuta el servidor Echo de muestra que entrega la API de muestra:
    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
    
    Go
    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 de Docker del Proxy de servicio extensible público empaquetado previamente. En las opciones de inicio del ESP, reemplaza [SERVICE_NAME] con el nombre de tu servicio. Se trata del mismo nombre que configuraste en el campo host de tu documento de OpenAPI.
    sudo docker run \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --rollout_strategy=managed \
        --backend=echo:8080
    

    La opción --rollout_strategy=managed configura el ESP para que utilice la última configuración de servicio implementada. Cuando especificas esta opción, un minuto después de implementar una configuración de servicio nueva, el ESP detecta el cambio y comienza a aplicarlo automáticamente. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo utilice el ESP. Para obtener información acerca de las otras opciones del ESP usadas aquí, consulta Opciones de inicio del ESP.

Si recibes un mensaje de error, consulta Solucionar problemas de Cloud Endpoints en Compute Engine.

Consulta Implementar el backend de la API para obtener información adicional.

Enviar una solicitud mediante la dirección IP

Una vez que la API de muestra y el Proxy de servicio extensible estén en ejecución en la instancia de Compute Engine, puedes enviar solicitudes a la API desde tu máquina local.

Crear una clave de API y configurar una variable de entorno

El código de muestra requiere una clave de API. Para simplificar la solicitud, configura una variable de entorno para la clave de API.

  1. En el mismo proyecto de GCP 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 proyecto de GCP, consulta Habilitar una API en tu proyecto de Cloud.

    Obtener una clave de API

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

Enviar la solicitud

Linux o Mac OS

Usa curl para enviar una solicitud HTTP mediante la variable del entorno ENDPOINTS_KEY que configuraste anteriormente. Reemplaza [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 el curl anterior:

  • 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

Usa Invoke-WebRequest para enviar una solicitud HTTP mediante la variable del entorno ENDPOINTS_KEY que configuraste anteriormente. Reemplaza [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 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 utilizadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

Aplicación de terceros

Para enviar la solicitud, puedes usar una aplicación de terceros, como la extensión Postman del navegador Chrome (producto que ofrece www.getpostman.com).

  • 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 clave de API real en lugar de la variable de entorno. Por ejemplo:
    http://192.0.2.0:80/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 Solucionar problemas de errores en las respuestas.

Acabas de implementar y probar una API en Cloud Endpoints.

Configurar DNS para Endpoints

Debido a que el nombre de servicio de Cloud Endpoints para la API se encuentra en el dominio .endpoints.PROJECT-ID.cloud.goog, puedes usarlo como el nombre de dominio completo (FQDN) mediante un cambio pequeño de configuración en tu archivo openapi.yaml. De este modo, puedes enviar solicitudes a la API de muestra si usas echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog en lugar de la dirección IP.

Para configurar DNS de Endpoints:

  1. Abre tu archivo de configuración de OpenAPI, openapi.yaml, y agrega la propiedad x-google-endpoints en el nivel superior del archivo (sin sangría ni anidado), tal 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, reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto. No incluyas los corchetes.
  3. En la propiedad target, reemplaza [IP_ADDRESS] por la dirección IP que usaste cuando enviaste una solicitud a la API de muestra. No incluyas los corchetes.
  4. Implementa el archivo de configuración de OpenAPI actualizado en Service Management mediante el siguiente comando:
        gcloud endpoints services deploy openapi.yaml
    

Por ejemplo, supongamos que openapi.yaml está configurado de la siguiente manera:

    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 openapi.yaml mediante el comando de gcloud anterior, Service Management crea un registro A DNS, echo-api.endpoints.my-project-id.cloud.goog, que se resuelve como la dirección IP objetivo, 192.0.2.1. Ten en cuenta que la configuración nueva de DNS puede tardar algunos minutos en propagarse.

Configurar SSL

Para obtener más detalles sobre cómo configurar DNS y SSL, consulta Habilitar SSL para Cloud Endpoints.

Enviar una solicitud mediante el FQDN

Ahora que ya has configurado el registro DNS para la API de muestra, envíale una solicitud con el FQDN (reemplaza [YOUR_PROJECT_ID] por el ID del proyecto) y la variable del entorno ENDPOINTS_KEY que configuraste antes:
  • 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

Realizar un seguimiento de la actividad de la API

Para realizar un seguimiento de la actividad de la API:

  1. Revisa los grafos de actividad de tu API en la página de Endpoints.
    Ver los grafos de actividad de Endpoints
    La solicitud puede tardar unos momentos en reflejarse en los grafos.

  2. Revisa 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 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.

Limpiar

Para evitar generar cargos en tu cuenta de GCP por los recursos que usaste en esta guía de inicio rápido, haz lo siguiente:

  1. Borra la API:
    gcloud endpoints services delete [SERVICE_NAME]
    

    Reemplaza [SERVICE_NAME] con el nombre de tu servicio.

  2. En GCP Console, dirígete a la página Instancias de VM.

    Ir a la página Instancias de VM

  3. Haz clic en la casilla de verificación junto ala instancia que deseas borrar.
  4. Haz clic en el botón Borrar en la parte superior de la página para borrar la instancia.

Pasos siguientes

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