Implementa una API administrada por Cloud Endpoints

En esta guía de inicio rápido, aprenderás a implementar una API de muestra administrada por Endpoints. El código de muestra incluye lo siguiente

  • Una API de REST que puedes consultar para obtener el nombre de un aeropuerto a partir de su código de IATA de tres letras.
  • Una secuencia de comandos que sube la configuración de la API a Endpoints.
  • Una secuencia de comandos que implementa un backend de entorno flexible de App Engine a fin de alojar la API de muestra.

Después de enviar solicitudes a la API de muestra, puedes ver los gráficos de actividad de Endpoints y los registros de observabilidad de Google Cloud en la consola de Google Cloud. Estas herramientas te permiten supervisar tus API y obtener información valiosa sobre su uso.

En esta guía de inicio rápido, se usan secuencias de comandos para simplificar los pasos de configuración y que puedas ver con rapidez los grafos de actividad y los registros en acción. Para aprender a configurar y a implementar una API de muestra, selecciona un instructivo de uno de los marcos de trabajo de API.

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.

    Ir al selector de proyectos

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

    Descubre cómo puedes habilitar la facturación

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

    Ir al selector de proyectos

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

    Descubre cómo puedes habilitar la facturación

Inicia Cloud Shell

  1. En la consola de Google Cloud, asegúrate de estar en el proyecto que quieres usar para la API de muestra.

  2. Abra Cloud Shell.

    Abra Cloud Shell

    Se abrirá una sesión de Cloud Shell en un marco nuevo en la parte inferior de la consola de Google Cloud, que mostrará una línea de comandos. La sesión puede tardar unos segundos en inicializarse.

    Sesión de Cloud Shell

  3. Si usas un proyecto existente, asegúrate de tener la última versión de todos los componentes de gcloud instalados:

    gcloud components update
    

Obtén el código de muestra

  1. En Cloud Shell, ingresa el comando siguiente a fin de obtener la API y las secuencias de comandos de muestra:

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. Ve al directorio que contiene el código de muestra:

    cd endpoints-quickstart
    

Implementa la configuración de Endpoints

Para publicar una API de REST en Endpoints, se requiere un archivo de configuración de OpenAPI que la describa. La API de muestra viene con un archivo de OpenAPI preconfigurado con el nombre openapi.yaml.

Para crear y administrar API y servicios, Endpoints utiliza Service Management, un servicio de infraestructura de Google Cloud. Si quieres usar Endpoints para administrar una API, debes implementar el archivo de configuración de OpenAPI de la API en Service Management.

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

  1. En Cloud Shell, en el directorio endpoints-quickstart, ingresa lo siguiente:

    cd scripts
    
  2. Ejecuta la secuencia de comandos siguiente que se incluye en la muestra:

    ./deploy_api.sh
    

Endpoints usa el campo host en el archivo de configuración de OpenAPI para identificar el servicio. La secuencia de comandos deploy_api.sh establece el ID de tu proyecto de Google Cloud como parte del nombre configurado en el campo host. Cuando prepares un archivo de configuración de OpenAPI para tu servicio, debes hacerlo de forma manual.

A continuación, la secuencia de comandos implementa la configuración de OpenAPI en Service Management con el comando siguiente: gcloud endpoints services deploy openapi.yaml

Mientras se crea y configura el servicio, Service Management exporta la información a la consola de Google Cloud. Las advertencias que te avisan que las rutas de openapi.yaml no requieren una clave de API pueden ignorarse sin riesgo. Si se completa de forma correcta, verás una línea similar a la siguiente que muestra el ID de configuración del servicio y el nombre del servicio:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

Habilita los servicios requeridos

Como mínimo, Endpoints requiere que estén habilitados 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, la implementación de la configuración de Endpoints habilita estos servicios obligatorios.

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 YOUR-PROJECT-ID.appspot.com

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

Implementa el backend de la API

Hasta ahora, implementaste la configuración de OpenAPI en Service Management, pero aún no el código que entrega el backend de la API. La secuencia de comandos deploy_app.sh que se incluye en la muestra crea un entorno flexible de App Engine a fin de alojar el backend de API y, a continuación, la secuencia de comandos implementa la API en App Engine.

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

  • En Cloud Shell, en el directorio endpoints-quickstart/scripts, ejecuta la secuencia de comandos siguiente:

    ./deploy_app.sh
    

La secuencia de comandos ejecuta el comando siguiente a fin de crear un entorno flexible de App Engine en la región us-central: gcloud app create --region="$REGION"

La creación del backend del entorno flexible de App Engine tarda varios minutos. Después de crear la aplicación, el resultado es el siguiente:

Success! The app is now created.

Luego, la secuencia de comandos ejecuta el comando gcloud app deploy para implementar la API de muestra en App Engine.

Este es el resultado:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

La implementación de la API en App Engine tarda varios minutos. Cuando la API se implementa de forma correcta en App Engine, el resultado es el siguiente:

Deployed service [default] to [https://example-project.appspot.com]

Envía una solicitud a la API

  • En Cloud Shell, después de implementar la API de muestra, puedes enviarle solicitudes si ejecutas la secuencia de comandos siguiente:

    ./query_api.sh
    

La secuencia de comandos replica el comando curl que usa para enviar una solicitud a la API y, luego, muestra el resultado. El resultado es el siguiente:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

La API espera un parámetro de consulta, iataCode, que se configura como un código de aeropuerto IATA válido, como SEA o JFK. Por ejemplo:

./query_api.sh JFK

Nota: App Engine puede tardar unos minutos en responder a las solicitudes de forma correcta. Si envías una solicitud y recibes un error HTTP 502, 503 o algún otro error de servidor, espera un minuto y, luego, inténtalo de nuevo.

¡Acabas de implementar y probar una API en Endpoints!

Realiza un seguimiento de la actividad de la API

Con las API implementadas con Endpoints, puedes supervisar las métricas de operaciones críticas en la consola de Google Cloud y obtener estadísticas sobre los usuarios y el uso con Cloud Logging.

  1. En Cloud Shell, ejecuta la secuencia de comandos de generación de tráfico para propagar los grafos y los registros:

    ./generate_traffic.sh
    
  2. En la consola de Google Cloud, observa los gráficos de actividad de tu API.

    Ir a la página Servicios de Endpoints

    Es posible que la solicitud tarde unos minutos en reflejarse en los grafos. Mientras esperas a que se muestren los datos, puedes hacer lo siguiente:

    • Si el panel lateral Permisos no está abierto, haz clic en +Permisos. El panel Permisos te permite controlar quién tiene acceso a tu API y el nivel de acceso.

    • Haz clic en Historial de implementaciones. En esta pestaña, se muestra el historial de implementaciones de tu API, que incluye la hora de implementación y quien implementó el cambio.

    • Haz clic en Descripción general. Verás ver el tráfico entrante. Una vez que la secuencia de comandos de generación de tráfico se haya ejecutado durante un minuto, verás tres líneas en el grafo de Latencia total (percentiles 50, 95 y 98). Estos datos ofrecen una estimación de los tiempos de respuesta.

  3. Desplázate hasta la tabla debajo de los grafos y en Vínculos, haz clic en Ver registros para GET/airportName. La página Explorador de registros muestra los registros de solicitud de la API.

  4. Abra Cloud Shell.

    Abra Cloud Shell

  5. Si quieres detener la secuencia de comandos, ingresa Control+C.

Agrega una cuota a la API

Endpoints te permite configurar cuotas para controlar la velocidad a la que las aplicaciones pueden llamar a tu API. Puedes usar las cuotas para proteger tu API del uso excesivo por parte de un solo cliente.

  1. En Cloud Shell, implementa la configuración de Endpoints que tiene una cuota.

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    

    Luego de implementar una configuración de Endpoints actualizada, se activa en un minuto.

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

    Ir a la página Credenciales

  3. Haz clic en Crear credenciales y, luego, en Clave de API. Se mostrará una clave de API nueva en la pantalla.

  4. Haz clic en Copiar..

  5. En Cloud Shell, ingresa lo siguiente. Reemplaza YOUR_API_KEY por la clave de API que acabas de crear.

    export API_KEY=YOUR_API_KEY
    
  6. Envía una solicitud a tu API con la clave de API que acabas de generar.

    ./query_api_with_key.sh $API_KEY
    

    El resultado es similar al siguiente:

    curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
    San Francisco International Airport
    
  7. Ahora, la API tiene un límite de 5 solicitudes por minuto. Ejecuta el comando siguiente para enviar tráfico a la API y activar el límite de la cuota:

    ./generate_traffic_with_key.sh $API_KEY
    
  8. Una vez que la secuencia de comandos se ejecuta durante 5 a 10 segundos, ingresa Control+C para detener la secuencia de comandos.

  9. Envía otra solicitud autenticada a la API.

    ./query_api_with_key.sh $API_KEY
    

    El resultado es similar al siguiente:

    {
     "code": 8,
     "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "internal"
      }
     ]
    }
    

Si obtienes una respuesta diferente, prueba ejecutar la secuencia de comandos generate_traffic_with_key.sh de nuevo y, luego, vuelva a intentarlo.

¡Felicitaciones! Estableciste un límite de frecuencia en tu API de forma correcta. También puedes configurar otros tipos de límites con distintos métodos de API, crear varios tipos de cuotas y realizar un seguimiento de qué consumidores usan las distintas API.

Para obtener más información, consulta Acerca de las cuotas.

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

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que se usaron en esta página.

Para evitar que se apliquen cargos a la cuenta, puedes borrar el proyecto de Google Cloud y detener la facturación de todos los recursos que usa.

  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?