EventBridge は、標準の CloudEvents 1.0 形式のイベントを、イベントターゲットが期待する構造に変換します。各イベントルールで変換メソッドを構成して、ターゲットに到達するデータを制御します。これには、完全なイベント、単一の抽出されたフィールド、静的ペイロード、またはイベント値から組み立てられたカスタム構造があります。
変換メソッド
EventBridge は4つの変換メソッドを提供します。それぞれが、ターゲットに配信されるイベントペイロードに対して異なるレベルの制御を提供します。
| メソッド | 動作 | 使用する場合 |
|---|---|---|
| 完了イベント | 変更なしで完全な CloudEvents ペイロードを配信します | ターゲットは CloudEvents をネイティブに受け入れます |
| 部分的なイベント | JSONPath 式を使用して単一の値を抽出します | ターゲットがイベントから単一のフィールドのみを必要とする場合 |
| 定数 | イベントコンテンツを無視して、固定文字列を配信します | イベントがトリガーのみである場合 -- ターゲットは静的ペイロードを必要とします |
| テンプレート | JSONPath を使用して複数の値を抽出し、それらをカスタム文字列または JSON 構造に組み立てます | ターゲットが特定のペイロード形式を必要とする場合 |
次の例では、サンプルの CloudEvents イベントを使用します。
{
"id": "7adc8c1a-645d-4476-bdef-5d6fb57f****",
"source": "acs.oss",
"specversion": "1.0",
"type": "oss:ObjectCreated:PostObject",
"datacontenttype": "application/json",
"dataschema": "http://example.com/test.json",
"subject": "acs:oss:cn-hangzhou:1234567:xls-papk/game_apk/123.jpg",
"time": "2020-08-17T16:04:46.149Asia/Shanghai",
"aliyuneventbusname": "demo-bus",
"aliyunregionid": "Shanghai",
"data": {
"name": "test",
"scope": 100
}
}イベントの完了
CloudEvents ペイロード全体が変更なしでターゲットに配信されます。構成は不要です。
出力:
{
"id": "7adc8c1a-645d-4476-bdef-5d6fb57f****",
"source": "acs.oss",
"specversion": "1.0",
"type": "oss:ObjectCreated:PostObject",
"datacontenttype": "application/json",
"dataschema": "http://example.com/test.json",
"subject": "acs:oss:cn-hangzhou:1234567:xls-papk/game_apk/123.jpg",
"time": "2020-08-17T16:04:46.149Asia/Shanghai",
"aliyuneventbusname": "demo-bus",
"aliyunregionid": "Shanghai",
"data": {
"name": "test",
"scope": 100
}
}部分的なイベント
単一の JSONPath 式がイベントから1つの値を抽出します。
構成:
{
"name": "$.data.name",
"state": "$.data.state"
}出力:
test1注意事項:
部分的なイベントの構成ごとに、1つの JSONPath 式のみが許可されます。
値は最大10,240文字の長さにすることができます。
定数
固定文字列がイベントペイロードを置き換えます。イベント自体は純粋にトリガーとして機能します。
構成:
test1出力:
test1注意事項:
値は最大10,240文字の長さにすることができます。
テンプレート
テンプレートは最も柔軟なメソッドです。これは2つの部分で機能します。
変数 -- 変数名を JSONPath 式 (または固定値) にマッピングする JSON オブジェクトです。各 JSONPath 式はイベントから値を抽出します。
テンプレート --
${variableName}構文で変数を参照する文字列または JSON 構造です。
構成:
変数:
{
"name": "$.data.name",
"constant": "Please deal with it timely."
}テンプレート:
The instance is broken, which name is ${name}, ${constant}出力:
The instance is broken, which name is test, Please deal with it timely.注意事項:
変数値は JSONPath 式または固定文字列にすることができます。
変数定義ではネストされた構造はサポートされていません。
変数値は最大10,240文字の長さにすることができます。
テンプレート値は最大10,240文字の長さにすることができます。
テンプレートの出力形式
テンプレートでは、単純な文字列、単純な JSON 、変数と定数が混在する JSON 、およびネストされた JSON の 4 つの出力フォーマットがサポートされています。単純な文字列、単純な JSON 、および変数と定数が混在する JSON の例では、上記と同じサンプルイベントが使用されますが、data フィールドでは "scope": 100 の代わりに "state": "RUNNING" が使用されます。ネストされた JSON の例では、異なるサンプルイベントを使用します。
単純な文字列
変数:
{
"name": "$.data.name",
"state": "$.data.state"
}テンプレート:
"name ${name} is in ${state}"出力:
"name test is in RUNNING"単純な JSON
変数:
{
"name": "$.data.name",
"state": "$.data.state"
}テンプレート:
{
"name": "${name}",
"state": "${state}"
}出力:
{
"name": "test",
"state": "RUNNING"
}変数と定数が混在する JSON
抽出された値を、ハードコードされた定数、配列、および異なるデータ型と単一のテンプレートで組み合わせます。
変数:
{
"name": "$.data.name",
"state": "$.data.state"
}テンプレート:
{
"name": "${name}",
"state": [
9,
"${state}",
true
],
"Transformed": "Yes"
}出力:
{
"name": "test",
"state": [
9,
"RUNNING",
true
],
"Transformed": "Yes"
}ネストされた JSON
イベントからネストされたオブジェクトまたは配列をパススルーするには、EventBridge が生の JSON 構造を挿入するように、引用符なしで変数を参照します。
次の例では、異なるサンプルイベントを使用します。
{
"id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
"source": "acs.imm",
"specversion": "1.0",
"subject": "acs.imm:cn-hangzhou:123456789098****:215672",
"time": "2020-11-19T21:04:41+08:00",
"type": "imm:FileMeta:Index",
"aliyunaccountid": "123456789098****",
"aliyunpublishtime": "2020-11-19T21:04:42.179PRC",
"aliyuneventbusname": "default",
"aliyunregionid": "cn-hangzhou",
"aliyunpublishaddr": "172.25.XX.XX",
"data": {
"ProjectName": "test_project",
"DatasetName": "test_dataset",
"RequestId": "D2A3AE88-D17C-4CCC-B149-6651115C****",
"StartTime": "2021-07-22T14:03:15.489885+08:00",
"EndTime": "2021-07-22T14:05:15.489885+08:00",
"Message": "InvalidParameter",
"Success": false,
"Files": [
{
"URI": "oss://bucket/file",
"CustomId": "defaultId",
"CustomLabels": {
"Key1": "Val1",
"Key2": "Val2"
},
"Error": "InternalError"
}
]
}
}変数:
{
"ProjectName": "$.data.ProjectName",
"Files": "$.data.Files"
}テンプレート (${Files} は配列を参照するため引用符がありません):
{
"ProjectName": "${ProjectName}",
"Files": ${Files}
}出力:
{
"ProjectName": "test_project",
"Files": [
{
"URI": "oss://bucket/file",
"CustomId": "defaultId",
"CustomLabels": {
"Key1": "Val1",
"Key2": "Val2"
},
"Error": "InternalError"
}
]
}抽出された値が文字列の場合は "${variableName}" (引用符付き) を使用します。JSON オブジェクトまたは配列の場合は ${variableName} (引用符なし) を使用します。
エスケープ関数
EventBridge は、テンプレート変数内の特殊文字をエスケープするための2つのビルトイン関数 jsonEscape() と htmlEscape() を提供します。
jsonEscape()
JSON 文字列内の特殊文字をエスケープして、埋め込まれた文字が JSON 構造を破壊するのを防ぎます。
変数:
{
"var": "\"abc\""
}テンプレート:
{
"text": "var is ${jsonEscape(var)}"
}出力:
{
"text": "var is \"abc\""
}htmlEscape()
HTML 特殊文字をエスケープして、プレーンテキストとしてレンダリングします。イベントデータが HTML 出力に埋め込まれるときにスクリプトインジェクションを防ぐために、この関数を使用します。
変数:
{
"var": "<script>alert('unsafe');</script>"
}テンプレート:
<p>User Input: ${htmlEscape(var)}</p>出力:
<p>User Input: <script>alert('unsafe');</script></p>制限事項
| 項目 | 制限 |
|---|---|
| 部分的なイベント値の長さ | 最大10,240文字 |
| 定数値の長さ | 最大10,240文字 |
| テンプレート変数値の長さ | 最大10,240文字 |
| テンプレート値の長さ | 最大10,240文字 |
| ルールごとの部分的なイベント変数 | 1 |
| 変数定義におけるネストされた構造 | サポートされていません |
一般的な問題
| 問題 | 原因 | 解決策 |
|---|---|---|
| JSON 出力が不正です | 文字列変数が引用符なしで参照されているか、オブジェクト/配列変数が引用符付きで参照されています | 文字列には "${var}" を、オブジェクトと配列には ${var} を使用します |
| 出力で変数値が空です | JSONPath 式がイベント内のどのフィールドとも一致しません | 実際のイベント構造に対して JSONPath 式を検証します |
| 特殊文字が JSON 出力を破壊します | 変数値に、JSON 構造と競合する二重引用符などの文字が含まれています | 変数参照を jsonEscape() で囲みます: ${jsonEscape(var)} |
| HTML が挿入されたスクリプトをレンダリングします | イベントデータに、埋め込み前にエスケープされていない HTML または JavaScript が含まれています | 変数参照を htmlEscape() で囲みます: ${htmlEscape(var)} |