翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# サポートされているコンテンツタイプ: JSON、Avro、Protobuf、および raw バイト
`PutRawEvents` は任意のバイトを受け入れます。各エントリの は、バイトが何であるかを EventBridge `SystemMetadata.ContentType`に伝え、その値は EventBridge がイベントをフィルタリングして配信する前にペイロードを逆シリアル化するかどうかを決定します。Avro および Protobuf の場合、EventBridge はリクエストで名前を付けたスキーマレジストリに対してペイロードを逆シリアル化するため、サブスクライバーはイベントを JSON としてフィルタリング、変換、受信します。不透明バイトの場合、EventBridge はペイロードをそのまま配信します。
| `ContentType` | EventBridge がペイロードで行う処理 | スキーマレジストリ |
| --- | --- | --- |
| application/json | JSON コンテンツのフィルタリングと変換 | 使用されていない |
| application/avro | Avro バイナリを JSON に逆シリアル化し、その JSON でフィルタリングして変換します。 | 必須 |
| application/protobuf | Protobuf バイナリを JSON に逆シリアル化し、その JSON でフィルタリングして変換します。 | 必須 |
| application/octet-stream | ペイロードを逆シリアル化または検査しません。送信されたバイトを配信します | 使用されていない |
## EventBridge がペイロードを逆シリアル化する方法
エントリが `application/avro`または の場合`application/protobuf`、EventBridge `ContentType`はそのエントリに対して次の手順を実行します。
1. EventBridge は、レジストリのシリアライザーがペイロードバイトに書き込んだスキーマ識別子を読み取ります。
1. EventBridge は、 で名前を付けたレジストリから一致するスキーマを取得し`SchemaRegistryConfiguration.RegistryUri`、ペイロードを JSON に逆シリアル化します。スキーマが見つからないか読み取れない場合、またはペイロードを逆シリアル化できない場合、エントリはエントリごとのエラーで失敗し、リクエストの他のエントリは影響を受けません。
1. サブスクライバーがフィルターを定義すると、EventBridge はそれらを逆シリアル化された JSON に対して評価します。
1. EventBridge は、サブスクライバーの変換を逆シリアル化された JSON に適用し、JSON をターゲットに配信します。
の各`PutRawEvents`リクエストでレジストリに名前を付けます`SchemaRegistryConfiguration.RegistryUri`。設定はバスではなくリクエストに属し、EventBridge は同じリクエストの JSON エントリに対してそれを無視します。EventBridge は呼び出し元の認証情報を使用してレジストリを読み取るため、発行する ID はレジストリへの読み取りアクセスを必要とします。
逆シリアル化後、イベントは で発行された JSON イベントと同様に動作します`PutRawEvents`。の範囲を持つフィルターは、スキーマ名によって逆シリアル化されたレコードのフィールド`DATA`に一致し、JSONata トランスフォーマーはそれらを でアドレス指定し`$events.Data`、ターゲットは JSON を受け取ります。EventBridge は、配信された に 3 つのキーも設定します`SystemMetadata`。
+ `aws:SchemaId`: 逆シリアル化されたスキーマ EventBridge の識別子。Glue の AWS UUID、Confluent の整数。
+ `aws:RegistryType`: イベントをデコードしたレジストリ、`Glue`または `Confluent`。でパブリッシュされたイベントは、それを持ち込む`PutEvents`ことはありません。
+ `ContentType`: など、公開されたエントリのコンテンツタイプ`application/avro`。
## EventBridge がペイロードを配信する方法の選択
`ContentType` は 2 つの配信パスのいずれかを選択します。
+ **JSON に逆シリアル化します。**`ContentType` を `application/avro` または `application/protobuf` に設定します。EventBridge は、スキーマレジストリに対してペイロードを逆シリアル化し、サブスクライバーは でフィルタリングし`DATA`、JSONata で変換して JSON を受け取ります。スキーマエンコードされたイベントをコンテンツベースのルーティングおよび再構築する場合は、このパスを使用します。
+ **バイトをそのまま配信します。**`ContentType` を `application/octet-stream` に設定します。EventBridge はペイロードを逆シリアル化または検査せず、スキーマレジストリも関与せず、サブスクライバーは送信した正確なバイトを受け取ります。ターゲットでペイロードを逆シリアル化する場合、またはコンテンツが EventBridge が逆シリアル化しない形式である場合は、このパスを使用します。
## AWS Glue スキーマレジストリを使用した逆シリアル化
`RegistryUri` を 形式のレジストリ ARN に設定します`arn:aws:glue:{{region}}:{{account-id}}:registry/{{name}}`。公開する前に、言語の AWS Glue Schema Registry シリアライザーでペイロードをエンコードします。シリアライザーは、EventBridge がイベントの解決と逆シリアル化に使用するスキーマリファレンスを埋め込みます。
EventBridge はスキーマを公開発信者として読み取るため、公開 ID にレジストリとそのスキーマへの読み取りアクセスを許可します。次のポリシーは、1 つのレジストリにスコープされた最小限のアクセス許可を付与します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "glue:GetSchemaVersion",
"Resource": [
"arn:aws:glue:us-east-1:111122223333:registry/orders",
"arn:aws:glue:us-east-1:111122223333:schema/orders/*"
]
}
]
}
```
で Glue レジストリ ARN を使用してスキーマエンコードされたバイトを発行します`RegistryUri`。
```
aws eventsv2 put-raw-events \
--event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
--schema-registry-configuration RegistryUri=arn:aws:glue:us-east-1:111122223333:registry/orders \
--entries '[
{
"Data": "{{base64-encoded-avro-bytes}}",
"SystemMetadata": { "ContentType": "application/avro", "EventGroupId": "order-1001" }
}
]'
```
次に、サブスクライバーは逆シリアル化されたレコードをフィルタリングします。Avro スキーマに という名前のフィールドがある場合`orderId`、次のフィルターは 1 つの順序に一致します。
```
{ "Scope": "DATA", "Pattern": "{\"orderId\":[\"1001\"]}" }
```
## Confluent Schema Registry を使用した逆シリアル化
レジストリの HTTPS URL `RegistryUri`に設定します。HTTPS レジストリには`SchemaRegistryConfiguration.ConfluentPublicRegistryConfiguration.ConnectionArn`、レジストリの API キーまたは OAuth 認証情報を保持する EventBridge 接続の ARN である も必要です。接続は呼び出し元のアカウントに属している必要があります。クロスアカウント接続は拒否されます。最初の発行前に接続を作成します。パブリッシュする前に、ペイロードを言語の Confluent シリアライザーでエンコードします。シリアライザーはEventBridge がイベントの解決と逆シリアル化に使用するスキーマリファレンスを埋め込みます。
EventBridge は、名前を付けた接続を介してレジストリ認証情報を読み取ります。パブリッシュする ID に、その接続の認証情報を読み取るアクセス許可を付与します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "events:RetrieveConnectionCredentials",
"Resource": "arn:aws:events:us-east-1:111122223333:connection/confluent-registry/*"
},
{
"Effect": "Allow",
"Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
"Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:events!connection/confluent-registry/*",
"Condition": { "Bool": { "aws:ViaAWSService": "true" } }
}
]
}
```
接続シークレットがカスタマーマネージド AWS KMS キーで暗号化されている場合は、そのキー`kms:Decrypt`に対して も付与します。
Confluent URL と接続 ARN を使用してスキーマエンコードされたバイトを発行します。
```
aws eventsv2 put-raw-events \
--event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
--schema-registry-configuration '{
"RegistryUri": "https://psrc-example.us-east-1.aws.confluent.cloud",
"ConfluentPublicRegistryConfiguration": {
"ConnectionArn": "arn:aws:events:us-east-1:111122223333:connection/confluent-registry/EXAMPLE-1234-5678-abcd"
}
}' \
--entries '[
{
"Data": "{{base64-encoded-protobuf-bytes}}",
"SystemMetadata": { "ContentType": "application/protobuf" }
}
]'
```
### 接続認証オプション
Confluent レジストリが想定する認証タイプを使用して接続を設定します。EventBridge は、接続が生成する認証ヘッダーのみを読み取ります。raw シークレットは表示されず、OAuth トークンが自動的に更新されます。
**API キー。**Confluent Schema Registry は通常、スキーマレジストリ API キーをユーザー名として使用し、API シークレットをパスワードとして使用して HTTP Basic 認証を使用します。
```
aws events create-connection \
--name confluent-registry \
--authorization-type API_KEY \
--auth-parameters '{
"ApiKeyAuthParameters": {
"ApiKeyName": "Authorization",
"ApiKeyValue": "Basic {{base64(srApiKey:srApiSecret)}}"
}
}'
```
**OAuth クライアントの認証情報。**EventBridge はトークンを取得して更新します。本文パラメータ`grant_type=client_credentials`として を含める必要があります。EventBridge では追加されません。
```
aws events create-connection \
--name confluent-registry-oauth \
--authorization-type OAUTH_CLIENT_CREDENTIALS \
--auth-parameters '{
"OAuthParameters": {
"AuthorizationEndpoint": "https://{{idp-domain}}/oauth/token",
"HttpMethod": "POST",
"ClientParameters": {
"ClientID": "{{oauth-client-id}}",
"ClientSecret": "{{oauth-client-secret}}"
},
"OAuthHttpParameters": {
"BodyParameters": [
{ "Key": "grant_type", "Value": "client_credentials", "IsValueSecret": false }
]
}
}
}'
```
EventBridge は、ユーザーに代わって接続が読み取るマネージド Secrets Manager シークレット (`events!connection/...`) にいずれかの認証情報を保存します。
## 逆シリアル化せずにバイトを配信する
EventBridge が送信されたペイロードとまったく同じようにペイロードを配信するには、エントリの を `SystemMetadata.ContentType` に設定します`application/octet-stream`。これは各エントリのフィールドであり、HTTP ヘッダーではありません。EventBridge はバイトを逆シリアル化または検査せず、スキーマレジストリも関係しないため、ターゲットで逆シリアル化する Avro や Protobuf など、あらゆる形式が機能します。コンテンツは不透明であるため、`DATA`フィルターは一致できません。このようなイベントは`METADATA`、 のフィルター、エントリの`Metadata`マップで設定したキー、または でルーティングします`SYSTEM_METADATA`。コンテンツベースの重複排除は引き続き機能し、送信したとおりにバイトをハッシュします。トランスフォーマーでは、ペイロードは Base64 文字列として表示されます。「」を参照してください[JSONata を使用したイベントの変換](eb-custom-bus-transform.md)。
## 逆シリアル化されたイベントのフィルタリングと変換
EventBridge がイベントを JSON に逆シリアル化すると、ペイロードは通常のパイプラインを流れます。スコープが のフィルターは、スキーマ名によって逆シリアル化されたフィールド`DATA`に一致し、JSONata トランスフォーマーは でそれらに対処します`$events.Data`。Avro または Protobuf として公開されたイベントは、プレーン JSON として公開されたイベントと同じコンテンツベースのルーティングとサブスクライブごとの再構成を取得します。2 つの変換ルールを念頭に置いて、逆シリアル化された JSON に対してフィルターパターンを記述します。
+ **Avro** は標準 JSON に逆シリアル化します。変換は一方向です。JSON を Avro オブジェクトに戻すことはできません。
+ **Protobuf** は通常、Protobuf ツールのようにキャメルケースに変換するのではなく、スキーマで定義されたフィールド名を使用して JSON に逆シリアル化します。スキーマフィールド名を一致させます。
## 形式間のイベントの重複排除
EventBridge は、エントリ`DeduplicationId`で を指定する ID ベースと、EventBridge がイベントコンテンツの SHA-256 ハッシュを計算するコンテンツベースの 2 つの重複排除モードをサポートしています。逆シリアル化されたイベントの場合、コンテンツベースの重複排除は、逆シリアル化された JSON ではなく、元の Avro または Protobuf ワイヤバイトをハッシュします。元のペイロードがバイト同一である場合にのみ、2 つのイベントが重複します。したがって、異なる形式で発行された同じ論理イベントは重複排除されません。Avro バイト、Protobuf バイト、raw JSON は、同じデータに逆シリアル化されてもワイヤ上で異なります。「[カスタムイベントバスでのイベントの順序付けと重複排除](eb-custom-bus-ordering.md)」を参照してください。
## エラー
+ なしで公開された Avro または Protobuf エントリは、 `ErrorCode` が のエントリごとのエラーとして`SchemaRegistryConfiguration`失敗`VALIDATION_ERROR`し、 というメッセージが表示されます`SchemaRegistryConfiguration is required`。リクエスト内の他のエントリは影響を受けません。
+ 使用可能な接続に名前`ConnectionArn`を付けない、または別のアカウントに属する は、 `VALIDATION_ERROR`とレジストリに名前を付けるメッセージを使用してエントリに失敗します。
+ 検出または読み取りできないスキーマ、またはそれに対して逆シリアル化できないペイロードは、 でそのエントリに失敗します`VALIDATION_ERROR`。このエラーは再試行できません。再発行する前にリクエストまたは呼び出し元のレジストリアクセスを修正してください。
+ 到達できないレジストリは、 のリクエストに失敗します`SchemaRegistryUnavailableException`。Confluent OAuth パスでは、レジストリアクセストークンの更新中にこれが発生する可能性があります。このエラーは一時的なものです。バックオフでリクエストを再試行します。
エントリごとの結果と再試行の一般的なガイダンスについては、「」を参照してください[カスタムイベントバスへのイベントの発行](eb-custom-bus-publish.md)。