ファイル構造

gRPC API は、.proto ファイル内に proto3 IDL を使用して定義する必要があります。

ファイル構造では、より低レベルの重要度の低い項目の前に、より高レベルの重要度の高い定義を置く必要があります。各 proto ファイルでは、該当するセクションは次の順序にすることが推奨されます。

著作権とライセンス通知（必要な場合）。
Proto syntax、package、import、option 文をこの順序で配置します。
API の概要ドキュメント。ファイルの残りの部分について読者に説明します。
API proto service 定義。重要度の高い順序に配置します。
RPC リクエストとレスポンスの message 定義。対応するメソッドと同じ順序に配置します。各リクエストメッセージは、対応するレスポンスメッセージがある場合は、その前に置く必要があります。
リソース message 定義。親リソースは子リソースの前に定義する必要があります。

1 つの proto ファイルに API サーフェス全体が含まれている場合は、API の名前に基づく名前を付けることが推奨されます。

API	Proto
`Library`	`library.proto`
`Calendar`	`calendar.proto`

大きい .proto ファイルは複数のファイルに分割できます。サービス、リソースメッセージ、リクエスト / レスポンスメッセージは、必要に応じて別々のファイルに移動します。

サービスごとに、対応するリクエストとレスポンスを含む 1 つのファイルを作成することをおすすめします。このファイルには <enclosed service name>.proto という名前を付けることを検討してください。リソースのみを持つ proto ファイルの場合は、このファイルに resources.proto という名前を付けることを検討してください。

proto ファイル名

Proto ファイル名でには、小文字のアンダースコアを使用することが推奨され、拡張子には .proto を使用する必要があります。例: service_controller.proto。

proto オプション

さまざまな API 間で整合性のあるクライアントライブラリを生成するには、API デベロッパーは、.proto ファイルで整合性のある proto オプションを使用する必要があります。このガイドに準拠する API 定義では、次のファイルレベルの proto オプションを使用する必要があります。

syntax = "proto3";

// The package name should start with the company name and end with
// the major version.
package google.abc.xyz.v1;

// This option specifies the namespace to be used in C# code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a C#
// namespace of "Google.Shopping.Pets.V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a C# namespace of
// "Google.Shopping.Petstore.V1". Instead, the option should be used to
// capitalize it properly as "Google.Shopping.PetStore.V1".
//
// For more detail on C#/.NET capitalization rules, see the [Framework Design
// Guidelines](https://msdn.microsoft.com/en-us/library/ms229043).
//
// One corner-case of capitalization: while acronyms are generally
// PascalCased (e.g. Http), two-letter acronyms are normally all in capitals,
// e.g. `IOStream` and `OSVersion`, not `IoStream` and `OsVersion`. However,
// in APIs this should be used carefully, as protoc doesn't know which words
// are abbreviations and which aren't: it would introduce inconsistency to have
// a namespace of (say) `OSLogin` but then a class called `OsDetails` generated
// from a message of the same name. Unless you can be certain that the acronym
// won't crop up in a message or field name, it's safest to stick to regular
// PascalCase.
//
// For pre-releases, the Alpha/Beta should also be capitalized, so "V1Beta1"
// rather than "V1beta1" for example.
option csharp_namespace = "Google.Abc.Xyz.V1";

// This option specifies the Go package to be used in Go code. The package
// defined here depends mostly on how the organization manages their Go code.
//
// The example here uses a [Go remote import
// path](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) for branding and
// source control obfuscation reasons, and could be as direct as mirroring the
// protobuf `package` value in the Go module package, as is done here under
// `google.golang.org`.
//
// Read more about this option in the [Protobuf
// documentation](https://protobuf.dev/reference/go/go-generated/#package).
option go_package = "google.golang.org/google/abc/xyz/v1;xyz";

// This option lets the proto compiler generate Java code inside the package
// name (see below) instead of inside an outer class. It creates a simpler
// developer experience by reducing one-level of name nesting and be
// consistent with most programming languages that don't support outer classes.
option java_multiple_files = true;

// The Java outer classname should be the filename in UpperCamelCase. This
// class is only used to hold proto descriptor, so developers don't need to
// work with it directly.
option java_outer_classname = "XyzProto";

// The Java package name must be proto package name with proper prefix.
option java_package = "com.google.abc.xyz.v1";

// A reasonable prefix for the Objective-C symbols generated from the package.
// It should at a minimum be 3 characters long, all uppercase, and convention
// is to use an abbreviation of the package name. Something short, but
// hopefully unique enough to not conflict with things that may come along in
// the future. 'GPB' is reserved for the protocol buffer implementation itself.
option objc_class_prefix = "GABCX";

// This option specifies the namespace to be used in PHP code. This defaults
// to the PascalCased version of the proto package, which is fine if the
// package name consists of single-word segments.
// For example, a package name of "google.shopping.pets.v1" would use a PHP
// namespace of "Google\\Shopping\\Pets\\V1".
// However, if any segment of a package name consists of multiple words,
// this option needs to be specified to avoid only the first word being
// capitalized. For example, a Google Pet Store API might have a package name of
// "google.shopping.petstore.v1", which would mean a PHP namespace of
// "Google\\Shopping\\Petstore\\V1". Instead, the option should be used to
// capitalize it properly as "Google\\Shopping\\PetStore\\V1".
//
// For pre-releases, the Alpha/Beta should not be capitalized, so "V1beta1"
// rather than "V1Beta1" for example. Note that this is different from the
// capitalization used in the csharp_namespace option for pre-releases.
option php_namespace = "Google\\Abc\\Xyz\\V1";

ディレクトリ構造

用語集