Empezar a usar Cloud Endpoints Frameworks para Java

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

Instalar y configurar el software necesario

1. Si no tienes instalado Java 8, descarga el kit de desarrollo de Java (JDK) de Oracle e instálalo. Como Endpoints Frameworks para Java depende del entorno de ejecución estándar de Java 8 de App Engine, Endpoints Frameworks no admite ninguna otra versión de Java.
2. Si no tienes Maven 3.3.9 o una versión posterior, descárgalo y instálalo.

Nota para los usuarios de Windows: Si vas a instalar JDK y Maven en Windows, instálalos en un directorio cuyo nombre no contenga espacios. Consulta más información sobre Maven en Windows.

3. Necesitas una aplicación para enviar solicitudes a la API de ejemplo.

   • Usuarios de Linux y macOS: en este tutorial se muestra un ejemplo de uso de curl, que suele venir preinstalado en el sistema operativo. Si no tienes curl, puedes descargarlo desde la curl página de versiones y descargas.
   • Usuarios de Windows: en este tutorial se proporciona un ejemplo con 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 la CLI de gcloud tenga autorización para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   2. Usa las credenciales de aplicación predeterminadas:

      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. Define el ID de tu proyecto como proyecto predeterminado.

      gcloud config set project YOUR_PROJECT_ID

      Sustituye YOUR_PROJECT_ID por el ID de tu proyecto. Google Cloud Si tienes otros Google Cloud proyectos y quieres usar gcloud para gestionarlos, consulta Gestionar configuraciones de gcloud CLI.

   2. Selecciona la región en la que quieras crear tu aplicación 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. Sustituye YOUR_PROJECT_ID por el ID de tu proyecto y Google Cloud por la región en la que quieras crear la aplicación de App Engine.YOUR_REGION

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

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

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

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

Configurar Endpoints

El código de ejemplo incluye la herramienta Endpoints Frameworks, que genera un archivo de configuración OpenAPI que describe la API REST del código de ejemplo. Sigue los pasos de esta sección para configurar y compilar el proyecto Maven de ejemplo de forma que puedas generar el archivo de configuración de OpenAPI.

Añadir el ID de proyecto al código de ejemplo de la API

Debes añadir el ID de proyecto que obtuviste al crear el proyecto al pom.xml del ejemplo para poder implementar el código.

Para añadir el ID de proyecto, sigue estos pasos:

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

2. Busca <endpoints.project.id> y sustituye YOUR_PROJECT_ID por elGoogle Cloud ID de tu proyecto.

   Por ejemplo:

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

3. Guarda los cambios.

Compilar el proyecto de ejemplo

Para compilar el proyecto, sigue estos pasos:

1. Asegúrate de que estás en el directorio java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Ejecuta el siguiente comando:

   mvn clean package
   

3. Espera a que se compile el proyecto. Cuando el proyecto finalice correctamente, 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
   

Generar el archivo de configuración de OpenAPI

Utilizas una herramienta de la biblioteca Endpoints Frameworks para generar un documento OpenAPI llamado openapi.json. En este archivo se describe la API REST del código de ejemplo.

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

1. Invoca la herramienta Endpoints Frameworks con este comando:

   mvn endpoints-framework:openApiDocs
   

2. Espera a que se cree la especificación de configuración. Cuando termine, se mostrará un mensaje similar a este:

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

   Ignora los mensajes sobre errores al cargar una clase de registro estática.

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 Frameworks 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 java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Despliega el archivo de configuración de OpenAPI que se ha generado en la sección anterior:

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

De esta forma, se crea un servicio de Endpoints con el nombre en el formato YOUR_PROJECT_ID.appspot.com. Este nombre se configura en pom.xml y en 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 (FQDN) que usas cuando envías solicitudes a la API.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Puedes ignorar las advertencias sobre las rutas de openapi.json que no requieren una clave de API. Si se completa correctamente, se mostrará una línea similar a la siguiente con 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 más información sobre gcloud Endpoints services deploy.

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 desplegar la configuración de Endpoints, puedes ejecutar el ejemplo de forma local.

1. Crea una variable de entorno llamada ENDPOINTS_SERVICE_NAME, que se usa en el archivo appengine-web.xml del ejemplo para definir el nombre de host. En el siguiente ejemplo, sustituye YOUR_PROJECT_ID por el ID de tu proyectoGoogle Cloud .

   En Linux o Mac OS:

   export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
   

   En Windows PowerShell:

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

2. Obtén nuevas credenciales de usuario para usarlas con las credenciales de aplicación predeterminadas:

   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, tal como indican los registros impresos por 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 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 la configuración de 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. Asegúrate de que estás en el directorio java-docs-samples/appengine-java8/endpoints-v2-backend

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

    mvn appengine:deploy
   

   La primera vez que subas una aplicación de ejemplo, es posible que se te pida que autorices la implementación. Sigue las indicaciones que se muestran. Cuando aparezca una ventana del navegador con un código, cópialo en la ventana de la terminal.

3. Espera a que finalice la subida.

   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

Una vez que hayas implementado la API y su archivo de configuración, podrás enviar solicitudes a la API.

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.

Acabas de desplegar y probar una API en Endpoints Frameworks.

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

Crear un portal para desarrolladores de la API

Puedes usar el portal de Cloud Endpoints para crear un portal para desarrolladores, un sitio web que puedes usar para interactuar con la API de ejemplo. Para obtener más información, consulta la descripción general del portal de Cloud Endpoints.