Guía de inicio rápido de 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 Google Cloud's operations suite en Google Cloud Console. 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.

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

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

    Ir a la página del selector de proyectos

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

    Descubre cómo puedes habilitar la facturación

Inicia Cloud Shell

  1. En Cloud Console, asegúrate de estar en el proyecto que deseas utilizar para la API de muestra.

  2. Abre Cloud Shell.

    Abre Cloud Shell

    Se abrirá una sesión de Cloud Shell en un marco nuevo en la parte inferior de Cloud Console, que mostrará una ventana emergente con 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

A medida que crea y configura el servicio, Service Management envía información a Cloud Console. Puedes ignorar sin riesgo las advertencias que indican que las rutas de openapi.yaml no requieren una clave de API. 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 se habiliten los siguientes servicios de Google:

Name Cargo
servicemanagement.googleapis.com API de Administración de servicios
servicecontrol.googleapis.com API de Control de servicios
endpoints.googleapis.com Google Cloud Endpoints

En la mayoría de los casos, implementar 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 puede tardar 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 Cloud Console y obtener estadísticas sobre tus usuarios y 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 Cloud Console, mira los gráficos de actividad de tu API.

    Ir a la página de 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. En la página Visor de registros, se muestran los registros de solicitud de la API.

  4. Abre Cloud Shell.

    Abre Cloud Shell

  5. Si quieres detener la secuencia de comandos, ingresa Ctrl+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 Cloud Console, 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 Ctrl-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.

Cómo crear 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 usaste en esta guía de inicio rápido.

Para evitar que se apliquen cargos, puedes borrar el proyecto de Cloud a fin de detener la facturación de todos los recursos que se usan en ese proyecto.

  1. En Cloud Console, ve a la página Administrar recursos.

    Ir a la página Administrar recursos

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

Qué sigue