言語ガイド (proto 3)

プロジェクトで Protocol Buffers 言語の proto3 リビジョンを使用する方法を説明します。

このガイドでは、プロトコルバッファ言語を使用してプロトコルバッファデータを構造化する方法について説明します。これには、.proto ファイル構文と、.proto ファイルからデータアクセスクラスを生成する方法が含まれます。プロトコルバッファ言語の proto3 リビジョンを対象としています。

エディション構文については、Protobuf Editions 言語ガイドを参照してください。

proto2 構文については、Proto2 言語ガイドを参照してください。

これはリファレンスガイドです。このドキュメントで説明されている多くの機能を使用したステップバイステップの例については、選択した言語のチュートリアルを参照してください。

メッセージ型の定義

まず、非常に簡単な例を見てみましょう。検索リクエストメッセージ形式を定義したいとします。各検索リクエストには、クエリ文字列、興味のある結果の特定のページ、およびページあたりの結果数が含まれています。これが、メッセージ型を定義するために使用する .proto ファイルです。

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
}

ファイルの最初の行は、protobuf 言語仕様の proto3 リビジョンを使用していることを指定します。
- edition (または proto2/proto3 の syntax) は、ファイルの最初の空でない、コメントではない行でなければなりません。
- edition または syntax が指定されていない場合、プロトコルバッファコンパイラは proto2 を使用していると仮定します。
SearchRequestメッセージ定義は、3つのフィールド（名前/値のペア）を指定しています。これらは、このタイプのメッセージに含めたい各データに対応しています。各フィールドには名前と型があります。

フィールド型の指定

前の例では、すべてのフィールドがスカラー型です。2つの整数 (page_number と results_per_page) と文字列 (query) です。フィールドには、列挙型や、他のメッセージ型のような複合型も指定できます。

フィールド番号の割り当て

メッセージ定義の各フィールドには、1から536,870,911までの番号を、以下の制限付きで与える必要があります。

指定された番号は、そのメッセージのすべてのフィールドの中で一意でなければなりません。
フィールド番号19,000から19,999は、Protocol Buffersの実装のために予約されています。メッセージでこれらの予約済みフィールド番号を使用すると、プロトコルバッファコンパイラは文句を言います。
以前に予約されたフィールド番号や、拡張機能に割り当てられたフィールド番号は使用できません。

この番号は、メッセージのメッセージワイヤ形式でフィールドを識別するため、メッセージ型が使用されている場合は変更できません。「フィールド番号の変更」は、そのフィールドを削除し、同じ型で新しい番号を持つ新しいフィールドを作成することと同じです。これを適切に行う方法については、フィールドの削除を参照してください。

フィールド番号は決して再利用すべきではありません。予約済みリストからフィールド番号を取り出して、新しいフィールド定義で再利用しないでください。フィールド番号の再利用による影響を参照してください。

最も頻繁に設定されるフィールドには、フィールド番号1から15を使用してください。フィールド番号の値が小さいほど、ワイヤ形式でのスペースが少なくなります。たとえば、フィールド番号1から15の範囲は、エンコードに1バイトかかります。フィールド番号16から2047の範囲は2バイトかかります。これについては、プロトコルバッファエンコーディングで詳しく説明されています。

フィールド番号の再利用による影響

フィールド番号を再利用すると、ワイヤーフォーマットメッセージのデコードが曖昧になります。

Protobufのワイヤーフォーマットは無駄がなく、ある定義でエンコードされたフィールドを別の定義でデコードしたことを検出する方法を提供していません。

ある定義を使用してフィールドをエンコードし、その後、その同じフィールドを別の定義でデコードすると、以下のような事態につながる可能性があります。

デバッグに費やされる開発者の時間
パース/マージエラー（最良のシナリオ）
個人情報/機密情報の漏洩
データの破損

フィールド番号の再利用の一般的な原因

フィールドの番号変更（見た目の美しい番号順にするために行われることがあります）。番号変更は、事実上、番号変更に関わるすべてのフィールドを削除して再追加することになり、互換性のないワイヤーフォーマットの変更をもたらします。
フィールドを削除し、将来の再利用を防ぐために番号を予約しないこと。

フィールド番号は32ビットではなく29ビットに制限されています。これは、3ビットがフィールドのワイヤーフォーマットを指定するために使用されるためです。詳細については、エンコーディングのトピックを参照してください。

フィールドカーディナリティの指定

メッセージフィールドは、次のいずれかになります。

単数形:
proto3 には、2種類の単数フィールドがあります。
- optional: (推奨) optional フィールドは、2つの可能な状態のいずれかになります。
  - フィールドが設定されており、明示的に設定されたか、ワイヤーから解析された値が含まれています。ワイヤーにシリアライズされます。
  - フィールドが設定されておらず、デフォルト値を返します。ワイヤーにシリアライズされません。
  値が明示的に設定されたかどうかを確認できます。
  optional は、protobuf エディションおよび proto2 との互換性を最大限に高めるために、暗黙的フィールドよりも推奨されます。
- 暗黙的: (非推奨) 暗黙的フィールドには明示的なカーディナリティラベルがなく、次のように動作します。
  - フィールドがメッセージ型の場合、optional フィールドとまったく同じように動作します。
  - フィールドがメッセージではない場合、2つの状態があります。
    - フィールドは、明示的に設定された、またはワイヤから解析された非デフォルト (非ゼロ) の値に設定されています。これはワイヤにシリアル化されます。
    - フィールドはデフォルト (ゼロ) の値に設定されています。これはワイヤにシリアル化されません。実際、デフォルト (ゼロ) の値が設定されたのか、ワイヤから解析されたのか、まったく提供されなかったのかを判断することはできません。この主題の詳細については、フィールドの存在を参照してください。
repeated: このフィールド型は、整形式のメッセージ内で0回以上繰り返すことができます。繰り返された値の順序は保持されます。
map: これはキーと値のペアのフィールド型です。このフィールド型の詳細については、マップを参照してください。

繰り返しフィールドはデフォルトでパックされます

proto3 では、スカラー数値型の repeated フィールドはデフォルトで packed エンコーディングを使用します。

`packed`エンコーディングについての詳細は、Protocol Bufferエンコーディングで確認できます。

メッセージ型フィールドは常にフィールドの存在を持ちます

proto3 では、メッセージ型フィールドはすでにフィールドの存在を持っています。このため、optional 修飾子を追加しても、そのフィールドのフィールドの存在は変わりません。

以下のコードサンプルにおける Message2 と Message3 の定義は、すべての言語で同じコードを生成し、バイナリ、JSON、および TextFormat での表現に違いはありません。

syntax="proto3";

package foo.bar;

message Message1 {}

message Message2 {
  Message1 foo = 1;
}

message Message3 {
  optional Message1 bar = 1;
}

整形式メッセージ

「整形式」という用語は、protobufメッセージに適用される場合、シリアライズ/デシリアライズされたバイトを指します。protocパーサーは、与えられたproto定義ファイルが解析可能であることを検証します。

単数フィールドは、ワイヤ形式のバイトに複数回出現する可能性があります。パーサーは入力を受け入れますが、生成されたバインディングを通じてアクセスできるのは、そのフィールドの最後のインスタンスのみです。このトピックの詳細については、最後のものが優先されるを参照してください。

メッセージ型の追加

1つの .proto ファイルに複数のメッセージ型を定義できます。これは、複数の関連するメッセージを定義する場合に便利です。たとえば、SearchResponse メッセージ型に対応する返信メッセージ形式を定義したい場合、同じ .proto に追加できます。

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
}

message SearchResponse {
 ...
}

メッセージの結合は肥大化につながる 複数のメッセージ型 (メッセージ、enum、サービスなど) を1つの .proto ファイルで定義できますが、依存関係の異なる多数のメッセージが1つのファイルで定義されている場合、依存関係の肥大化につながる可能性もあります。.proto ファイルあたりのメッセージ型をできるだけ少なくすることをお勧めします。

コメントの追加

`.proto`ファイルにコメントを追加するには：

.protoコード要素の前の行に、C/C++/Javaの行末スタイルコメント「//」を使用することを推奨します。
Cスタイルのインライン/複数行コメント `/* ... */` も受け入れられます。
- 複数行コメントを使用する場合、マージン行として「*」を使用することが推奨されます。

/**
 * SearchRequest represents a search query, with pagination options to
 * indicate which results to include in the response.
 */
message SearchRequest {
  string query = 1;

  // Which page number do we want?
  int32 page_number = 2;

  // Number of results to return per page.
  int32 results_per_page = 3;
}

フィールドの削除

フィールドを削除することは、適切に行われないと深刻な問題を引き起こす可能性があります。

フィールドが不要になり、クライアントコードからすべての参照が削除された場合、メッセージからフィールド定義を削除できます。ただし、削除されたフィールド番号を予約する必要があります。フィールド番号を予約しないと、将来、開発者がその番号を再利用する可能性があります。

また、メッセージのJSONおよびTextFormatエンコーディングが引き続き解析できるように、フィールド名を予約する必要もあります。

予約済みフィールド番号

フィールドを完全に削除するか、コメントアウトすることでメッセージ型を更新した場合、将来の開発者は、その型に対して独自の更新を行う際に、フィールド番号を再利用する可能性があります。これは、フィールド番号の再利用の影響で説明されているように、重大な問題を引き起こす可能性があります。これを防ぐために、削除されたフィールド番号を reserved リストに追加してください。

将来の開発者がこれらの予約済みフィールド番号を使用しようとすると、protocコンパイラはエラーメッセージを生成します。

message Foo {
  reserved 2, 15, 9 to 11;
}

予約済みフィールド番号の範囲は包括的です（`9 to 11`は`9, 10, 11`と同じです）。

予約済みのフィールド名

古いフィールド名を後で再利用することは一般的に安全ですが、TextProtoやJSONエンコーディングを使用している場合、フィールド名がシリアライズされるため例外です。このリスクを避けるために、削除したフィールド名を`reserved`リストに追加することができます。

予約名は、protoc コンパイラの動作のみに影響し、実行時の動作には影響しません。ただし、1つの例外があります。TextProto の実装では、解析時に予約名を持つ未知のフィールドを (他の未知のフィールドのようにエラーを発生させることなく) 破棄する場合があります (現在、C++ と Go の実装のみがこれを行います)。実行時の JSON 解析は予約名の影響を受けません。

message Foo {
  reserved 2, 15, 9 to 11;
  reserved "foo", "bar";
}

同じ`reserved`文にフィールド名とフィールド番号を混在させることはできないことに注意してください。

`.proto`から何が生成されるか

.proto ファイルに対してプロトコルバッファコンパイラを実行すると、コンパイラは、ファイルで記述したメッセージ型を操作するために必要な選択した言語のコードを生成します。これには、フィールド値の取得と設定、メッセージの出力ストリームへのシリアル化、入力ストリームからのメッセージの解析が含まれます。

C++の場合、コンパイラは各`.proto`から`.h`と`.cc`ファイルを生成し、ファイルで記述された各メッセージ型に対応するクラスを作成します。
Javaの場合、コンパイラは各メッセージ型に対応するクラスを含む`.java`ファイルを生成します。また、メッセージクラスのインスタンスを作成するための特別な`Builder`クラスも生成します。
Kotlinの場合、Javaの生成コードに加えて、コンパイラは各メッセージタイプに対して、改善されたKotlin APIを持つ.ktファイルを生成します。これには、メッセージインスタンスの作成を簡素化するDSL、NULL許容フィールドアクセサ、およびコピー関数が含まれます。
Pythonは少し異なり、Pythonコンパイラは、.protoファイルの各メッセージ型の静的な記述子を持つモジュールを生成します。これは、実行時に必要なPythonデータアクセスクラスを作成するためにメタクラスとともに使用されます。
Goの場合、コンパイラは`.pb.go`ファイルを生成し、そのファイル内の各メッセージ型に対応する型を作成します。
Rubyの場合、コンパイラはメッセージ型を含むRubyモジュールを持つ`.rb`ファイルを生成します。
Objective-Cの場合、コンパイラは各`.proto`から`pbobjc.h`と`pbobjc.m`ファイルを生成し、ファイルで記述された各メッセージ型に対応するクラスを作成します。
C#の場合、コンパイラは各`.proto`から`.cs`ファイルを生成し、ファイルに記述された各メッセージ型に対応するクラスを作成します。
PHPの場合、コンパイラは、ファイルに記述された各メッセージ型に対して.phpメッセージファイルを生成し、コンパイルする各.protoファイルに対して.phpメタデータファイルを生成します。メタデータファイルは、有効なメッセージ型を記述子プールにロードするために使用されます。
Dartの場合、コンパイラはファイル内の各メッセージタイプに対応するクラスを持つ`.pb.dart`ファイルを生成します。

各言語のAPIの使用方法についての詳細は、選択した言語のチュートリアルを参考にしてください。さらに詳細なAPI情報については、関連するAPIリファレンスを参照してください。

スカラー値型

スカラーメッセージフィールドは以下のいずれかの型を持つことができます。表は`.proto`ファイルで指定された型と、自動生成されるクラスでの対応する型を示しています。

Proto 型	注釈
double	IEEE 754 倍精度形式を使用します。
float	IEEE 754 単精度形式を使用します。
int32	可変長エンコーディングを使用します。負の数のエンコードには非効率です。フィールドが負の値を持つ可能性が高い場合は、代わりにsint32を使用してください。
int64	可変長エンコーディングを使用します。負の数のエンコードには非効率です。フィールドが負の値を持つ可能性が高い場合は、代わりにsint64を使用してください。
uint32	可変長エンコーディングを使用します。
uint64	可変長エンコーディングを使用します。
sint32	可変長エンコーディングを使用します。符号付き整数値。これらは通常のint32よりも効率的に負の数をエンコードします。
sint64	可変長エンコーディングを使用します。符号付き整数値。これらは通常のint64よりも効率的に負の数をエンコードします。
fixed32	常に4バイト。値が2²⁸より大きいことが多い場合、uint32より効率的です。
fixed64	常に8バイト。値が2⁵⁶より大きいことが多い場合、uint64より効率的です。
sfixed32	常に4バイト。
sfixed64	常に8バイト。
bool
string	文字列は常にUTF-8エンコードまたは7ビットASCIIテキストを含んでいる必要があり、2³²より長くすることはできません。
bytes	2³²以下の任意のバイトシーケンスを含むことができます。

Proto 型	C++ 型	Java/Kotlin 型^[1]	Python 型^[3]	Go 型	Ruby 型	C# 型	PHP 型	Dart 型	Rust 型
double	double	double	float	float64	Float	double	float	double	f64
float	float	float	float	float32	Float	float	float	double	f32
int32	int32_t	int	int	int32	Fixnum または Bignum (必要に応じて)	int	integer	int	i32
int64	int64_t	long	int/long^[4]	int64	Bignum	long	integer/string^[6]	Int64	i64
uint32	uint32_t	int^[2]	int/long^[4]	uint32	Fixnum または Bignum (必要に応じて)	uint	integer	int	u32
uint64	uint64_t	long^[2]	int/long^[4]	uint64	Bignum	ulong	integer/string^[6]	Int64	u64
sint32	int32_t	int	int	int32	Fixnum または Bignum (必要に応じて)	int	integer	int	i32
sint64	int64_t	long	int/long^[4]	int64	Bignum	long	integer/string^[6]	Int64	i64
fixed32	uint32_t	int^[2]	int/long^[4]	uint32	Fixnum または Bignum (必要に応じて)	uint	integer	int	u32
fixed64	uint64_t	long^[2]	int/long^[4]	uint64	Bignum	ulong	integer/string^[6]	Int64	u64
sfixed32	int32_t	int	int	int32	Fixnum または Bignum (必要に応じて)	int	integer	int	i32
sfixed64	int64_t	long	int/long^[4]	int64	Bignum	long	integer/string^[6]	Int64	i64
bool	bool	boolean	bool	bool	TrueClass/FalseClass	bool	boolean	bool	bool
string	std::string	String	str/unicode^[5]	string	String (UTF-8)	string	string	String	ProtoString
bytes	std::string	ByteString	str (Python 2), bytes (Python 3)	[]byte	String (ASCII-8BIT)	ByteString	string	リスト	ProtoBytes

^[1] Kotlinは、Java/Kotlin混合コードベースでの互換性を確保するため、符号なし型であってもJavaの対応する型を使用します。

^[2] Javaでは、符号なし32ビットおよび64ビット整数は、符号付きの対応物を使用して表現され、最上位ビットは単に符号ビットに格納されます。

^[3] すべての場合において、フィールドに値を設定する際には、それが有効であることを確認するための型チェックが実行されます。

^[4] 64ビットまたは符号なし32ビット整数は、デコード時には常にlongとして表現されますが、フィールドを設定する際にintが与えられた場合はintになることがあります。すべての場合において、設定される値は表現される型に収まる必要があります。[2]を参照してください。

^[5] Pythonの文字列はデコード時にはユニコードとして表現されますが、ASCII文字列が与えられた場合はstrになることがあります（これは変更される可能性があります）。

^[6] 64ビットマシンではIntegerが使用され、32ビットマシンではstringが使用されます。

メッセージをシリアライズする際にこれらの型がどのようにエンコードされるかについての詳細は、Protocol Bufferエンコーディングで確認できます。

フィールドのデフォルト値

メッセージがパースされる際、エンコードされたメッセージバイトに特定のフィールドが含まれていない場合、パースされたオブジェクトでそのフィールドにアクセスすると、そのフィールドのデフォルト値が返されます。デフォルト値は型によって異なります。

文字列の場合、デフォルト値は空文字列です。
bytesの場合、デフォルト値は空のバイト列です。
boolの場合、デフォルト値はfalseです。
数値型の場合、デフォルト値はゼロです。
メッセージフィールドの場合、フィールドは設定されません。その正確な値は言語に依存します。詳細は生成コードガイドを参照してください。
Enum の場合、デフォルト値は最初に定義された enum 値であり、0でなければなりません。 Enum のデフォルト値を参照してください。

repeatedフィールドのデフォルト値は空です（通常、適切な言語での空のリスト）。

マップフィールドのデフォルト値は空です（通常、適切な言語での空のマップ）。

暗黙的プレゼンススカラーフィールドの場合、メッセージが解析された後、そのフィールドが明示的にデフォルト値に設定されたのか (たとえば、ブール値が false に設定されたのか)、まったく設定されなかったのかを区別する方法はありません。メッセージ型を定義するときは、この点を考慮する必要があります。たとえば、false に設定されたときに何らかの動作をオンにするブール値がある場合、その動作がデフォルトでも発生してほしくない場合は、そうしないでください。また、スカラーメッセージフィールドがデフォルトに設定されている場合、その値はワイヤーでシリアル化されないことにも注意してください。float または double の値が +0 に設定されている場合、それはシリアル化されませんが、-0 は区別され、シリアル化されます。

生成されたコードにおけるデフォルト値の動作に関する詳細は、選択した言語の生成コードガイドを参照してください。

列挙型

メッセージ型を定義するとき、フィールドの1つが事前定義された値のリストのいずれかしか持たないようにしたい場合があります。たとえば、各 SearchRequest に corpus フィールドを追加したいとします。ここで、corpus は UNIVERSAL、WEB、IMAGES、LOCAL、NEWS、PRODUCTS、または VIDEO のいずれかです。これは、各可能な値の定数を持つ enum をメッセージ定義に追加することで非常に簡単に行うことができます。

以下の例では、すべての可能な値を持つ`Corpus`という`enum`と、`Corpus`型のフィールドを追加しました。

enum Corpus {
  CORPUS_UNSPECIFIED = 0;
  CORPUS_UNIVERSAL = 1;
  CORPUS_WEB = 2;
  CORPUS_IMAGES = 3;
  CORPUS_LOCAL = 4;
  CORPUS_NEWS = 5;
  CORPUS_PRODUCTS = 6;
  CORPUS_VIDEO = 7;
}

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
  Corpus corpus = 4;
}

列挙型のデフォルト値

`SearchRequest.corpus`フィールドのデフォルト値は`CORPUS_UNSPECIFIED`です。なぜなら、それがenumで定義された最初の値だからです。

proto3では、enum定義で最初に定義された値は**必ず**ゼロの値を持ち、ENUM_TYPE_NAME_UNSPECIFIEDまたはENUM_TYPE_NAME_UNKNOWNという名前を持つ必要があります。これは、以下の理由によります。

ゼロ値が必要なのは、0を数値のデフォルト値として使用できるようにするためです。
ゼロ値は、proto2のセマンティクスとの互換性のために最初の要素である必要があります。proto2では、異なる値が明示的に指定されない限り、最初のenum値がデフォルトです。

また、この最初のデフォルト値は、「この値は指定されなかった」以外の意味を持たないことが推奨されます。

列挙値のエイリアス

異なるenum定数に同じ値を割り当てることで、エイリアスを定義できます。これを行うには、allow_aliasオプションをtrueに設定する必要があります。そうしないと、プロトコルバッファコンパイラはエイリアスが見つかったときに警告メッセージを生成します。すべてのエイリアス値はシリアル化に対して有効ですが、デシリアル化時には最初の値のみが使用されます。

enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2;
}

enum EnumNotAllowingAlias {
  ENAA_UNSPECIFIED = 0;
  ENAA_STARTED = 1;
  // ENAA_RUNNING = 1;  // Uncommenting this line will cause a warning message.
  ENAA_FINISHED = 2;
}

列挙子定数は32ビット整数の範囲内になければなりません。enum値はワイヤ上でvarintエンコーディングを使用するため、負の値は非効率的であり、推奨されません。前述の例のように、メッセージ定義内でenumを定義することも、外で定義することもできます。これらのenumは、.protoファイル内の任意のメッセージ定義で再利用できます。また、_MessageType_._EnumType_という構文を使用して、あるメッセージで宣言されたenum型を別のメッセージのフィールドの型として使用することもできます。

enumを使用する.protoに対してプロトコルバッファコンパイラを実行すると、生成されたコードには、Java、Kotlin、またはC++の場合に対応するenumが、Pythonの場合には実行時に生成されるクラス内で整数値を持つ記号定数のセットを作成するために使用される特殊なEnumDescriptorクラスが生成されます。

重要

生成されたコードは、列挙子の数に関する言語固有の制限（ある言語では数千程度）の対象となる場合があります。使用を計画している言語の制限を確認してください。

デシリアライズ中、認識されない enum 値はメッセージに保存されますが、メッセージがデシリアライズされたときにこれがどのように表現されるかは言語に依存します。C++やGoのように、指定されたシンボルの範囲外の値を持つオープン enum 型をサポートする言語では、不明な enum 値は基になる整数表現として単純に格納されます。Javaのように閉じた enum 型を持つ言語では、enum のケースが認識されない値を表現するために使用され、基になる整数は特別なアクセサーでアクセスできます。どちらの場合でも、メッセージがシリアライズされた場合、認識されない値はメッセージと一緒にシリアライズされます。

重要

enumがどのように動作すべきかと、異なる言語で現在どのように動作するかの対比については、Enumの動作を参照してください。

アプリケーションでメッセージの`enum`を扱う方法についての詳細は、選択した言語の生成コードガイドを参照してください。

予約値

enum エントリを完全に削除したり、コメントアウトしたりして enum 型を更新すると、将来のユーザーは、その型に対して独自の更新を行うときに数値値を再利用する可能性があります。これは、同じ .proto の古いインスタンスを後でロードした場合に、データの破損、プライバシーバグなど、重大な問題を引き起こす可能性があります。これを防ぐ1つの方法は、削除されたエントリの数値 (および/または名前。これは JSON シリアル化でも問題を引き起こす可能性があります) を reserved として指定することです。プロトコルバッファコンパイラは、将来のユーザーがこれらの識別子を使用しようとすると文句を言います。max キーワードを使用して、予約された数値範囲が最大可能値までであることを指定できます。

enum Foo {
  reserved 2, 15, 9 to 11, 40 to max;
  reserved "FOO", "BAR";
}

同じ`reserved`文にフィールド名と数値を混在させることはできません。

他のメッセージ型の使用

他のメッセージ型をフィールド型として使用できます。たとえば、各 SearchResponse メッセージに Result メッセージを含めたい場合、同じ .proto で Result メッセージ型を定義し、SearchResponse で Result 型のフィールドを指定できます。

message SearchResponse {
  repeated Result results = 1;
}

message Result {
  string url = 1;
  string title = 2;
  repeated string snippets = 3;
}

定義のインポート

先の例では、`Result`メッセージ型は`SearchResponse`と同じファイルで定義されています。フィールド型として使用したいメッセージ型が既に別の`.proto`ファイルで定義されている場合はどうなるでしょうか。

他の`.proto`ファイルからの定義を*インポート*することで使用できます。別の`.proto`の定義をインポートするには、ファイルの先頭にimport文を追加します。

import "myproject/other_protos.proto";

デフォルトでは、直接インポートされた .proto ファイルの定義のみを使用できます。ただし、.proto ファイルを新しい場所に移動する必要がある場合があります。.proto ファイルを直接移動してすべての呼び出しサイトを1回の変更で更新する代わりに、古い場所にプレースホルダーの .proto ファイルを配置して、import public の概念を使用してすべてのインポートを新しい場所に転送できます。

注: Javaで利用できる公開インポート機能は、.protoファイル全体を移動する場合や、java_multiple_files = trueを使用する場合に最も効果的です。これらの場合、生成された名前は安定したままであり、コード内の参照を更新する必要がありません。java_multiple_files = trueを使用せずに.protoファイルの一部を移動する場合でも技術的には機能しますが、その場合、多くの参照を同時に更新する必要があるため、移行が大幅に容易になるわけではありません。この機能は、Kotlin、TypeScript、JavaScript、GCL、またはprotobuf静的リフレクションを使用するC++ターゲットでは利用できません。

`import public`の依存関係は、`import public`文を含むプロトをインポートする任意のコードによって推移的に依存される可能性があります。例えば：

// new.proto
// All definitions are moved here

// old.proto
// This is the proto that all clients are importing.
import public "new.proto";
import "other.proto";

// client.proto
import "old.proto";
// You use definitions from old.proto and new.proto, but not other.proto

プロトコルコンパイラは、-I/--proto_path フラグを使用してプロトコルコンパイラコマンドラインで指定されたディレクトリセット内でインポートされたファイルを探します。フラグが指定されていない場合、コンパイラが呼び出されたディレクトリを探します。一般に、--proto_path フラグをプロジェクトのルートに設定し、すべてのインポートに完全修飾名を使用する必要があります。

proto2 メッセージ型の使用

proto2メッセージ型をインポートしてproto3メッセージで使用することも、その逆も可能です。ただし、proto2 enumはproto3構文で直接使用することはできません（インポートされたproto2メッセージがそれらを使用している場合は問題ありません）。

ネストされた型

次の例のように、他のメッセージタイプの内部でメッセージタイプを定義し、使用することができます。ここでは、`Result`メッセージが`SearchResponse`メッセージの内部で定義されています。

message SearchResponse {
  message Result {
    string url = 1;
    string title = 2;
    repeated string snippets = 3;
  }
  repeated Result results = 1;
}

このメッセージ型を親メッセージ型の外部で再利用したい場合は、`_Parent_._Type_`として参照します。

message SomeOtherMessage {
  SearchResponse.Result result = 1;
}

メッセージは好きなだけ深くネストできます。以下の例では、`Inner`という名前の2つのネストされた型は、異なるメッセージ内で定義されているため、完全に独立していることに注意してください。

message Outer {       // Level 0
  message MiddleAA {  // Level 1
    message Inner {   // Level 2
      int64 ival = 1;
      bool  booly = 2;
    }
  }
  message MiddleBB {  // Level 1
    message Inner {   // Level 2
      int32 ival = 1;
      bool  booly = 2;
    }
  }
}

メッセージ型の更新

既存のメッセージ型がすべてのニーズを満たさなくなった場合、たとえば、メッセージ形式に余分なフィールドを持たせたい場合でも、古い形式で作成されたコードを使用したい場合でも、心配いりません！バイナリワイヤー形式を使用する場合、既存のコードを壊すことなくメッセージ型を更新するのは非常に簡単です。

注意

ProtoJSON または proto テキスト形式を使用してプロトコルバッファメッセージを保存する場合、proto 定義で行える変更は異なります。ProtoJSON ワイヤー形式の安全な変更については、こちらで説明されています。

Protoのベストプラクティスと以下のルールを確認してください。

バイナリワイヤー形式で安全でない変更

ワイヤーアンセーフな変更とは、古いスキーマを使用してシリアル化されたデータを、新しいスキーマを使用するパーサーで解析した場合（またはその逆）、破損するスキーマ変更のことです。データのすべてのシリアライザーとデシリアライザーが新しいスキーマを使用していることがわかっている場合にのみ、ワイヤーアンセーフな変更を行ってください。

既存のフィールドのフィールド番号を変更することは安全ではありません。
- フィールド番号を変更することは、そのフィールドを削除し、同じ型で新しいフィールドを追加することと同等です。フィールドの番号を付け替えたい場合は、フィールドの削除の手順を参照してください。
フィールドを既存の`oneof`に移動することは安全ではありません。

バイナリワイヤー形式で安全な変更

ワイヤーセーフな変更とは、データの損失や新たなパース失敗のリスクなしに、スキーマをこの方法で進化させることが完全に安全な変更です。

ワイヤーセーフな変更であっても、特定の言語のアプリケーションコードにとって破壊的な変更となる可能性があることに注意してください。たとえば、既存のenumに値を追加することは、そのenumに対する包括的なswitchを持つコードのコンパイルを中断させる可能性があります。そのため、Googleは一部の公開メッセージに対してこれらの種類の変更を避ける場合があります。AIPには、これらの変更のうちどれが安全であるかについてのガイダンスが含まれています。

新しいフィールドの追加は安全です。
- 新しいフィールドを追加した場合、古いメッセージ形式を使用するコードによってシリアル化されたメッセージは、新しい生成コードによって引き続き解析できます。新しいコードが古いコードによって生成されたメッセージと適切にやり取りできるように、これらの要素のデフォルト値を覚えておく必要があります。同様に、新しいコードによって作成されたメッセージは、古いコードによって解析できます。古いバイナリは、解析時に新しいフィールドを単に無視します。詳細については、不明なフィールドセクションを参照してください。
フィールドの削除は安全です。
- 更新されたメッセージ型で同じフィールド番号を再度使用してはいけません。代わりにフィールドの名前を変更することをお勧めします。たとえば、「OBSOLETE_」というプレフィックスを追加したり、将来の.protoのユーザーが誤ってその番号を再利用しないように、フィールド番号を予約済みにしたりすることを検討してください。
enumに値を追加することは安全です。
単一の明示的な存在フィールドまたは拡張を**新しい** `oneof`のメンバーに変更することは安全です。
1つのフィールドのみを含む`oneof`を明示的な存在フィールドに変更することは安全です。
フィールドを同じ番号と型の拡張に変更することは安全です。

バイナリワイヤー形式で互換性のある変更（条件付きで安全）

ワイヤーセーフな変更とは異なり、ワイヤー互換性があるとは、特定の変更の前と後の両方で同じデータを解析できることを意味します。ただし、この形式の変更では、データの解析が情報損失を伴う可能性があります。たとえば、int32 を int64 に変更することは互換性のある変更ですが、INT32_MAXよりも大きな値が書き込まれた場合、int32として読み取るクライアントは数値の上位ビットを破棄します。

スキーマに対する互換性のある変更は、システムへの展開を慎重に管理する場合にのみ行うことができます。たとえば、int32 を int64 に変更することができますが、新しいスキーマがすべてのエンドポイントに展開されるまで合法的な int32 値のみを書き込み続け、その後により大きな値を書き込み始めることを保証します。

スキーマが組織外に公開されている場合、新しいスキーマの展開を管理して、異なる値の範囲がいつ安全に使用できるかを知ることができないため、一般的にワイヤー互換の変更を行うべきではありません。

`int32`、`uint32`、`int64`、`uint64`、および`bool`はすべて互換性があります。
- ワイヤーから解析された数値が対応する型に収まらない場合、C++でその数値をその型にキャストした場合と同じ効果が得られます（たとえば、64ビットの数値がint32として読み取られると、32ビットに切り捨てられます）。
`sint32`と`sint64`は互いに互換性がありますが、他の整数型とは互換性が*ありません*。
- 書き込まれた値がINT_MINとINT_MAXの範囲内であれば、どちらの型でも同じ値として解析されます。sint64の値がその範囲外で書き込まれ、sint32として解析された場合、varintは32ビットに切り捨てられ、その後ジグザグデコードが行われます（これにより異なる値が観測されることになります）。
`string`と`bytes`は、バイト列が有効なUTF-8である限り互換性があります。
埋め込みメッセージは、バイト列がメッセージのエンコードされたインスタンスを含んでいる場合、`bytes`と互換性があります。
`fixed32`は`sfixed32`と互換性があり、`fixed64`は`sfixed64`と互換性があります。
`string`、`bytes`、およびメッセージフィールドの場合、単数形は`repeated`と互換性があります。
- 繰り返しフィールドのシリアル化されたデータが入力として与えられた場合、このフィールドが単数であると想定するクライアントは、それがプリミティブ型フィールドの場合は最後の入力値を取得し、メッセージ型フィールドの場合はすべての入力要素をマージします。これは、ブール値や列挙型を含む数値型に対しては一般的に安全ではないことに注意してください。数値型の繰り返しフィールドは、デフォルトでパック形式でシリアル化されます。これは、単数フィールドが想定されている場合には正しく解析されません。
`enum`は`int32`、`uint32`、`int64`、`uint64`と互換性があります。
- メッセージがデシリアライズされたときに、クライアントコードがそれらを異なる方法で扱う可能性があることに注意してください。たとえば、認識されない proto3 enum 値はメッセージに保持されますが、メッセージがデシリアライズされたときにこれがどのように表現されるかは言語に依存します。
フィールドを `map<K, V>` と対応する `repeated` メッセージフィールドとの間で変更することは、バイナリ互換です（メッセージレイアウトやその他の制約については、下記のマップを参照してください）。
- しかし、変更の安全性はアプリケーションに依存します。メッセージをデシリアライズして再シリアライズする際、repeated フィールド定義を使用するクライアントは意味的に同一の結果を生成します。しかし、map フィールド定義を使用するクライアントは、エントリの順序を変更したり、重複するキーを持つエントリを削除したりする可能性があります。

未知のフィールド

不明なフィールドとは、パーサーが認識しないフィールドを表す、適切にフォーマットされたプロトコルバッファシリアル化データのことです。たとえば、古いバイナリが新しいフィールドを持つ新しいバイナリから送信されたデータを解析する場合、それらの新しいフィールドは古いバイナリでは不明なフィールドとなります。

Proto3 メッセージは、不明なフィールドを保持し、解析中およびシリアル化された出力にそれらを含めます。これは proto2 の動作と一致します。

未知のフィールドの保持

一部の操作により、未知のフィールドが失われる可能性があります。たとえば、次のいずれかを行うと、未知のフィールドは失われます。

プロトをJSONにシリアライズする。
メッセージ内のすべてのフィールドを反復処理して、新しいメッセージを生成する。

未知のフィールドを失わないようにするには、次のことを行ってください。

バイナリを使用し、データ交換にテキスト形式を使用しないようにする。
フィールドごとにコピーするのではなく、`CopyFrom()` や `MergeFrom()` などのメッセージ指向の API を使用してデータをコピーする。

TextFormatは少し特殊なケースです。TextFormatにシリアライズすると、未知のフィールドはフィールド番号を使用して出力されます。しかし、TextFormatデータをバイナリプロトに戻してパースすると、フィールド番号を使用するエントリがある場合に失敗します。

Any

Any メッセージ型を使用すると、.proto 定義がなくてもメッセージを埋め込み型として使用できます。Any には、任意のシリアル化されたメッセージが bytes として含まれ、そのメッセージの型のグローバルに一意な識別子として機能し、その型に解決される URL も含まれます。Any 型を使用するには、google/protobuf/any.proto をインポートする必要があります。

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  repeated google.protobuf.Any details = 2;
}

特定のメッセージ型のデフォルトの型URLは `type.googleapis.com/_packagename_._messagename_` です。

さまざまな言語実装は、型安全な方法で Any 値をパックおよびアンパックするためのランタイムライブラリヘルパーをサポートします。たとえば、Javaでは Any 型に特別な pack() および unpack() アクセサーがあり、C++では PackFrom() および UnpackTo() メソッドがあります。

// Storing an arbitrary message type in Any.
NetworkErrorDetails details = ...;
ErrorStatus status;
status.add_details()->PackFrom(details);

// Reading an arbitrary message from Any.
ErrorStatus status = ...;
for (const google::protobuf::Any& detail : status.details()) {
  if (detail.Is<NetworkErrorDetails>()) {
    NetworkErrorDetails network_error;
    detail.UnpackTo(&network_error);
    ... processing network_error ...
  }
}

Oneof

多くの単一フィールドを持ち、同時に最大1つのフィールドしか設定されないメッセージがある場合、oneof機能を使用することで、この動作を強制し、メモリを節約できます。

Oneof フィールドは、oneof 内のすべてのフィールドがメモリを共有し、同時に最大1つのフィールドしか設定できないという点を除いて、オプションフィールドと同じです。oneof のいずれかのメンバーを設定すると、他のすべてのメンバーが自動的にクリアされます。選択した言語に応じて、特別な case() または WhichOneof() メソッドを使用して、oneof のどの値が設定されているか (もしあれば) を確認できます。

複数の値が設定された場合、proto内の順序で決定される最後に設定された値が、以前のすべての値を上書きすることに注意してください。

oneofフィールドのフィールド番号は、それを囲むメッセージ内で一意でなければなりません。

Oneofの使用

`.proto`でoneofを定義するには、`oneof`キーワードの後にoneof名、この場合は`test_oneof`を続けます。

message SampleMessage {
  oneof test_oneof {
    string name = 4;
    SubMessage sub_message = 9;
  }
}

次に、oneof フィールドを oneof 定義に追加します。map フィールドと repeated フィールドを除く任意の型のフィールドを追加できます。繰り返しフィールドを oneof に追加する必要がある場合は、繰り返しフィールドを含むメッセージを使用できます。

生成されたコードでは、oneof フィールドは通常のフィールドと同じゲッターとセッターを持ちます。また、oneof のどの値が設定されているか (もしあれば) をチェックするための特別なメソッドも取得できます。選択した言語の oneof API の詳細については、関連するAPI リファレンスを参照してください。

Oneofの機能

oneofフィールドを設定すると、oneofの他のすべてのメンバーが自動的にクリアされます。そのため、複数のoneofフィールドを設定した場合、最後に設定したフィールドのみが値を持ち続けます。

SampleMessage message;
message.set_name("name");
CHECK_EQ(message.name(), "name");
// Calling mutable_sub_message() will clear the name field and will set
// sub_message to a new instance of SubMessage with none of its fields set.
message.mutable_sub_message();
CHECK(message.name().empty());

パーサーがワイヤ上で同じ oneof の複数のメンバーを検出した場合、解析されたメッセージでは最後に検出されたメンバーのみが使用されます。ワイヤ上のデータを解析する場合、バイトの最初から開始して、次の値を評価し、以下の解析ルールを適用します。
- まず、同じoneof内の*異なる*フィールドが現在設定されているかを確認し、設定されていればそれをクリアします。
- 次に、そのフィールドがoneof内にないかのように内容を適用します。
  - プリミティブは、既に設定されている値を上書きします。
  - メッセージは、すでに設定されている値にマージされます。
oneofは`repeated`にできません。
リフレクションAPIはoneofフィールドに対して機能します。
oneofフィールドをデフォルト値に設定した場合（例えば、int32のoneofフィールドを0に設定するなど）、そのoneofフィールドの「ケース」が設定され、値はワイヤー上でシリアライズされます。
C++を使用している場合は、コードがメモリクラッシュを引き起こさないように注意してください。以下のサンプルコードは、`set_name()`メソッドを呼び出すことによって`sub_message`がすでに削除されているため、クラッシュします。
```
SampleMessage message;
SubMessage* sub_message = message.mutable_sub_message();
message.set_name("name");      // Will delete sub_message
sub_message->set_...            // Crashes here
```
再びC++で、oneofを持つ2つのメッセージを`Swap()`すると、各メッセージは他方のoneofケースを持つことになります。以下の例では、`msg1`は`sub_message`を持ち、`msg2`は`name`を持つことになります。
```
SampleMessage msg1;
msg1.set_name("name");
SampleMessage msg2;
msg2.mutable_sub_message();
msg1.swap(&msg2);
CHECK(msg1.has_sub_message());
CHECK_EQ(msg2.name(), "name");
```

後方互換性の問題

oneof フィールドを追加または削除する場合は注意が必要です。oneof の値のチェックが None/NOT_SET を返した場合、oneof が設定されていないか、oneof の異なるバージョン内のフィールドに設定されている可能性があります。ワイヤ上の未知のフィールドが oneof のメンバーであるかどうかを知る方法がないため、違いを区別する方法はありません。

タグの再利用に関する問題

単一フィールドを oneof に移動または oneof から移動：メッセージがシリアル化および解析された後、一部の情報（一部のフィールドがクリアされる）が失われる可能性があります。ただし、単一フィールドを**新しい** oneof に安全に移動でき、1つのフィールドのみが常に設定されていることがわかっている場合は、複数のフィールドを移動できる場合があります。詳細については、メッセージ型の更新を参照してください。
oneofフィールドを削除して再度追加する: メッセージがシリアライズされ、パースされた後、現在設定されているoneofフィールドがクリアされる可能性があります。
oneof の分割または結合：これは、単一フィールドの移動と同様の問題があります。

マップ

データ定義の一部として連想マップを作成したい場合、プロトコルバッファは便利なショートカット構文を提供します。

map<key_type, value_type> map_field = N;

…ここで、key_type は任意の整数型または文字列型 (つまり、浮動小数点型と bytes を除くすべてのスカラー型) にすることができます。enum も proto メッセージも key_type には有効ではないことに注意してください。value_type は、別の map を除く任意の型にすることができます。

したがって、たとえば、各`Project`メッセージが文字列キーに関連付けられているプロジェクトのマップを作成したい場合、次のように定義できます。

map<string, Project> projects = 3;

マップの機能

マップフィールドはrepeatedにできません。
マップ値のワイヤーフォーマットの順序とマップの反復順序は未定義であるため、マップ項目が特定の順序であることに依存することはできません。
`.proto`のテキストフォーマットを生成する際、マップはキーによってソートされます。数値キーは数値的にソートされます。
ワイヤーからパースする場合やマージする場合、重複したマップキーが存在すると、最後に見つかったキーが使用されます。テキストフォーマットからマップをパースする場合、重複したキーがあるとパースに失敗することがあります。
マップフィールドにキーは提供するが値を提供しない場合、フィールドがシリアライズされる際の動作は言語に依存します。C++、Java、Kotlin、Pythonでは型のデフォルト値がシリアライズされますが、他の言語では何もシリアライズされません。
シンボル `FooEntry` は、マップ `foo` と同じスコープに存在できません。なぜなら、`FooEntry` はマップの実装によってすでに使用されているからです。

生成されたマップAPIは、現在サポートされているすべての言語で利用可能です。選択した言語のマップAPIの詳細については、関連するAPIリファレンスで確認できます。

後方互換性

マップ構文は、ワイヤー上では以下のものと等価であるため、マップをサポートしていないプロトコルバッファ実装でもデータを処理できます。

message MapFieldEntry {
  key_type key = 1;
  value_type value = 2;
}

repeated MapFieldEntry map_field = N;

マップをサポートするプロトコルバッファ実装は、以前の定義で受け入れ可能なデータを生成し、受け入れる必要があります。

パッケージ

プロトコルメッセージタイプ間の名前の衝突を防ぐために、`.proto`ファイルにオプションの`package`指定子を追加できます。

package foo.bar;
message Open { ... }

その後、メッセージタイプのフィールドを定義する際にパッケージ指定子を使用できます。

message Foo {
  ...
  foo.bar.Open open = 1;
  ...
}

パッケージ指定子が生成されたコードにどのように影響するかは、選択した言語によって異なります。

C++では、生成されたクラスはC++の名前空間内にラップされます。たとえば、`Open`は`foo::bar`という名前空間に入ります。
JavaおよびKotlinでは、`.proto`ファイルで明示的に`option java_package`を指定しない限り、パッケージはJavaのパッケージとして使用されます。
Pythonでは、Pythonモジュールはファイルシステム内の場所によって整理されるため、`package`ディレクティブは無視されます。
Goでは、packageディレクティブは無視され、生成された.pb.goファイルは対応するgo_proto_libraryBazelルールに従って命名されたパッケージに入ります。オープンソースプロジェクトの場合、go_packageオプションを提供するか、Bazelの-Mフラグを設定する**必要があります**。
Rubyでは、生成されたクラスはネストされたRuby名前空間でラップされ、必要なRubyのキャピタリゼーションスタイル（最初の文字が大文字。最初の文字がアルファベットでない場合はPB_が前置される）に変換されます。たとえば、OpenはFoo::Bar名前空間に入ります。
PHPでは、.protoファイルで明示的にoption php_namespaceを指定しない限り、パッケージはPascalCaseに変換された後、名前空間として使用されます。たとえば、OpenはFoo\Bar名前空間に入ります。
C#では、.protoファイルで明示的にoption csharp_namespaceを指定しない限り、パッケージはPascalCaseに変換された後、名前空間として使用されます。たとえば、OpenはFoo.Bar名前空間に入ります。

Pythonなど、package ディレクティブが生成コードに直接影響を与えない場合でも、.proto ファイルにパッケージを指定することを強くお勧めします。そうしないと、記述子で名前の衝突が発生し、他の言語で proto が移植できなくなる可能性があるためです。

パッケージと名前解決

プロトコルバッファ言語における型名の解決はC++のように機能します。まず最も内側のスコープが検索され、次にその次の内側のスコープが検索されます。各パッケージは親パッケージの「内側」にあると見なされます。先頭の「.」（例：.foo.bar.Baz）は、代わりに最も外側のスコープから開始することを意味します。

プロトコルバッファコンパイラは、インポートされた`.proto`ファイルを解析することですべての型名を解決します。各言語のコードジェネレータは、異なるスコーピングルールを持っていても、その言語で各型を参照する方法を知っています。

サービスの定義

メッセージ型をRPC（Remote Procedure Call）システムで使用したい場合は、.protoファイルでRPCサービスインターフェースを定義でき、プロトコルバッファコンパイラは選択した言語でサービスインターフェースコードとスタブを生成します。たとえば、SearchRequestを受け取りSearchResponseを返すメソッドを持つRPCサービスを定義したい場合は、.protoファイルで次のように定義できます。

service SearchService {
  rpc Search(SearchRequest) returns (SearchResponse);
}

プロトコルバッファで使用する最も簡単なRPCシステムは、gRPCです。これは、Googleで開発された言語とプラットフォームに依存しないオープンソースのRPCシステムです。gRPCはプロトコルバッファと特にうまく機能し、特別なプロトコルバッファコンパイラプラグインを使用して、.protoファイルから関連するRPCコードを直接生成できます。

gRPC を使用したくない場合でも、独自の RPC 実装でプロトコルバッファを使用できます。これについては、Proto2 言語ガイドで詳しく説明されています。

Protocol Buffers 用の RPC 実装を開発するための進行中のサードパーティプロジェクトもいくつかあります。私たちが知っているプロジェクトへのリンクのリストについては、サードパーティアドオン wiki ページを参照してください。

JSONマッピング

標準の protobuf バイナリワイヤー形式は、protobuf を使用する2つのシステム間の通信に推奨されるシリアル化形式です。protobuf ワイヤー形式ではなく JSON を使用するシステムとの通信には、Protobuf はJSONの正規エンコーディングをサポートしています。

オプション

.proto ファイル内の個々の宣言には、多くのオプションを注釈として付けることができます。オプションは宣言の全体的な意味を変更しませんが、特定のコンテキストでの処理方法に影響を与える可能性があります。利用可能なオプションの完全なリストは、/google/protobuf/descriptor.protoで定義されています。

一部のオプションはファイルレベルのオプションであり、メッセージ、enum、またはサービス定義の内部ではなく、トップレベルスコープで記述する必要があります。一部のオプションはメッセージレベルのオプションであり、メッセージ定義の内部で記述する必要があります。一部のオプションはフィールドレベルのオプションであり、フィールド定義の内部で記述する必要があります。オプションはenum型、enum値、oneofフィールド、サービス型、およびサービスメソッドにも記述できますが、現在、これらのいずれにも有用なオプションは存在しません。

以下は、最も一般的に使用されるオプションのいくつかです。

java_package (ファイルオプション): 生成される Java/Kotlin クラスに使用したいパッケージ。.proto ファイルで明示的な java_package オプションが指定されていない場合、デフォルトではプロトパッケージ (.proto ファイルで "package" キーワードを使用して指定) が使用されます。ただし、プロトパッケージは通常、リバースドメイン名で始まることが期待されないため、適切な Java パッケージにはなりません。Java または Kotlin コードを生成しない場合、このオプションは効果がありません。
```
option java_package = "com.example.foo";
```
java_outer_classname (ファイルオプション): 生成するラッパー Java クラスのクラス名（したがってファイル名）。.proto ファイルで明示的な java_outer_classname が指定されていない場合、クラス名は .proto ファイル名をキャメルケースに変換して構築されます（例: foo_bar.proto は FooBar.java になります）。java_multiple_files オプションが無効になっている場合、.proto ファイル用に生成される他のすべてのクラス/enumなどは、この外部ラッパー Java クラスの**内部**にネストされたクラス/enumなどとして生成されます。Java コードを生成しない場合、このオプションは効果がありません。
```
option java_outer_classname = "Ponycopter";
```
java_multiple_files (ファイルオプション): false の場合、この .proto ファイルに対しては単一の .java ファイルのみが生成され、トップレベルのメッセージ、サービス、列挙型に対して生成されるすべての Java クラス/enum などは、外部クラス (java_outer_classname を参照) の中にネストされます。true の場合、トップレベルのメッセージ、サービス、列挙型に対して生成される各 Java クラス/enum などに対して個別の .java ファイルが生成され、この .proto ファイル用に生成されるラッパー Java クラスにはネストされたクラス/enum などは含まれません。これはブール型のオプションで、デフォルトは false です。Java コードを生成しない場合、このオプションは効果がありません。
```
option java_multiple_files = true;
```
`optimize_for` (ファイルオプション): `SPEED`、`CODE_SIZE`、または`LITE_RUNTIME`に設定できます。これはC++およびJavaのコードジェネレータ（および場合によってはサードパーティのジェネレータ）に次のように影響します。
- `SPEED` (デフォルト): プロトコルバッファコンパイラは、メッセージタイプのシリアライズ、パース、その他の一般的な操作のためのコードを生成します。このコードは高度に最適化されています。
- CODE_SIZE: プロトコルバッファコンパイラは最小限のクラスを生成し、シリアル化、解析、およびその他のさまざまな操作を実装するために、共有されたリフレクションベースのコードに依存します。したがって、生成されるコードは SPEED よりもはるかに小さくなりますが、操作は遅くなります。クラスは、SPEED モードと同じパブリック API を実装します。このモードは、非常に多くの .proto ファイルを含み、それらすべてが非常に高速である必要がないアプリで最も役立ちます。
- LITE_RUNTIME: プロトコルバッファコンパイラは「lite」ランタイムライブラリ（libprotobufではなくlibprotobuf-lite）のみに依存するクラスを生成します。liteランタイムはフルライブラリよりもはるかに小さく（約1桁小さい）、記述子やリフレクションなどの特定の機能は省略されます。これは、モバイルフォンなどの制約されたプラットフォームで実行されるアプリに特に役立ちます。コンパイラは、SPEEDモードと同様に、すべてのメソッドの高速な実装を生成します。生成されるクラスは、各言語でMessageLiteインターフェースのみを実装します。これは、フルMessageインターフェースのメソッドの一部のみを提供します。
```
option optimize_for = CODE_SIZE;
```
cc_generic_services、java_generic_services、py_generic_services（ファイルオプション）：**ジェネリックサービスは非推奨です。**プロトコルバッファコンパイラがC++、Java、Pythonでそれぞれサービス定義に基づいて抽象サービスコードを生成するかどうか。レガシーの理由から、これらはデフォルトでtrueです。ただし、バージョン2.3.0（2010年1月）以降、RPC実装は「抽象」サービスに依存するのではなく、各システムに特化したコードを生成するためのコードジェネレータプラグインを提供することが望ましいとされています。
```
// This file relies on plugins to generate service code.
option cc_generic_services = false;
option java_generic_services = false;
option py_generic_services = false;
```
`cc_enable_arenas` (ファイルオプション): C++で生成されたコードに対してアリーナアロケーションを有効にします。
objc_class_prefix (ファイルオプション): この .proto から生成されるすべての Objective-C クラスと enum の前に付加される Objective-C クラスプレフィックスを設定します。デフォルトはありません。Apple が推奨するように、3～5文字の大文字のプレフィックスを使用する必要があります。2文字のプレフィックスはすべて Apple によって予約されています。
packed (フィールドオプション): 基本数値型の繰り返しフィールドではデフォルトで true になり、よりコンパクトなエンコーディングが使用されます。パックされていないワイヤ形式を使用するには、false に設定できます。これにより、以下の例に示すように、バージョン 2.3.0 以前のパーサーとの互換性が提供されます (ほとんど必要ありません)。
```
repeated int32 samples = 4 [packed = false];
```
deprecated（フィールドオプション）：trueに設定されている場合、そのフィールドは非推奨であり、新しいコードでは使用すべきではないことを示します。ほとんどの言語では、これによる実際の影響はありません。Javaでは、@Deprecatedアノテーションになります。C++では、deprecatedフィールドが使用されるたびにclang-tidyが警告を生成します。将来的には、他の言語固有のコードジェネレータがフィールドのアクセサに非推奨アノテーションを生成する可能性があり、その結果、そのフィールドを使用しようとするコードをコンパイルする際に警告が発せられます。そのフィールドが誰にも使用されず、新しいユーザーがそれを使用することを防ぎたい場合は、フィールド宣言を予約済みステートメントに置き換えることを検討してください。
```
int32 old_field = 6 [deprecated = true];
```

列挙値のオプション

Enum値のオプションがサポートされています。`deprecated`オプションを使用して、ある値がもはや使用されるべきでないことを示すことができます。拡張機能を使用してカスタムオプションを作成することもできます。

次の例は、これらのオプションを追加するための構文を示しています。

import "google/protobuf/descriptor.proto";

extend google.protobuf.EnumValueOptions {
  optional string string_name = 123456789;
}

enum Data {
  DATA_UNSPECIFIED = 0;
  DATA_SEARCH = 1 [deprecated = true];
  DATA_DISPLAY = 2 [
    (string_name) = "display_value"
  ];
}

`string_name`オプションを読み取るC++コードは、次のようになるかもしれません。

const absl::string_view foo = proto2::GetEnumDescriptor<Data>()
    ->FindValueByName("DATA_DISPLAY")->options().GetExtension(string_name);

enum値やフィールドにカスタムオプションを適用する方法については、カスタムオプションを参照してください。

カスタムオプション

Protocol Buffers では、独自のオプションを定義して使用することもできます。これはほとんどの人が必要としない高度な機能であることに注意してください。独自のオプションを作成する必要があると思われる場合は、詳細についてProto2 言語ガイドを参照してください。カスタムオプションの作成には拡張機能を使用しますが、proto3ではカスタムオプションの場合にのみ許可されていることに注意してください。

オプションの保持

オプションには、生成コードにオプションを保持するかどうかを制御する保持の概念があります。オプションはデフォルトでランタイム保持を持ちます。つまり、生成コードに保持され、生成された記述子プールでランタイム時に可視になります。ただし、retention = RETENTION_SOURCE を設定して、オプション（またはオプション内のフィールド）をランタイム時に保持しないことを指定できます。これはソース保持と呼ばれます。

オプションの保持は、ほとんどのユーザーが気にする必要のない高度な機能ですが、バイナリで保持するコードサイズのコストを支払うことなく、特定のオプションを使用したい場合に役立ちます。ソース保持のあるオプションは、protoc および protoc プラグインには引き続き表示されるため、コードジェネレーターはそれらを使用して動作をカスタマイズできます。

保持は、次のようにオプションに直接設定できます。

extend google.protobuf.FileOptions {
  optional int32 source_retention_option = 1234
      [retention = RETENTION_SOURCE];
}

通常のフィールドにも設定できますが、その場合、そのフィールドがオプション内に現れる場合にのみ効果があります。

message OptionsMessage {
  int32 source_retention_field = 1 [retention = RETENTION_SOURCE];
}

retention = RETENTION_RUNTIME を設定することもできますが、これはデフォルトの動作であるため効果はありません。メッセージフィールドが RETENTION_SOURCE とマークされている場合、その内容全体が破棄されます。その内部のフィールドは RETENTION_RUNTIME を設定しようとしても、それを上書きすることはできません。

注意

Protocol Buffers 22.0の時点では、オプション保持のサポートはまだ進行中であり、C++とJavaのみがサポートされています。Goは1.29.0からサポートしています。Pythonのサポートは完了していますが、まだリリースには含まれていません。

オプションのターゲット

フィールドには targets オプションがあり、オプションとして使用される場合にフィールドが適用されるエンティティのタイプを制御します。たとえば、フィールドが targets = TARGET_TYPE_MESSAGE の場合、そのフィールドは enum (またはその他の非メッセージエンティティ) のカスタムオプションで設定できません。Protoc はこれを強制し、ターゲット制約に違反がある場合はエラーを発生させます。

一見すると、この機能は不要に見えるかもしれません。各カスタムオプションは、特定のエンティティのオプションメッセージの拡張機能であり、すでにそのオプションをその1つのエンティティに制約しているためです。ただし、オプションターゲットは、複数のエンティティタイプに適用される共有オプションメッセージがあり、そのメッセージ内の個々のフィールドの使用を制御したい場合に役立ちます。たとえば、

message MyOptions {
  string file_only_option = 1 [targets = TARGET_TYPE_FILE];
  int32 message_and_enum_option = 2 [targets = TARGET_TYPE_MESSAGE,
                                     targets = TARGET_TYPE_ENUM];
}

extend google.protobuf.FileOptions {
  optional MyOptions file_options = 50000;
}

extend google.protobuf.MessageOptions {
  optional MyOptions message_options = 50000;
}

extend google.protobuf.EnumOptions {
  optional MyOptions enum_options = 50000;
}

// OK: this field is allowed on file options
option (file_options).file_only_option = "abc";

message MyMessage {
  // OK: this field is allowed on both message and enum options
  option (message_options).message_and_enum_option = 42;
}

enum MyEnum {
  MY_ENUM_UNSPECIFIED = 0;
  // Error: file_only_option cannot be set on an enum.
  option (enum_options).file_only_option = "xyz";
}

クラスの生成

.protoファイルで定義されたメッセージ型を扱うために必要なJava、Kotlin、Python、C++、Go、Ruby、Objective-C、またはC#のコードを生成するには、.protoファイルに対してプロトコルバッファコンパイラprotocを実行する必要があります。コンパイラをインストールしていない場合は、パッケージをダウンロードし、READMEの指示に従ってください。Goの場合、コンパイラ用の特別なコード生成プラグインもインストールする必要があります。これはGitHubのgolang/protobufリポジトリでインストール手順とともに見つけることができます。

プロトコルコンパイラは次のように呼び出されます。

protoc --proto_path=IMPORT_PATH --cpp_out=DST_DIR --java_out=DST_DIR --python_out=DST_DIR --go_out=DST_DIR --ruby_out=DST_DIR --objc_out=DST_DIR --csharp_out=DST_DIR path/to/file.proto

IMPORT_PATHは、importディレクティブを解決する際に.protoファイルを探すディレクトリを指定します。省略された場合、現在のディレクトリが使用されます。複数のインポートディレクトリは、--proto_pathオプションを複数回渡すことで指定できます。-I=_IMPORT_PATH_は--proto_pathの短縮形として使用できます。

注意: proto_pathに対する相対ファイルパスは、特定のバイナリ内でグローバルに一意である必要があります。たとえば、proto/lib1/data.protoとproto/lib2/data.protoがある場合、-I=proto/lib1 -I=proto/lib2と組み合わせて使用することはできません。なぜなら、import "data.proto"がどちらのファイルを意味するのか曖昧になるからです。代わりに-Iproto/を使用し、グローバル名はlib1/data.protoとlib2/data.protoになります。

ライブラリを公開しており、他のユーザーがメッセージを直接使用する可能性がある場合、ファイル名の衝突を避けるために、パスに一意のライブラリ名を含めて使用することが期待されます。1つのプロジェクトに複数のディレクトリがある場合は、プロジェクトの最上位ディレクトリに1つの-Iを設定するのが最善の方法です。

1つ以上の出力指示を提供できます。
- --cpp_out は DST_DIR に C++ コードを生成します。詳細については、C++ 生成コードリファレンスを参照してください。
- --java_out は DST_DIR に Java コードを生成します。詳細については、Java 生成コードリファレンスを参照してください。
- --kotlin_out は DST_DIR に追加の Kotlin コードを生成します。詳細については、Kotlin 生成コードリファレンスを参照してください。
- --python_out は DST_DIR に Python コードを生成します。詳細については、Python 生成コードリファレンスを参照してください。
- --go_out は DST_DIR に Go コードを生成します。詳細については、Go 生成コードリファレンスを参照してください。
- --ruby_out は DST_DIR に Ruby コードを生成します。詳細については、Ruby 生成コードリファレンスを参照してください。
- --objc_out は DST_DIR に Objective-C コードを生成します。詳細については、Objective-C 生成コードリファレンスを参照してください。
- --csharp_out は DST_DIR に C# コードを生成します。詳細については、C# 生成コードリファレンスを参照してください。
- --php_out は DST_DIR に PHP コードを生成します。詳細については、PHP 生成コードリファレンスを参照してください。
さらに便利な機能として、DST_DIR が .zip または .jar で終わる場合、コンパイラは出力を指定された名前の単一の ZIP 形式アーカイブファイルに書き込みます。.jar 出力には、Java JAR 仕様で要求されるマニフェストファイルも与えられます。出力アーカイブが既に存在する場合、上書きされます。
1つ以上の.protoファイルを入力として指定する必要があります。複数の.protoファイルを一度に指定できます。ファイルは現在のディレクトリに対する相対パスで指定されますが、コンパイラが正規名を決定できるように、各ファイルはIMPORT_PATHのいずれかの場所に存在する必要があります。

ファイルの場所

.protoファイルを他の言語のソースと同じディレクトリに置かないことをお勧めします。プロジェクトのルートパッケージの下に、.protoファイル用のサブパッケージprotoを作成することを検討してください。

場所は言語に依存しないようにすべき

Java コードを扱う場合、関連する .proto ファイルを Java ソースと同じディレクトリに配置すると便利です。ただし、Java 以外のコードが同じプロトコルを使用する場合、パスのプレフィックスは意味をなさなくなります。したがって、一般的には、プロトコルは //myteam/mypackage のような関連する言語に依存しないディレクトリに配置します。

このルールの例外は、テスト用など、プロトコルが Java コンテキストでのみ使用されることが明らかな場合です。

サポートされているプラットフォーム

に関する情報

サポートされているオペレーティングシステム、コンパイラ、ビルドシステム、C++バージョンについては、Foundational C++ Support Policyを参照してください。
サポートされている PHP バージョンについては、Supported PHP versionsを参照してください。