En esta página, se describen los archivos de configuración necesarios para crear un servicio de gRPC administrado por Endpoints.
Requisitos previos
Como punto de partida, en esta página se supone que ya:
- Un proyecto de Google Cloud.
- Conocimientos básicos sobre cómo configurar un Servicio de API de gRPC.
- Instalación de gRPC y las herramientas de gRPC. Consulta la sección sobre cómo comenzar a usar gRPC para obtener más detalles.
Elige el nombre del servicio
Cloud Endpoints usa el nombre que creaste en el archivo YAML de la configuración de la API de gRPC como nombre de tu servicio.El nombre de tu servicio de API debe ser único en Google Cloud. Dado que Endpoints usa nombres compatibles con DNS para identificar los servicios, te recomendamos que uses el nombre de dominio o de subdominio de tu API como el nombre del servicio. Según este enfoque, el nombre del servicio que aparece en la página Endpoints Services coincide con el nombre que se usa en las solicitudes para tu API. Además, si el nombre de tu servicio y tu nombre de dominio son iguales, puedes crear un Portal de Cloud Endpoints para tus usuarios de API. Endpoints tiene los siguientes requisitos para el nombre del servicio:
- La longitud máxima del nombre de dominio es de 253 caracteres.
- El nombre de dominio debe comenzar con una letra minúscula.
- Cada sección del nombre de dominio, que está delimitada por puntos, tiene los requisitos siguientes:
- Debe comenzar con una letra en minúscula.
- No debe terminar con un guion.
- Los caracteres restantes pueden ser letras minúsculas, números o guiones.
- La longitud máxima es de 63 caracteres.
Puedes registrar tu propio dominio personalizado (como example.com
) o puedes usar un dominio administrado por Google.
Usa un dominio administrado por Google
Google es propietario y administra el dominiocloud.goog
. Si deseas usar un dominio administrado por Google, debes utilizar el ID de tu proyecto de Google Cloud como parte del nombre del servicio. Dado que los proyectos de Google Cloud tienen un ID del proyecto global único, este requisito garantiza que el nombre del servicio sea único.
Si quieres usar el dominio cloud.goog
, el nombre del servicio debe tener un formato en el que YOUR_API_NAME
es el nombre de tu API y YOUR_PROJECT_ID
es el ID de tu proyecto de Google Cloud:
YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`
Para usar este dominio como el nombre de dominio de la API, consulta Configurar DNS en el dominio cloud.goog
.
Usa un dominio personalizado
Si no quieres usar un dominio administrado por Google, puedes usar un dominio personalizado (por ejemplo, myapi.mycompany.com
) para el cual tengas autorización.
Antes de implementar la configuración de tu API, sigue los pasos que aparecen en Verificar la propiedad del dominio.
Configura el búfer de protocolo
Crea un archivo
.proto
para tu servicio. Consulta la Guía para desarrolladores
a fin de obtener más detalles.Compila tus búferes de protocolo con el compilador
protoc
para tu lenguaje. Por ejemplo:protoc --proto_path=. \ --include_imports \ --include_source_info \ --descriptor_set_out=api_descriptor.pb \ bookstore.proto
En el comando anterior,
--proto_path
está configurado en el directorio de trabajo actual. Si usas un directorio diferente para los archivos de entrada para.proto
en tu entorno de compilación de gRPC, cambia--proto_path
de modo que el compilador busque el directorio donde guardaste tu archivo.proto
.Si el comando
protoc
para generar tu archivo descriptor falla, asegúrate de que se cumplan las siguientes condiciones:- Tu versión de
protoc
está actualizada. - Especificaste
--proto_path
, o la forma corta-I
, para los directorios raíz de los archivos.proto
importados. Puedes obtener más información en la documentación sobre búferes de protocolo. - Especificaste
--include_imports
.
Si quieres que tus clientes puedan acceder a tu servicio de gRPC mediante HTTP con JSON, deberás especificar cómo se traducen los datos de HTTP con JSON a gRPC. Te recomendamos que anotes las API definidas en tu archivo
.proto
. Consulta la sección sobre cómo transcodificar HTTP/JSON a gRPC para obtener más información.- Tu versión de
Establece el archivo de configuración de servicio de gRPC
Debes crear un archivo YAML de configuración de servicio de gRPC. Especifica el nombre del servicio y las restricciones de uso, como requerir una clave de API en este archivo.
Puedes usar el archivo api_config.yaml
de la muestra de Bookstore como modelo.
Guarda una copia de
api_config.yaml
.Ingresa el nombre de tu servicio en el campo
name
. Por ejemplo:name: bookstore.endpoints.example-project-12345.cloud.goog
Ingresa el título que se muestra en la página Endpoints > Services en Google Cloud Console. Por ejemplo:
title: Bookstore gRPC API
Ingresa el nombre de la API en el campo
apis:name
. El texto que ingreses debe coincidir exactamente con el nombre de API completo de tu archivo.proto
. Por ejemplo:apis: - name: endpoints.examples.bookstore.Bookstore
Configura el resto del archivo. Por ejemplo:
# # API usage restrictions. # usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true
Consulta Reglas y selectores para obtener más información.
¿Qué sigue?
- Implementar la configuración de Endpoints
- Implementa el backend de la API
- Configura la autenticación
Muestras de gRPC adicionales
- Versión Java de la muestra de Bookstore.
La muestra de
getting-started-grpc
está disponible en GitHub en los siguientes lenguajes: