Comienza a usar Endpoints Frameworks para Java

---

En esta página se muestra cómo configurar, implementar y enviar solicitudes a una API de muestra con Marcos de trabajo de Cloud Endpoints para Java. Los marcos de trabajo de Endpoints para Java se integran en el entorno de ejecución de App Engine estándar para Java 8. Endpoints Frameworks cuenta con herramientas, bibliotecas y capacidades que te permiten generar API y bibliotecas cliente mediante 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 obtener el código de muestra.
4. Genera un archivo de configuración de OpenAPI. Consulta Cómo configurar Cloud Endpoints.
5. Implementa la configuración de Endpoints para crear un servicio de Endpoints. 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 Cómo 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:

• Endpoints
• 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

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.

6. Toma nota del ID del proyecto, ya que será necesario más tarde.

Cómo instalar y configurar el software obligatorio

1. Si no tienes Java 8 instalado, descarga el Java Development Kit (JDK) de Oracle y, a continuación, instálalo. Debido a que los marcos de trabajo de Endpoints para Java dependen del entorno de ejecución de App Engine estándar para Java 8, estos no son compatibles con ninguna otra versión de Java.
2. Si no tienes Maven 3.3.9 o una versión superior, descárgalo y, luego, instálalo.

Nota para los usuarios de Windows: Si instalas Maven y el JDK en Windows, hazlo en un directorio que no tenga un espacio en la ruta. Consulta Maven en Windows para obtener más información.

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, que es compatible con PowerShell 3.0 y versiones posteriores.
4. Descarga e inicializa Google Cloud CLI.
5. Ejecuta los siguientes comandos:
   1. Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   2. Usa las credenciales predeterminadas de la aplicación:

      gcloud auth application-default login

   3. Instala el componente app-engine-java del SDK de Google Cloud:

      gcloud components install app-engine-java

   4. Actualiza a la versión más reciente del SDK de Google Cloud y de todos los componentes:

      gcloud components update

6. Crea una aplicación de App Engine:
   1. Configura el proyecto predeterminado con tu ID del proyecto.

      gcloud config set project YOUR_PROJECT_ID

      Reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloud. Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta Cómo gcloud CLI de gcloud.

   2. Selecciona la región en la que deseas crear tu app de App Engine. Ejecuta el siguiente comando para obtener una lista de regiones:

      gcloud app regions list

   3. 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 donde deseas que se cree la aplicación de App Engine.

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

Obtén 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/java-docs-samples
   

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

   cd java-docs-samples/appengine-java8/endpoints-v2-backend
   

Configura Endpoints

El código de muestra incluye la herramienta de marcos de trabajo de Endpoints que genera un archivo de configuración OpenAPI que describe la API de REST del código de la muestra. Sigue los pasos en esta sección para configurar y compilar el proyecto Maven de muestra a fin de que puedas generar el archivo de configuración OpenAPI.

Agrega el ID del proyecto al código de la API de muestra

Debes agregar el ID del proyecto obtenido cuando creaste tu proyecto a la muestra pom.xml antes de implementar el código.

Para agregar el ID del proyecto, haz lo siguiente:

1. Edita el archivo java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

2. Busca <endpoints.project.id> y reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud.

   Por ejemplo:

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. Guarda los cambios.

Cómo compilar el proyecto de muestra

Para compilar el proyecto, haz lo siguiente:

1. Asegúrate de estar en el directorio java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Ejecuta el comando siguiente:

   mvn clean package
   

3. Espera a que se compile el proyecto. Cuando el proyecto finalice de forma correcta, se mostrará un mensaje similar a este:

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 14.846s
   [INFO] Finished at: Wed April 13 09:43:09 PDT 2016
   [INFO] Final Memory: 24M/331M
   

Genera el archivo de configuración de OpenAPI

Usas una herramienta de la biblioteca Endpoints Frameworks para generar un documento OpenAPI llamado openapi.json. Este archivo describe la API de REST del código de muestra.

Para generar un archivo de configuración de OpenAPI:

1. Invoca la herramienta de marcos de trabajo de Endpoints con este comando:

   mvn endpoints-framework:openApiDocs
   

2. Espera a que se compile la especificación de la configuración. Se muestra un mensaje similar a este cuando finaliza:

   OpenAPI document written to target/openapi-docs/openapi.json
   

   Ignora cualquier mensaje sobre errores cuando se sube una clase de registrador estático.

Cómo implementar la configuración de Endpoints

Para implementar la configuración de Endpoints, utiliza la Infraestructura de servicios, la plataforma fundamental de servicios de Google, que utiliza el marco de trabajo de Endpoints y otros servicios para crear y administrar las API y los servicios.

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

1. Asegúrate de estar en el directorio java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Implementa el archivo de configuración de OpenAPI que se generó en la sección anterior:

   gcloud endpoints services deploy target/openapi-docs/openapi.json
   

Esto crea un nuevo servicio de Endpoints con el nombre en el formato YOUR_PROJECT_ID.appspot.com. Este nombre se configura en pom.xml y otros archivos de configuración incluidos en la muestra. Ten en cuenta que, 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 nombre de dominio completo que utilizas cuando envías solicitudes a la API.

Mientras se crea y configura el servicio, Service Management exporta la información a la terminal. Las advertencias que te avisan que las rutas de openapi.json no requieren una clave de API pueden ignorarse sin riesgo. Una vez completado de forma correcta, una línea similar a la siguiente muestra el ID de configuración del servicio y el nombre del servicio:

Service Configuration [2017-02-13-r2] 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 implementación de servicios de extremos de gcloud para obtener más información.

Verifica los servicios requeridos

Para permitirte administrar tu API, Endpoints Frameworks requiere los siguientes servicios:

Nombre	Título
servicemanagement.googleapis.com	API de Administración de servicios
servicecontrol.googleapis.com	Service Control API

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

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

Después de implementar la configuración de Endpoints, puedes ejecutar la muestra de manera local.

1. Crea una variable de entorno llamada ENDPOINTS_SERVICE_NAME, que se utiliza en el archivo appengine-web.xml de la muestra para establecer el nombre de host. A continuación, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud.

   En Linux o macOS:

   export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
   

   En Windows PowerShell:

   $Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
   

2. Adquiere credenciales de usuario nuevas para utilizar las Credenciales predeterminadas de la aplicación:

   gcloud auth application-default login
   

3. Ejecuta el servidor de desarrollo:

   mvn appengine:run
   

   Se puede acceder a la instancia local en http://localhost:8080 como lo indican los registros impresos con el comando mvn appengine:run:

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. Envía una solicitud a la instancia 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, sucede 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 implementaste el código que entrega 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, sigue estos pasos:

1. Asegúrate de estar en el directorio java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Implementa el código de implementación de la API con Maven:

    mvn appengine:deploy
   

   Se te solicitará que autorices la implementación la primera vez que subas una aplicación de muestra. Sigue las indicaciones. Aparecerá una ventana del navegador con un código, cópialo en la ventana de terminal.

3. Espera a que finalice la carga.

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

Cómo enviar una solicitud a la API

Después de implementar la API y su archivo de configuración, puedes enviar solicitudes a la API.

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, sucede 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 Solución de problemas en las respuestas.

¡Acabas de implementar y probar una API en el marco de trabajo de 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

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

• Obtén más información sobre la arquitectura de Endpoints Frameworks.
• Obtén más información sobre anotaciones de la API disponibles.
• 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 manejar control de versiones de API.
• Obtén más información sobre las opciones del servicio de asistencia de la comunidad.