Implementa una API administrada por Cloud Endpoints

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.

• Cloud Endpoints para OpenAPI: instructivos
• Cloud Endpoints para gRPC: instructivos
• Cloud Endpoints Frameworks: instructivos

Antes de comenzar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

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 ventana emergente con una línea de comandos. La sesión puede tardar unos segundos en inicializarse.

   

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

   gcloud components update
   

Nota: Si usas una máquina Linux o MacOS y quieres seguir esta guía de inicio rápido con tu shell local, descarga Google Cloud CLI y usa tu interfaz de línea de comandos local, en lugar de Cloud Shell, para llevar a cabo estas instrucciones de inicio rápido.

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 genera información a la consola de Google Cloud. 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 estén habilitados los siguientes servicios de Google:

Name	Título
endpoints.googleapis.com	Google Cloud Endpoints
servicecontrol.googleapis.com	Service Control API
servicemanagement.googleapis.com	API de Service Management

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

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

Con las APIs implementadas con Endpoints, puedes supervisar las métricas de operaciones críticas en la consola de Google Cloud y obtener estadísticas sobre tus 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
   

   Nota: Esta secuencia de comandos genera solicitudes en bucle y agota el tiempo de espera de forma automática en 5 minutos. Para finalizar la secuencia de comandos antes, ingresa Control+C en Cloud Shell.

2. En la consola de Google Cloud, consulta 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

Beta

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

Precaución: Borrar un proyecto tiene las siguientes 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

¿Qué sigue?

• Para obtener una descripción general de Endpoints, lee la información siguiente:

  • Acerca de Endpoints
  • Endpoints: descripción general de la arquitectura

• Para obtener información sobre los diferentes marcos de API que son compatibles con Endpoints, consulta las secciones siguientes:

  • OpenAPI Specification
  • Endpoints para las API de gRPC
  • Acerca Endpoints Frameworks

• Para aprender a configurar y a implementar una API de muestra, selecciona un instructivo de uno de los marcos de trabajo de API.

  • Endpoints para OpenAPI: instructivos
  • Endpoints para gRPC: instructivos
  • Endpoints Frameworks: instructivos