This page describes the configuration files needed to create a gRPC service that is managed by Endpoints.
Prerequisites
As a starting point, this page assumes that you have:
- A Google Cloud project.
- Basic knowledge of configuring a gRPC API service.
- Installed gRPC and the gRPC tools. Read Get started with gRPC for details.
Choosing the service name
Cloud Endpoints uses the name you configure in your gRPC API configuration YAML file as the name of your service.The name of your API service must be unique on Google Cloud. Because Endpoints uses DNS-compatible names to identify services, we recommend that you use your API's domain name or subdomain name as the service name. With this approach, the service name that appears on the Endpoints Services page matches the name used in requests to your API. Additionally, if your service name and domain name are the same, you can create a Cloud Endpoints Portal for your API users. Endpoints has the following requirements for the service name:
- The maximum length of the domain name is 253 characters.
- The domain name must start with a lowercase letter.
-
Each section in the domain name, which is delimited by dots, has the following
requirements:
- Must start with a lowercase letter.
- Must not end with a dash.
- The remaining characters can be lowercase letters, numbers, or dashes.
- The maximum length is 63 characters.
You can either register your own custom domain (such as example.com
), or
you can use a domain managed by Google.
Use a domain managed by Google
Google owns and manages thecloud.goog
domain. If you want to use a domain
managed by Google, you must use your Google Cloud project ID as part of
the service name. Because Google Cloud projects have a globally
unique project ID, this requirement ensures that you have a unique service name.
If you want to use the cloud.goog
domain, the service name must be
in the format, where YOUR_API_NAME
is the name of your
API and YOUR_PROJECT_ID
is your
Google Cloud project ID:
YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`
To use this domain as the API's domain name, read
Configuring DNS on the cloud.goog
domain.
Use a custom domain
If you don't want to use a domain managed by Google, you can use a custom domain
(for example, myapi.mycompany.com
) that you are authorized to use.
Before you deploy the API configuration, follow the steps in
Verify ownership of the domain.
Configuring the protocol buffer
Create a
.proto
file for your service. Read the Developer guide
for details.Compile your protocol buffers by using the
protoc
compiler for your language. For example:protoc --proto_path=. \ --include_imports \ --include_source_info \ --descriptor_set_out=api_descriptor.pb \ bookstore.proto
In the preceding command,
--proto_path
is set to the current working directory. In your gRPC build environment, if you use a different directory for.proto
input files, change--proto_path
so the compiler searches the directory where you saved your.proto
file.If the
protoc
command to generate your descriptor file fails, make sure that:- Your
protoc
version is up-to-date. - You specified the
--proto_path
or its short form-I
for the root directories for imported.proto
files. You can find out more in the protocol buffers documentation. - You specified
--include_imports
.
If you want your clients to access your gRPC service by using HTTP with JSON, you need to specify how data is translated from HTTP with JSON to gRPC. We recommend that you annotate the APIs defined in your
.proto
file. Read Transcoding HTTP/JSON to gRPC for more information.- Your
Configuring the gRPC service configuration file
You need to create a gRPC service configuration YAML file. You specify the name
of the service and usage restrictions, such as requiring an API key in this file.
You can use the api_config.yaml
file from the Bookstore sample as a model.
Save a copy of
api_config.yaml
.Enter the name of your service in the
name
field. For example:name: bookstore.endpoints.example-project-12345.cloud.goog
Enter the title that is displayed on the Endpoints > Services page in the Google Cloud console. For example:
title: Bookstore gRPC API
Enter the API name in the
apis:name
field. The text that you enter must exactly match the fully-qualified API name from your.proto
file. For example:apis: - name: endpoints.examples.bookstore.Bookstore
Configure the rest of the file. For example:
# # API usage restrictions. # usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true
Read Rules and selectors for more information.
What's next
Additional gRPC samples
- Java version of the Bookstore sample.
The
getting-started-grpc
sample is available on GitHub in the following languages: