Protobuf 形式

MIME タイプ: application/protobuf

ID: protobuf

Protobuf は、DataWeave 値にネイティブにマップできるデータ形式です。ユーザーの観点からは、DataWeave で読み書きするメッセージの記述子ファイルの場所と完全修飾名を常に指定します。設定プロパティを指定するときに、descriptorUrl プロパティと messageType プロパティをそれぞれ使用します。

例: Protobuf メッセージを読み取るときに記述子を指定する

次の例は、Protobuf メッセージを解析して JSON に変換するための記述子の場所とメッセージ種別を指定する方法を示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.descriptor;

message MyMessage {
  int32 myInt = 3;
  bool myBool = 13;
  string myString = 23;
}protobuf

入力

Protobuf メッセージは、DataWeave ソースへの入力ペイロードとして機能します。これには、値が 42 の myInt 項目、値が false の myBool 項目、値が DW + Proto の myString 項目が含まれます。Protobuf メッセージは、表現がわかりづらいため表示していません。

ソース

この DataWeave スクリプトは、int 項目、bool 項目、string 項目が含まれる Protobuf メッセージを読み取り、その入力を JSON 形式に変換します。 messageType は、読み取られるメッセージの完全修飾名 (このケースでは examples.descriptor.MyMessage) を参照します。 descriptorUrl は、記述子 (前述の .proto スキーマのコンパイル済みのバージョン) を参照します。

%dw 2.0
output application/json
input payload application/x-protobuf messageType='examples.descriptor.MyMessage',descriptorUrl="descriptors/examples.dsc"
---
payloaddataweave

出力

この DataWeave スクリプトは、3 つの値が含まれる次の JSON オブジェクトを出力します。

{
  "myInt": 42.0,
  "myBool": false,
  "myString": "DW <3 Proto"
}json

Protobuf 機能

Protobuf では、他の形式では一般的でない次の機能がサポートされています。

列挙

Protobuf 列挙 Leaving the Site は、列挙インデックスを指定する特定のスキーマで文字列として読み取られます。proto メッセージを解析するときに、列挙値の表示ラベルを抽出するためにこのスキーマが使用されます。多くの表示ラベルで同じインデックスを共有している場合、最初の表示ラベルが使用されます。インデックスに一致する表示ラベルがない場合、特殊な表示ラベル「-UNRECOGNIZED」が使用されます。 proto メッセージを書き込むときに、特定の表示ラベルに対応するインデックスの取得に使用されるプロトコルがスキーマによって指定されます。

例: DataWeave を使用して Protobuf 列挙を書き込む

次の例は、特定のスキーマの場合に列挙値が含まれる proto メッセージを生成する方法を示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.enumerations;


message Langs {
  enum Languages {
    DataWeave = 0;
    Scala = 2;
    Java = 343049039;
  }

  Languages okayLanguage = 10;
  Languages bestLanguage = 11;
}protobuf

ソース

この DataWeave スクリプトは、okayLanguage および bestLanguage 値が含まれる Protobuf メッセージを出力します。

%dw 2.0
output application/x-protobuf messageType='examples.enumerations.Langs',descriptorUrl="descriptors/examples.dsc"
---
{
  okayLanguage : "Scala",
  bestLanguage : "DataWeave"
}dataweave

出力

この DataWeave スクリプトは、エンコードされた値で指定された 2 つの項目が含まれる Protobuf メッセージを出力します。

例: DataWeave を使用して Protobuf 列挙を読み取る

次の例は、特定のスキーマの場合に一部の列挙値が含まれる proto メッセージを読み取る方法と、メッセージに存在する値がスキーマで指定されていない場合に想定される内容を示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.enumerations;


message Langs {
  enum Languages {
    DataWeave = 0;
    Scala = 2;
    Java = 343049039;
  }

  Languages okayLanguage = 10;
  Languages bestLanguage = 11;
}protobuf

入力

DataWeave ソースへの入力ペイロードとして機能する Protobuf メッセージは、バイナリであるため表示していません。これには列挙インデックス 3 (スキーマで指定されていないインデックス) の okayLanguage 項目が含まれますが、bestLanguage には想定される値が含まれます。

ソース

この DataWeave スクリプトは、Protobuf メッセージを読み取り、DataWeave 出力として出力します。

%dw 2.0
input payload application/x-protobuf messageType='examples.enumerations.Langs',descriptorUrl="descriptors/examples.dsc"
output application/dw
---
payloaddataweave

出力

この DataWeave スクリプトは、Protobuf メッセージ入力が DataWeave (dw) 形式でどのように表わされるかを示しています。

{
  okayLanguage: "-UNRECOGNIZED" as String {protobufEnumIndex: 3},
  bestLanguage: "DataWeave" as String {protobufEnumIndex: 0},
}dataweave

Oneof

Oneof Leaving the Site 項目 (Protobuf 固有) は、DataWeave の通常の項目として表されます。proto メッセージを書き込むときに、特定のスキーマで DataWeave スクリプトで検証する必要がある項目を指定します。複数の項目が定義されている場合、スクリプトは失敗します。

例: 2 つの排他的な項目を書き込もうとする無効な試行

次の例は、スキーマに従って 2 つの排他的な項目を書き込もうとするとどうなるのか示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.oneof;

message ThisOrThat {
  oneof thisOrThat {
    bool this = 2;
    bool that = 4;
  }
}protobuf

ソース

この DataWeave スクリプトは、this と that の両方項目セットが含まれる Protobuf メッセージを出力します。

%dw 2.0
output application/x-protobuf messageType='examples.oneof.ThisOrThat',descriptorUrl="descriptors/examples.dsc"
---
{
  this: true,
  that: false,
}dataweave

出力

この DataWeave スクリプトは、誤って使用されている oneof を指定する ProtoBufWritingException を出力します。

反復項目

DataWeave では反復項目が許可されているため、Protobuf 反復項目は DataWeave 反復し項目と一致します (逆の場合も同様)。書き込まれる DataWeave オブジェクトは、使用されるスキーマと一致する必要があります。スキーマで反復として指定されていない項目が DataWeave スクリプトに複数回出現すると、スクリプトは失敗します。

例: JSON 配列を Protobuf 反復項目に変換する

次の例は、JSON 配列から取得された反復項目が含まれる proto メッセージを生成する方法を示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.repeated;


message People {
  repeated string names = 1;
}protobuf

入力

この JSON 入力が DataWeave ソースへのペイロードとして機能します。

{
  "names": [
    "Mariano",
    "Shoki",
    "Tomo",
    "Ana"
  ]
}json

ソース

この DataWeave スクリプトは、reduce 関数を使用して、配列の名前ごとに新しい項目を生成します。

%dw 2.0
output application/x-protobuf messageType='examples.repeated.People',descriptorUrl="descriptors/examples.dsc"
---
reduce(payload.names, (item, acc = {}) ->  acc ++ {names: item})dataweave

出力

この DataWeave スクリプトは、JSON 配列のすべての名前が含まれる反復項目のある Protobuf メッセージを出力します。

例: Protobuf 反復項目を JSON 配列に変換する

次の例は、反復項目が含まれる proto メッセージを JSON 配列に変換する方法を示しています。

スキーマ

次のスキーマでは、この例で使用されるプロトコルを指定します。

syntax = "proto3";

package examples.repeated;


message People {
  repeated string names = 1;
}protobuf

ソース

この DataWeave スクリプトは、名前の配列が含まれる JSON メッセージを出力します。

%dw 2.0
input payload application/x-protobuf messageType='examples.repeated.People',descriptorUrl="descriptors/examples.dsc"
output application/json
---
names: payload.people.*namesdataweave

出力

この DataWeave スクリプトは、名前の配列が含まれる JSON メッセージを出力します。

{
  "names": [
    "Mariano",
    "Shoki",
    "Tomo",
    "Ana"
  ]
}json

不明

Protobuf では、プロトコルの前方互換性と後方互換性を確保する機能が提供されます。これを実現するために、リーダーとライターでメッセージの不明な項目 Leaving the Site が許可されています。DataWeave は、特定のキー名を使用してこの機能に適応します。

Protobuf メッセージを読み取るときに、スキーマにない項目が検出されると、"-35": 111111 as Number {wireType: "Varint"}, のように読み取られます。"-35" は項目インデックスが 35 であることを意味し、wireType: "Varint" はメッセージの項目のワイヤー種別を指定します。wireType は、"Varint"、"64Bit"、"LengthDelimited"、"Group"、または "32Bit" になります。

セマンティック解析 (一般的に使用されるメッセージ種別)

Protobuf では、一般的に使用されるメッセージ種別 Leaving the Site のコレクションが提供されます。DataWeave は、これらの一部を基盤となるメッセージではなく、表される値として解析します。たとえば、google.protobuf.Duration は Period として DataWeave に読み取られますが、google.protobuf.NullValue は Null として読み取られます。

次の表で、Protobuf 型と DataWeave 型の対応について説明します。

Protobuf 型	DataWeave 型
BoolValue	Boolean (ブール)
BytesValue	Binary (バイナリ)
DoubleValue	Number (数値)
Duration (所要時間)	Duration Period (期間)
空	{}
FloatValue	Number (数値)
Int32Value	Number (数値)
Int64Value	Number (数値)
ListValue	Array (配列)
NullValue	Null
StringValue	String (文字列)
Struct (構造)	Object (オブジェクト)
Timestamp (タイムスタンプ)	LocalDateTime
UInt32Value	Number (数値)
UInt64Value	Number (数値)
Value (値)	ProtoBufValue

Protobuf 型

DataWeave 型

BoolValue

Boolean (ブール)

BytesValue

Binary (バイナリ)

DoubleValue

Number (数値)

Duration (所要時間)

Duration Period (期間)

空

{}

FloatValue

Number (数値)

Int32Value

Number (数値)

Int64Value

Number (数値)

ListValue

Array (配列)

NullValue

Null

StringValue

String (文字列)

Struct (構造)

Object (オブジェクト)

Timestamp (タイムスタンプ)

LocalDateTime

UInt32Value

Number (数値)

UInt64Value

Number (数値)

Value (値)

ProtoBufValue

各項目は次のとおりです。

type ProtoBufValue  = Null
                    | Number
                    | String
                    | Boolean
                    | { _?: ProtoBufValue }
                    | Array<ProtoBufValue>dataweave

マップ

Protobuf マップ Leaving the Site により、定義済みのキーセットがなく、各項目の値の型が同じ構造を得られます。 map<keyType, valueType> は DataWeave オブジェクトにマップされます。キーは文字列として表され、値は対応する値にマップされます。proto メッセージを書き込むときに、キーは記述子で指定された keyType にキャストされます。キャストを実行できない場合、スクリプトは失敗します。

記述子へのスキーマのコンパイル

DataWeave は、*.proto ファイルを直接使用できないため、記述子と呼ばれるコンパイル済みのバージョンが必要になります。protoc --descriptor_set_out=./out.dsc file1.proto file2.proto … のように protoc コンパイラーを使用して記述子を生成します。out.dsc は、(DataWeave の descriptorUrl プロパティで想定される) 記述子の出力ファイルで、file1.proto と file2.proto は、コンパイラーでコンパイルする必要がある実際のプロトコル仕様です。

Configuration のプロパティ

DataWeave では、この形式の以下の設定プロパティがサポートされています。

Reader のプロパティ

この形式は、入力データを読み取るための指示を提供するプロパティを受け入れます。

パラメーター型デフォルト説明

パラメーター	型	デフォルト	説明
`bufferSize`	`Number`	`8192`	バッファライターのサイズ。値は 8 よりも大きい必要があります。
`deferred`	`Boolean`	`false`	`true` に設定すると、出力をデータストリームとして生成し、スクリプトの実行は生成されたコンテンツがコンシュームされるまで延期されます。有効な値は、`true` または `false` です。
`descriptorUrl` (必須)	`String`	`''`	ProtoBuf 記述子の URL。有効な値は、`classpath://`、`file://`、`http://` です。
`messageType` (必須)	`String`	`null`	特定の記述子から取得されるメッセージ種別の完全名 (そのパッケージを含む)。

bufferSize

Number

8192

バッファライターのサイズ。値は 8 よりも大きい必要があります。

deferred

Boolean

false

true に設定すると、出力をデータストリームとして生成し、スクリプトの実行は生成されたコンテンツがコンシュームされるまで延期されます。

有効な値は、true または false です。

descriptorUrl (必須)

String

''

ProtoBuf 記述子の URL。有効な値は、classpath://、file://、http:// です。

messageType (必須)

String

null

特定の記述子から取得されるメッセージ種別の完全名 (そのパッケージを含む)。

Writer のプロパティ

この形式は、出力データを書き込むための指示を提供するプロパティを受け入れます。

パラメーター型デフォルト説明

パラメーター	型	デフォルト	説明
`bufferSize`	`Number`	`8192`	バッファライターのサイズ。値は 8 よりも大きい必要があります。
`deferred`	`Boolean`	`false`	`true` に設定すると、出力をデータストリームとして生成し、スクリプトの実行は生成されたコンテンツがコンシュームされるまで延期されます。有効な値は、`true` または `false` です。
`descriptorUrl` (必須)	`String`	`''`	ProtoBuf 記述子の URL。有効な値は、`classpath://`、`file://`、`http://` です。
`messageType` (必須)	`String`	`null`	特定の記述子から取得されるメッセージ種別の完全名 (そのパッケージを含む)。

bufferSize

Number

8192

バッファライターのサイズ。値は 8 よりも大きい必要があります。

deferred

Boolean

false

true に設定すると、出力をデータストリームとして生成し、スクリプトの実行は生成されたコンテンツがコンシュームされるまで延期されます。

有効な値は、true または false です。

descriptorUrl (必須)

String

''

ProtoBuf 記述子の URL。有効な値は、classpath://、file://、http:// です。

messageType (必須)

String

null

特定の記述子から取得されるメッセージ種別の完全名 (そのパッケージを含む)。

サポートされる MIME タイプ

この形式では、次の MIME タイプがサポートされます。

MIME タイプ

MIME タイプ
`application/protobuf`
`application/x-protobuf`

application/protobuf

application/x-protobuf