Comienza a usar Endpoints para Compute Engine con el ESP

---

OpenAPI   |  gRPC

En esta página, se muestra cómo implementar un ejemplo simple de servicio de gRPC con el proxy de servicio extensible (ESP) en un contenedor de Docker en Compute Engine.

En esta página, se usa la versión de Python del ejemplo bookstore-grpc. Consulta la sección Próximos pasos para ver muestras de gRPC en otros lenguajes.

Si quieres obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y Arquitectura de 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 y descarga el software necesario. Consulta Antes de comenzar.
2. Crea una instancia de VM de Compute Engine. Consulta Crear una instancia de Compute Engine.
3. Copia y configura archivos de la muestra bookstore-grpc. Consulta 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 la VM de Compute Engine. Consulta Implementa el backend de la API.
6. Envía una solicitud a la API. Consulta Cómo enviar una solicitud a la API.
7. 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:

• Compute Engine
• Extremos

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. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

2. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

4. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

5. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

6. Toma nota del ID del proyecto, ya que será necesario más tarde.
7. Instala y, luego, inicializa Google Cloud CLI.
8. Actualiza gcloud CLI y, luego, instala los componentes de Endpoints:

   gcloud components update

9. 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 pestaña del navegador nueva que se abre, selecciona una cuenta.
10. Configura el proyecto predeterminado con tu ID del 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 Administra gcloud CLI de gcloud.

11. Sigue los pasos en la Guía de inicio rápido de Python de gRPC para instalar gRPC y sus herramientas.

Crea una instancia de Compute Engine

Siga estos pasos para crear una instancia de Compute Engine:

1. En la consola de Google Cloud, ve a la página Crear una instancia.

   Ir a Crear una instancia

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



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

4. Asegúrate de que puedas conectarte a la instancia de VM.
   1. En la lista de instancias de máquinas virtuales, haz clic en SSH en la fila de la instancia a la que deseas 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.
5. Toma nota del nombre de la instancia, la zona y la dirección IP externa, ya que se necesitarán más adelante.

Configura Endpoints

Clona el repositorio de muestra bookstore-grpc de GitHub:

Para configurar Endpoints, haz lo siguiente:

1. Crea un archivo descriptor protobuf autónomo desde tu archivo de servicio .proto:
   1. Guarda una copia de bookstore.proto del repositorio de ejemplo. Este archivo define la API del servicio de Bookstore.
   2. Crea el directorio siguiente: mkdir generated_pb2
   3. Crea api_descriptor.pb, el archivo descriptor, mediante el compilador de búferes de protocolo protoc. Ejecuta el comando siguiente en el directorio donde guardaste bookstore.proto:

      python -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto
      

      En el comando anterior, --proto_path se configura como el directorio de trabajo actual. En tu entorno de compilación de gRPC, si usas un directorio diferente para los archivos de entrada .proto, cambia --proto_path a fin de que el compilador busque el directorio donde guardaste bookstore.proto.

2. Crea un archivo YAML de configuración de la API de gRPC:
   1. Guarda una copia del archivo api_config.yaml. Este archivo define la configuración de la API de gRPC para el servicio de Bookstore.
   2. Reemplaza MY_PROJECT_ID en tu archivo api_config.yaml con el ID de tu proyecto de Google Cloud. Por ejemplo:

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Ten en cuenta que el valor del campo apis.name en este archivo coincide con exactitud con el nombre de API calificado por completo del archivo .proto; de lo contrario, la implementación no funcionará. El servicio de Bookstore se define en bookstore.proto dentro del paquete endpoints.examples.bookstore. Su nombre de API calificado por completo es endpoints.examples.bookstore.Bookstore, tal como aparece en el archivo api_config.yaml.

      apis:
        - name: endpoints.examples.bookstore.Bookstore
      

Consulta Configurar Endpoints para obtener más información.

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Management a fin de crear un servicio administrado.

1. Asegúrate de estar en el directorio en el que se encuentran los archivos api_descriptor.pb y api_config.yaml.
2. Confirma que el proyecto predeterminado que se usa actualmente en la herramienta de línea de comandos de gcloud sea el proyecto de Google Cloud en el que deseas implementar la configuración de Endpoints. Valida el ID del proyecto que se muestra en el comando siguiente para asegurarte de que el servicio no se cree en el proyecto equivocado.

   gcloud config list project
   

   Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando:

   gcloud config set project YOUR_PROJECT_ID
   

3. Implementa el archivo proto descriptor y el archivo de configuración mediante Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   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 [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó la implementación. Por ejemplo:

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

   En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y bookstore.endpoints.example-project.cloud.goog es el nombre del servicio. El ID de configuración del servicio consiste en una marca de fecha seguida de un número de revisión. Si implementas la configuración de Endpoints otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio.

Verifica los servicios requeridos

Como mínimo, Endpoints y el ESP requieren que se habiliten los siguientes servicios de Google:

Nombre	Título
servicemanagement.googleapis.com	API de Service Management
servicecontrol.googleapis.com	API de Service Control
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 Extremos 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.

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

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

Implementar el backend de la API

Hasta ahora, implementaste la configuración de API en Service Management, pero aún no implementaste el código que entrega el backend de la API. En esta sección, aprenderás a configurar Docker en tu instancia de VM y ejecutar el código del backend de la API y el ESP en un contenedor de Docker.

Instala Docker en la instancia de VM

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

1. Configura la zona para tu proyecto mediante la ejecución del comando siguiente:

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Reemplaza YOUR_INSTANCE_ZONE por la zona donde se ejecuta tu instancia.

2. Conecta tu instancia con el comando siguiente:

   gcloud compute ssh INSTANCE_NAME
   

   Reemplaza INSTANCE_NAME por el nombre de tu instancia de VM.

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

Ejecuta la API y el ESP de muestra en un contenedor de Docker

Si quieres ejecutar el servicio de gRPC de muestra con ESP en un contenedor de Docker para que los clientes puedan usarlo, haz lo siguiente:

1. En la instancia de VM, crea tu propia red de contenedores llamada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Ejecuta el servidor de Bookstore de muestra que entrega la API de muestra:

   sudo docker run \
       --detach \
       --name=bookstore \
       --net=esp_net \
       gcr.io/endpointsv2/python-grpc-bookstore-server:1
   

3. Ejecuta el contenedor de Docker del ESP empaquetado con anterioridad. En las opciones de inicio del ESP, reemplaza SERVICE_NAME por el nombre de tu servicio. Este es el mismo nombre que configuraste en el campo name del archivo api_config.yaml. Por ejemplo: bookstore.endpoints.example-project-12345.cloud.goog

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --http2_port=9000 \
       --backend=grpc://bookstore:8000
   

   La opción --rollout_strategy=managed configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, hasta 5 minutos después de implementar una nueva configuración de servicio, el ESP detecta el cambio y comienza a usarlo automáticamente. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP. Si quieres obtener más detalles sobre los argumentos del ESP, consulta Opciones de inicio de ESP.

Si tienes habilitada la Transcodificación, asegúrate de configurar un puerto para el tráfico HTTP1.1 o SSL.

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

Enviar una solicitud a la API

Si envías la solicitud desde la misma instancia en la que se ejecutan los contenedores de Docker, puedes reemplazar $SERVER_IP por localhost. De lo contrario, reemplaza $SERVER_IP por la IP externa de la instancia.

Para buscar la dirección IP externa, ejecuta el comando siguiente:

gcloud compute instances list

Para enviar solicitudes a la API de muestra, puedes usar un cliente gRPC de muestra escrito en Python.

1. Clona el repositorio de Git donde se aloja el código del cliente gRPC:

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

2. Cambia tu directorio de trabajo:

   cd python-docs-samples/endpoints/bookstore-grpc/
     

3. Instala las dependencias:

   pip install virtualenv
   virtualenv env
   source env/bin/activate
   python -m pip install -r requirements.txt
   

4. Envía una solicitud a la API de muestra:

   python bookstore_client.py --host SERVER_IP --port 80
   

   • Para ver los grafos de actividad de tu API, ve a la página Endpoints > Servicios.
     

     Ir a la página Servicios de Endpoints

     La solicitud puede tardar unos minutos en reflejarse en los gráficos.

   • Revisa los registros de solicitud de tu API en la página del visor de registros.
     

     Ir a la página Explorador de registros

Si no obtienes una respuesta correcta, consulta Solucionar errores en las respuestas.

¡Acabas de implementar y probar una API en Endpoints!

Nota: Si quieres contarnos qué te gustó de este instructivo, envíanos tus comentarios al final de esta página. Tus comentarios nos ayudarán a mejorar estos instructivos.
Si recibiste un error, únete al grupo de Google google-cloud-endpoints y cuéntanos cuál fue el problema. En este grupo hay respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

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.

1. Borra la API:

   gcloud endpoints services delete SERVICE_NAME
   

   Reemplaza SERVICE_NAME con el nombre de tu servicio.

2. En la consola de Google Cloud, ve a la página Instancias de VM.

   Ir a Instancias de VM

3. Selecciona tu instancia en la casilla de verificación de es la instancia que deseas borrar.
4. Para borrar la instancia, haz clic en Más acciones, haz clic en Borrar y, luego, sigue las instrucciones.

¿Qué sigue?

• Obtén información sobre cómo configurar tu propia API de gRPC para Endpoints.
• Mira la muestra de Bookstore con más detalle en GitHub. El cliente y el servidor están disponibles en Python y Java.
• La muestra getting-started-grpc está disponible en GitHub en los lenguajes siguientes:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js