Empezar a usar Cloud Endpoints Frameworks para Python

En esta página se explica cómo configurar, desplegar y enviar solicitudes a una API de ejemplo mediante Cloud Endpoints Frameworks para Python. Endpoints Frameworks para Python está integrado con el entorno de ejecución estándar de Python 2.7 de App Engine. Endpoints Frameworks incluye herramientas, bibliotecas y funciones que te permiten generar APIs y bibliotecas de cliente a partir de una aplicación de App Engine.

Obtener el código de ejemplo

Para clonar la API de ejemplo de GitHub, sigue estos pasos:

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

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

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

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

Configurar Endpoints

Para configurar Endpoints, primero debes instalar la biblioteca de Python de Endpoints Frameworks. A continuación, usa una herramienta de la biblioteca Endpoints Frameworks para generar un documento de OpenAPI de la API de ejemplo. Necesitas la biblioteca de Endpoints Frameworks y el documento OpenAPI para que Endpoints pueda gestionar la API. Para obtener más información, consulta Añadir gestión de APIs.

Instalar la biblioteca de Endpoints Frameworks

En esta sección se explica cómo usar pip de Python para añadir la biblioteca de Endpoints Frameworks al directorio del proyecto de la API de ejemplo.

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

Para añadir la biblioteca Endpoints Frameworks al ejemplo, sigue estos pasos:

1. Asegúrate de que estás en el directorio principal de la API de ejemplo, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

2. Crea un subdirectorio /lib en el proyecto:

   mkdir lib
   

3. En el directorio principal de ejemplo 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 GNU Compiler Collection (GCC) para compilar módulos de extensión. Si usas macOS y es la primera vez que ejecutas GCC en tu sistema, es posible que tengas que aceptar la licencia de Xcode de Apple. Para hacerlo, ejecuta sudo xcodebuild -license.

   • Si tienes varias versiones de Python instaladas en tu ordenador, asegúrate de que estás usando una versión de pip correspondiente a la versión de Python que estás usando en este tutorial. Las versiones no coincidentes (por ejemplo, pip de Python 3.4 mientras se usa python de Python 2.7) pueden provocar errores que pueden ser difíciles de entender. Si es necesario, puedes ejecutar pip como módulo de Python: sustituye pip en el comando anterior por python -m pip.

   • Si pip no encuentra un paquete adecuado al ejecutar el comando, prueba a actualizarlo ejecutando pip install --upgrade pip. Cuando se haya completado la actualización, vuelve a probar el comando de instalación.

   • En algunas versiones de Debian y Ubuntu, pip puede fallar con DistutilsOptionError. Si aparece este error, añade la marca --system.

Si se completa correctamente, el directorio lib se rellena con los archivos necesarios para compilar la aplicación Endpoints Frameworks.

Generar el documento de OpenAPI

Utilizas una herramienta de la biblioteca Endpoints Frameworks para generar un documento que describa la API REST del código de ejemplo.

Para generar el documento de OpenAPI, sigue estos pasos:

1. Asegúrate de que estás en el directorio principal de ejemplo:

   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
   

   Sustituye [YOUR_PROJECT_ID] por el ID de tu proyecto. Google Cloud Ignora las advertencias que se muestran. La herramienta Endpoints genera un documento OpenAPI llamado echov1openapi.json en el directorio actual. La herramienta Endpoints asigna al archivo el nombre y la versión del servicio especificados en el decorador @endpoints.api. Consulta más información en Crear la API.

   Endpoints usa el texto especificado en el argumento hostname como nombre del servicio. El formato de nombre YOUR_PROJECT_ID.appspot.com coincide con la entrada DNS que se crea automáticamente al implementar la API en el backend de App Engine. Por lo tanto, en este caso, el nombre del servicio Endpoints y el nombre de dominio completo (FQDN) son los mismos.

Si se completa correctamente, se mostrará el siguiente mensaje: OpenAPI spec written to ./echov1openapi.json

Desplegar la configuración de Endpoints

Para desplegar la configuración de Endpoints, se usa Service Infrastructure, la plataforma de servicios básicos de Google que usan Endpoints y otros servicios para crear y gestionar APIs y servicios.

Para implementar el archivo de configuración, sigue estos pasos:

1. Asegúrate de que estás en el directorio principal de ejemplo:

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

2. Para implementar el documento de OpenAPI que se ha generado en la sección anterior, ejecuta el siguiente comando:

   gcloud endpoints services deploy echov1openapi.json

   De esta forma, se crea un servicio de Endpoints con el nombre que has especificado en el argumento hostname al ejecutar la herramienta de Endpoints para generar el documento OpenAPI. Independientemente del nombre del servicio Endpoints, cuando despliegue la API en App Engine, se creará un registro DNS con el formato de nombre YOUR_PROJECT_ID.appspot.com, que es el FQDN que usará cuando envíe solicitudes a la API.

   Mientras crea y configura el servicio, Gestión de servicios muestra mucha información en la terminal. Puedes ignorar las advertencias sobre las rutas de echov1openapi.json que no requieren una clave de API. Cuando se complete la implementación, se mostrará 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 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 de gcloud para obtener más información.

Comprobando los servicios necesarios

Para proporcionar gestión de APIs, Endpoints Frameworks requiere los siguientes servicios:

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.

Ejecutar la muestra de forma local

Después de implementar la configuración de Endpoints, puedes ejecutar el ejemplo de forma local mediante el servidor de desarrollo local.

1. Asegúrate de que estás en el directorio principal de ejemplo:

   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 que imprime Google Cloud 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 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

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

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

{
 "message": "hello world"
}

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

Para desplegar el backend de la API, sigue estos pasos:

1. Para mostrar el ID de configuración del servicio, ejecuta el siguiente comando:

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

   Sustituye [YOUR_PROJECT_ID] por el ID del proyecto. Por ejemplo:

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

2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

   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

Haga los siguientes cambios en la sección env_variables:

• En el campo ENDPOINTS_SERVICE_NAME, sustituye YOUR-PROJECT-ID por el ID de tu proyecto Google Cloud .
• En el campo ENDPOINTS_SERVICE_VERSION, sustituye 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

Ejecuta el siguiente comando:

gcloud app deploy

Sigue las indicaciones que aparecen en pantalla. Espera unos instantes a que la implementación se complete correctamente. Ignora los mensajes de advertencia. Cuando se complete la implementación, aparecerá un mensaje similar al siguiente:

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

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

Te recomendamos que esperes unos minutos antes de enviar solicitudes a tu API mientras App Engine se inicializa por completo.

Enviar una solicitud a la API de ejemplo

Linux o macOS

Envía una solicitud HTTP mediante curl. Sustituye [YOUR_PROJECT_ID] por elGoogle Cloud ID de tu proyecto:

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

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

Envía una solicitud HTTP mediante Invoke-WebRequest. Sustituye [YOUR_PROJECT_ID] por el ID de tu proyecto: 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 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"}
• Introduce la URL de la aplicación de ejemplo. Por ejemplo:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

La API devuelve el mensaje que le 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.

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.

Monitorizar la actividad de la API

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

   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