Implemente la configuración de Endpoints

OpenAPI | gRPC

Después de configurar Cloud Endpoints en un documento de OpenAPI, lo implementas a fin de que Endpoints tenga la información que necesita para administrar tu API. Para implementar la configuración de Endpoints, usas el comando de gcloud endpoints services deploy. Este comando emplea Service Infrastructure, la plataforma de servicios básica de Google, que usan Endpoints y otros servicios para crear y administrar API y servicios. En esta página, se describe cómo implementar un documento de OpenAPI en Endpoints.

Requisitos previos

Como punto de partida, en esta página se supone que ya:

Creaste un proyecto de Google Cloud en el que tienes la función Editor o Propietario. Después de la implementación inicial, puedes otorgar la función más restringida Editor de configuración de servicio a un usuario, grupo o cuenta de servicio. Consulta Otorgar y revocar el acceso a la API para obtener más información.
Configuraste Endpoints.
Si usas un nombre de dominio personalizado (como my-api.example.com), debes verificar el nombre de dominio antes de poder implementar el documento de OpenAPI.

Prepara Google Cloud CLI para la implementación

Usas la herramienta de línea de comandos de gcloud para implementar la configuración. Consulta la referencia de gcloud para obtener más información sobre los comandos.

Prepárate para la implementación de la siguiente manera:

Instala e inicializa gcloud CLI.
Actualiza la CLI de gcloud:
```
gcloud components update
```
Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y servicios:
```
gcloud auth login
```
Se abrirá una pestaña nueva del navegador y se te solicitará que elijas una cuenta.
Configura el proyecto predeterminado. Reemplaza [YOUR-PROJECT-ID] por el ID del proyecto de GCP.
```
gcloud config set project [YOUR-PROJECT-ID]
```
Si deseas implementar el backend de tu API en Kubernetes o Kubernetes Engine, ejecuta el comando siguiente para adquirir credenciales de usuario nuevas y usarlas como las credenciales predeterminadas de la aplicación. Para la autorización de kubectl, se necesitan las credenciales de usuario.
```
gcloud auth application-default login
```
Se abrirá una pestaña nueva del navegador y se te solicitará que elijas una cuenta.

Valida la sintaxis de `openapi.json`

El archivo del documento de OpenAPI puede estar en formato YAML o JSON. Si está en formato JSON, te recomendamos verificar la sintaxis antes de implementar el archivo. Para comprobar si tu openapi.json es un archivo JSON con el formato correcto, puedes abrirlo en un editor de texto que valide JSON, como vim, usar un servicio de linter de JSON en línea o Python, por ejemplo:

python -m json.tool openapi.json

Para mejorar la legibilidad del archivo JSON, puedes imprimirlo de la manera siguiente:

python -m json.tool input.json > output.json

Reemplaza input.json por la ruta de acceso a tu archivo openapi.json. output.json es el archivo JSON con impresión con formato.

Valida tu documento de OpenAPI

No todas las construcciones de OpenAPI son compatibles con Cloud Endpoints actualmente. Antes de implementar, puedes validar tu documento de OpenAPI.

Para validar tu documento de OpenAPI, sigue estos pasos:

Cambia el directorio a la ubicación que contiene el documento de OpenAPI.
Confirma el proyecto de Google Cloud en el que deseas crear el servicio. Si usas un nombre de dominio personalizado (como myapi.example.com), asegúrate de validar el ID del proyecto que muestra el siguiente comando para que el servicio no se cree en el proyecto incorrecto.
```
gcloud config list project
```
Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y reemplaza [YOUR_PROJECT_ID] por el ID del proyecto de Google Cloud en el que quieres crear el servicio:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Ejecuta el siguiente comando y reemplaza [YOUR_OPENAPI_DOCUMENT] por el nombre del documento de OpenAPI que describe tu API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

El comando de gcloud llama a la API de Service Management para crear un servicio administrado con el nombre que especificaste en el campo host en tu documento de OpenAPI. Cuando especificas la marca --validate-only, se crea un servicio, pero la configuración no se implementa. No existe una forma de validar tu documento de OpenAPI sin crear un servicio. Si bien puedes borrar el servicio, Administración de servicio te impide crear un servicio con el mismo nombre por un período de 30 días aproximadamente.

Implementa el documento de OpenAPI

Cuando estés listo para implementar tu API, ejecuta Google Cloud CLI, que usa Service Management para subir la configuración de tu API y crear (o actualizar) un servicio administrado.

Para implementar tu documento de OpenAPI, sigue estos pasos:

Cambia el directorio a la ubicación que contiene el documento de OpenAPI.
Valida el ID del proyecto que muestra el siguiente comando para asegurarte de que el servicio no se cree en el proyecto equivocado.
```
gcloud config list project
```
Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y reemplaza [YOUR_PROJECT_ID] por el ID del proyecto de Google Cloud en el que quieres crear el servicio:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Ejecuta el siguiente comando y reemplaza [YOUR_OPENAPI_DOCUMENT] por el nombre del documento de OpenAPI que describe tu API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

La primera vez que ejecutas el comando anterior, Service Management crea un nuevo servicio de Endpoints en el proyecto predeterminado con un nombre que coincide con el texto que especificaste en el campo host en tu documento de OpenAPI y, además, sube la configuración del servicio.

Mientras se crea y configura el servicio, Administración de servicio exporta la información a la terminal. Cuando el proceso finalice con éxito, verás una línea como la siguiente, que indica el ID de configuración y el nombre del servicio:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el nombre del servicio.

Después de una implementación exitosa, puedes ver la API en la página Endpoints > Servicios de la consola de Google Cloud.

Si recibes un mensaje de error, consulta Solucionar problemas en la implementación de la configuración de Endpoints.

Volver a implementar

Cuando quieras cambiar algo en tu documento de OpenAPI, asegúrate de volver a implementarlo para que Endpoints tenga la versión más reciente de la configuración de servicio de la API. No es necesario volver a implementar o reiniciar el ESP si ya implementaste el ESP con la opción rollout configurada como managed. Esta opción configura el ESP de modo que use la última configuración del servicio implementada. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración determinado para que lo utilice el ESP.

Después de la implementación inicial de la configuración de Endpoints, puedes otorgar a un usuario, una cuenta de servicio o un grupo una función que les permita volver a implementar la configuración de Endpoints. Consulta Cómo otorgar y revocar el acceso a la API para obtener más información.