Comienza a usar Cloud Endpoints Frameworks para Python

---

En esta página se muestra cómo configurar, implementar y enviar solicitudes a una API de muestra mediante Cloud Endpoints Frameworks para Python. Endpoints Frameworks para Python está integrado en el entorno de ejecución estándar Python 2.7 de App Engine. Endpoints Frameworks consta de herramientas, bibliotecas y funciones que te permiten generar bibliotecas cliente y API desde una aplicación de App Engine.

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. Consulta Antes de comenzar.
2. Instala el software obligatorio y crea una aplicación de App Engine. Consulta Cómo instalar y configurar el software obligatorio.
3. Descarga el código de muestra. Consulta Cómo descargar el código de muestra.
4. Genera un documento de OpenAPI. Consulta Cómo configurar Endpoints.
5. Implementa la configuración de Endpoints para crear un servicio de este sistema. Consulta Cómo implementar la configuración de Endpoints.
6. Ejecuta la muestra en tu computadora. Consulta Ejecuta la muestra de manera local.
7. Crea un backend para entregar la API y, luego, implementarla. Consulta Implementa el backend de la API.
8. Envía una solicitud a la API. Consulta Enviar una solicitud a la API.
9. Realiza un seguimiento de la actividad de la API. Consulta Realizar un seguimiento de la actividad de la API.
10. 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:

• Extremos
• App Engine

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

Nota: Asegúrate de tener instalado Python 2.7.x. Python 3.x no es compatible con Endpoints Frameworks.

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 de Google Cloud, ya que lo necesitarás más adelante.

Instala y configura el software obligatorio

1. Sigue las instrucciones en Cómo instalar Google Cloud CLI para Python para configurar el entorno de desarrollo estándar de App Engine. Asegúrate de instalar los componentes app-engine-python y app-engine-python-extras gcloud.
2. Ejecuta los siguientes comandos:
   1. Actualiza gcloud CLI.

      gcloud components update

   2. Asegúrate de que Google Cloud CLI (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   3. Se abrirá una nueva pestaña del navegador donde debes elegir una cuenta.
   4. Configura el proyecto predeterminado con tu ID del proyecto.

      gcloud config set project [YOUR_PROJECT_ID]

      Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto de Google Cloud. Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta Administra gcloud CLI de gcloud.

3. 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 compatible con PowerShell 3.0 y versiones posteriores.
4. Asegúrate de que tu entorno de desarrollo de Python incluya pip.
5. Asegúrate de que puedas compilar extensiones C para Python.
   • Windows: Es obligatorio tener Microsoft Visual C++ 9.0 o una versión superior. Puedes descargar el compilador de Microsoft Visual C++ para Python 2.7 desde el Centro de descargas de Microsoft.
   • Otros sistemas operativos: Según tu sistema operativo, es posible que debas instalar herramientas del compilador (a veces, en un paquete denominado build-essential) o los encabezados de desarrollo de Python (a veces, en un paquete denominado python-dev).

6. Para Linux, debes establecer la variable de entorno ENDPOINTS_GAE_SDK como la ruta de la carpeta del SDK de App Engine: [Path-to-Google-Cloud-SDK]/platform/google_appengine.

   Reemplaza [Path-to-Google-Cloud-SDK] por el resultado del siguiente comando:

   gcloud info --format="value(installation.sdk_root)"

7. Crea una aplicación de App Engine:
   1. 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

   2. Crea una aplicación de App Engine con el siguiente comando. Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto de Google Cloud y [YOUR_REGION] por la región en la que deseas que se cree la aplicación de App Engine.

      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      Por ejemplo:

      gcloud app create --project=example-project-12345 --region=us-central

Cómo obtener el código de muestra

Para clonar la API de muestra desde GitHub:

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

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

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

   cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

Cómo configurar Endpoints

Para configurar Endpoints, primero debes instalar la biblioteca de Python de Endpoints Frameworks. Luego, usa una herramienta de la biblioteca de Endpoints Frameworks a fin de generar un documento de OpenAPI para la API de muestra. Necesitas la biblioteca de Endpoints Frameworks y el documento de OpenAPI para que Endpoints pueda administrar la API. Si deseas obtener más información, consulta Cómo agregar una administración de API.

Cómo instalar la biblioteca de Endpoints Frameworks

En esta sección se explica cómo usar pipde Python para agregar la biblioteca de Endpoints Frameworks al directorio del proyecto de la API de muestra.

Nota: No ejecutes Python en un entorno virtual. Los paquetes de Endpoints Frameworks deben instalarse en el subdirectorio lib bajo el directorio del proyecto en tu computadora.

Para agregar la biblioteca de Endpoints Frameworks a la muestra, sigue estos pasos:

1. Asegúrate de estar en el directorio principal de la API de muestra, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

2. Crea un subdirectorio /lib en el proyecto:

   mkdir lib
   

3. Desde el directorio principal de muestra python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, ejecuta el comando de instalación:

   pip install --target lib --requirement requirements.txt --ignore-installed
   

   Ten en cuenta lo siguiente:

   • Este comando pip puede usar GCC (la colección de compiladores de GNU) para compilar módulos de extensión. Si tienes macOS y esta es la primera vez que ejecutas GCC en tu sistema, es posible que debas aceptar la licencia Xcode de Apple. Para hacerlo, ejecuta sudo xcodebuild -license.

   • Si tienes varias versiones de Python instaladas en tu computadora, asegúrate de usar una versión de pip correspondiente a la versión de Python que usarás en este instructivo. La incompatibilidad entre las versiones (por ejemplo, pip de Python 3.4 mientras se usa python de Python 2.7) pueden causar errores difíciles de entender. Si es necesario, puedes ejecutar pip como un módulo de Python: reemplaza pip en el comando anterior con python -m pip.

   • Si pip no puede encontrar un paquete adecuado cuando ejecuta el comando, intenta actualizarlo ejecutando pip install --upgrade pip. Luego de que se complete la actualización, vuelve a intentar el comando de instalación.

   • En algunas versiones de Debian y Ubuntu, pip podría fallar con DistutilsOptionError. Si ves este error, agrega la marca --system.

Cuando el proceso finalice correctamente, el directorio lib se propagará con los archivos necesarios para compilar la aplicación de Endpoints Frameworks.

Cómo generar el documento de OpenAPI

Usas una herramienta de la biblioteca de Endpoints Frameworks para generar un documento que describe la API de REST del código de muestra.

Para generar el documento de OpenAPI, realiza los siguientes pasos:

1. Asegúrate de que estés en el directorio principal de muestra:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Genera el documento de OpenAPI:

   python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
   

   Reemplaza [YOUR_PROJECT_ID] por el ID del proyecto de Google Cloud. Ignora las advertencias que se muestran. La herramienta de Endpoints genera un documento de OpenAPI llamado echov1openapi.json en el directorio actual. La herramienta de Endpoints nombra el archivo en función del nombre y la versión del servicio especificado en el decorador @endpoints.api. Consulta Cómo crear la API para obtener más información.

   Endpoints utiliza el texto especificado en el argumento hostname como el nombre del servicio. El formato del nombre YOUR_PROJECT_ID.appspot.com coincide con la entrada de DNS que se crea automáticamente cuando implementas la API en el backend de App Engine. Por eso, en este caso, tanto el nombre del servicio de Endpoints como el nombre de dominio completamente calificado (FQDN) son iguales.

Cuando el proceso finalice con éxito, se mostrará el siguiente mensaje: OpenAPI spec written to ./echov1openapi.json

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, utiliza la Infraestructura de servicios, que es la plataforma básica de servicios de Google utilizada por Endpoints y otros servicios con el fin de crear y administrar las API y los servicios.

Para implementar el archivo de configuración, haz lo siguiente:

1. Asegúrate de que estés en el directorio principal de muestra:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Implementa el documento de OpenAPI que se generó en la sección anterior con el comando siguiente:

   gcloud endpoints services deploy echov1openapi.json
   

   Esto crea un servicio de Endpoints nuevo con el nombre que especificaste en el argumento hostname cuando ejecutaste la herramienta de Endpoints para generar el documento de OpenAPI. Sin importar cuál sea el nombre del servicio de Endpoints, cuando implementas la API en App Engine se crea un registro DNS con el formato de nombre YOUR_PROJECT_ID.appspot.com, que es el FQDN que usas cuando envías solicitudes a la API.

   Mientras se crea y configura el servicio, Service Management envía una gran cantidad de información a la terminal. Puedes ignorar sin riesgo las advertencias que indican que las rutas de echov1openapi.json no requieren una clave de API. Cuando finalice la implementación, aparecerá un mensaje similar al siguiente:

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

   En el ejemplo anterior, 2017-02-13-r2 es el ID de la configuración del servicio y example-project-12345.appspot.com es el nombre del servicio.

   Consulta gcloud endpoints services deploy en la documentación de referencia gcloud para obtener más información.

Verifica los servicios requeridos

Para proporcionar administración de API, Endpoints Frameworks requiere los siguientes servicios:

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

Ejecuta la muestra de forma local

Luego de implementar la configuración de Endpoints, puedes ejecutar la muestra de forma local con el servidor de desarrollo local.

1. Asegúrate de que estés en el directorio principal de muestra:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Inicia el servidor de desarrollo local:

   dev_appserver.py ./app.yaml
   

   De forma predeterminada, el servidor de desarrollo escucha en http://localhost:8080, como se indica en los registros de la consola de Google Cloud impresos por dev_appserver.py:

   INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
   

3. Envía una solicitud al servidor de desarrollo local:

Linux o macOS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

En el curl anterior, ocurre 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

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").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. Si deseas obtener más información sobre las opciones utilizadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

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

{
 "message": "hello world"
}

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 la API de muestra en App Engine.

Para implementar el backend de la API:

1. Ejecuta el siguiente comando para mostrar el ID de configuración del servicio:

   gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
   

   Reemplaza [YOUR_PROJECT_ID] con el ID del proyecto. Por ejemplo:

   gcloud endpoints configs list --service=example-project-12345.appspot.com
   
   

2. Abre el archivo app.yaml en el directorio python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

   env_variables:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy swagger.json' command.
     ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
     ENDPOINTS_SERVICE_VERSION: 2016-08-01r0

3. Realiza los siguientes cambios en la sección env_variables:
   • En el campo ENDPOINTS_SERVICE_NAME, reemplaza YOUR-PROJECT-ID por tu ID del proyecto de Google Cloud.
   • En el campo ENDPOINTS_SERVICE_VERSION, reemplaza el texto por el ID de configuración del servicio. Por ejemplo:

     ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
     ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
   

4. Ejecuta el siguiente comando:

   gcloud app deploy
   

5. Sigue las indicaciones que aparecen en pantalla. Espera unos instantes para que la implementación se realice de manera correcta; ignora los mensajes de advertencia. Cuando se complete la implementación, verás un mensaje similar al siguiente:

   File upload done.
   Updating service [default]...done.
   

   Si recibiste un mensaje de error, consulta la sección Solución de problemas en la documentación de App Engine para obtener más información.

   Recomendamos que esperes unos minutos antes de enviar solicitudes a la API mientras App Engine se inicializa de forma completa.

Cómo enviar una solicitud a la API de muestra

Linux o macOS

Envía una solicitud HTTP con curl. Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto de Google Cloud.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

En el curl anterior, ocurre 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

Envía una solicitud HTTP con Invoke-WebRequest. Reemplaza [YOUR_PROJECT_ID] por el ID de tu proyecto de Google Cloud.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").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"}
• Ingresa la URL a la aplicación de muestra. Por ejemplo:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

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.

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 encontrarás respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

Realiza un seguimiento de la actividad de la API

1. Consulta los gráficos de actividad de tu API en la consola de Google Cloud en la página Endpoints > Servicio.

   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.

Precaución: Borrar un proyecto tiene estas consecuencias:
• Se borra todo en el proyecto. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.
1. En la consola de Google Cloud, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

• Obtén más información sobre la arquitectura de Endpoints Frameworks.
• Obtén más información sobre cómo crear una API.
• Obtén más información sobre cómo crear un servidor web para entregar tu API.
• Obtén más información sobre cómo entregar tu API desde una ruta diferente.
• Obtén más información sobre cómo supervisar tu API.
• Obtén más información sobre cómo restringir el acceso con claves de API.
• Obtén más información sobre cómo configurar un nombre de dominio personalizado.
• Obtén más información sobre cómo manejar control de versiones de API.
• Obtén más información sobre opciones de asistencia.