1. Homepage
  2. DataWeave (2.5)
  3. 言語ガイド
  4. サポートされるデータ形式

  5. Protobuf 形式

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 メッセージは、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"
---
payload

出力

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

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

Protobuf 機能

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

列挙

Protobuf 列挙​は、列挙インデックスを指定する特定のスキーマで​文字列​として読み取られます。​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;
}

ソース

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

%dw 2.0
output application/x-protobuf messageType='examples.enumerations.Langs',descriptorUrl="descriptors/examples.dsc"
---
{
  okayLanguage : "Scala",
  bestLanguage : "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;
}

入力

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
---
payload

出力

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

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

Oneof

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

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

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

スキーマ

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

syntax = "proto3";

package examples.oneof;

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

ソース

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

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

出力

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

反復項目

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

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

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

スキーマ

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

syntax = "proto3";

package examples.repeated;


message People {
  repeated string names = 1;
}

入力

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

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

ソース

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

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

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

スキーマ

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

syntax = "proto3";

package examples.repeated;


message People {
  repeated string names = 1;
}

ソース

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

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

出力

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

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

不明

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

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

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

Protobuf では、 一般的に使用されるメッセージ種別​のコレクションが提供されます。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

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

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

マップ

Protobuf マップ​により、定義済みのキーセットがなく、各項目の値の型が同じ構造を得られます。 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

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

Writer のプロパティ

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

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

bufferSize

Number

8192

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

deferred

Boolean

false

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

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

descriptorUrl​ (必須)

String

''

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

messageType​ (必須)

String

null

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

サポートされる MIME タイプ

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

MIME タイプ

application/protobuf

application/x-protobuf