本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 支援的內容類型：JSON、Avro、Protobuf 和原始位元組
`PutRawEvents` 接受任何位元組。每個項目的 都會`SystemMetadata.ContentType`告知 EventBridge 位元組是什麼，該值會決定 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 如何還原序列化承載
當項目的 `ContentType`是 `application/avro`或 時`application/protobuf`，EventBridge 會針對該項目執行下列步驟。
1. EventBridge 會讀取登錄序列化程式寫入承載位元組的結構描述識別符。
1. EventBridge 會從您在 中命名的登錄檔擷取相符的結構描述`SchemaRegistryConfiguration.RegistryUri`，並將承載還原序列化至 JSON。如果找不到或無法讀取結構描述，或承載無法對其還原序列化，則項目會失敗，並出現每個項目錯誤，且請求中的其他項目不會受到影響。
1. 如果訂閱者定義篩選條件，EventBridge 會根據還原序列化 JSON 來評估篩選條件。
1. EventBridge 會將訂閱者的轉換套用至還原序列化 JSON，並將 JSON 交付至目標。
您可以在 中為每個`PutRawEvents`請求命名登錄檔`SchemaRegistryConfiguration.RegistryUri`。設定屬於請求，而不是匯流排，EventBridge 會忽略相同請求中的 JSON 項目。EventBridge 會使用發起人的登入資料讀取登錄檔，因此發佈的身分需要登錄檔的讀取存取權。
還原序列化後，事件的行為類似於使用 發佈的任何 JSON 事件`PutRawEvents`。篩選條件的範圍符合依結構描述名稱的還原序列化記錄`DATA`欄位，JSONata 轉換器會在 下處理它們`$events.Data`，而目標會收到 JSON。EventBridge 也會在交付的 中設定三個金鑰`SystemMetadata`。
+ `aws:SchemaId`：結構描述 EventBridge 已還原序列化的識別符；Glue 的 AWS UUID，Confluent 的整數。
+ `aws:RegistryType`：解碼事件的登錄檔，`Glue`或 `Confluent`。使用 發佈的事件`PutEvents`永遠不會攜帶它。
+ `ContentType`：已發佈項目的內容類型，例如 `application/avro`。
## 選擇 EventBridge 如何交付您的承載
`ContentType` 選取兩個交付路徑的其中一個。
+ **取消序列化為 JSON。**將 `ContentType` 設為 `application/avro` 或 `application/protobuf`。EventBridge 會根據您的結構描述登錄檔還原序列化承載，並在 上篩選訂閱者`DATA`、使用 JSONata 轉換，以及接收 JSON。當您想要以內容為基礎的路由和重塑結構描述編碼的事件時，請使用此路徑。
+ **交付未修補的位元組。**將 `ContentType` 設定為 `application/octet-stream`。EventBridge 不會還原序列化或檢查承載，不會涉及結構描述登錄檔，訂閱者會收到您傳送的確切位元組。當您在目標還原序列化承載，或內容是 EventBridge 不會還原序列化的格式時，請使用此路徑。
## 使用 Glue AWS 結構描述登錄檔還原序列化
`RegistryUri` 設定為 形式的登錄檔 ARN`arn:aws:glue:{{region}}:{{account-id}}:registry/{{name}}`。在發佈之前，使用您語言的 AWS Glue 結構描述登錄檔序列化程式來編碼承載；序列化程式會內嵌 EventBridge 用來解析和還原序列化事件的結構描述參考。
EventBridge 會將結構描述讀取為發佈發起人，因此請將發佈身分讀取存取權授予登錄檔及其結構描述。下列政策會授予範圍限定為一個登錄檔的最低許可。
```
{
"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`，則下列篩選條件符合一個順序。
```
{ "Scope": "DATA", "Pattern": "{\"orderId\":[\"1001\"]}" }
```
## 使用 Confluent 結構描述登錄檔還原序列化
`RegistryUri` 設定為登錄檔的 HTTPS URL。HTTPS 登錄檔也需要 `SchemaRegistryConfiguration.ConfluentPublicRegistryConfiguration.ConnectionArn`，即保留登錄檔 API 金鑰或 OAuth 登入資料的 EventBridge 連線 ARN。連線必須屬於呼叫帳戶；跨帳戶連線會遭到拒絕。在第一次發佈之前建立連線。在發佈之前，使用 Confluent 序列化程式為您的語言編碼承載；序列化程式會內嵌 EventBridge 用來解析和還原序列化事件的結構描述參考。
EventBridge 會透過您命名的連線讀取登錄檔登入資料。授予發佈身分許可，以讀取該連線的登入資料。
```
{
"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 只會讀取連線產生的身分驗證標頭；它永遠不會看到原始秘密，而且會自動重新整理 OAuth 權杖。
**API 金鑰。**Confluent 結構描述登錄檔通常會使用 HTTP 基本身分驗證搭配結構描述登錄檔 API 金鑰做為使用者名稱，並使用 API 秘密做為密碼。
```
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 的事件相同的內容型路由和每個訂閱者重塑。針對還原序列化 JSON 寫入篩選條件模式，並謹記兩個轉換規則。
+ **Avro** 還原序列化為標準 JSON。轉換是單向：JSON 無法轉換回 Avro 物件。
+ **Protobuf** 會使用結構描述中定義的欄位名稱還原序列化為 JSON，而不是像 Protobuf 工具一般將其轉換為駱駝案例。結構描述欄位名稱相符。
## 跨格式刪除重複事件
EventBridge 支援兩種重複資料刪除模式：以 ID 為基礎，您可以在項目`DeduplicationId`上提供 ，以內容為基礎，EventBridge 會計算事件內容的 SHA-256 雜湊。對於還原序列化事件，內容型重複資料刪除會雜湊原始 Avro 或 Protobuf 線路位元組，而不是還原序列化 JSON。只有當兩個事件的原始承載是位元組相同時，才會重複。因此，不會刪除以不同格式發佈的相同邏輯事件：Avro 位元組、Protobuf 位元組和原始 JSON 在線路上不同，即使它們還原序列化為相同的資料。請參閱 [在自訂事件匯流排上排序和刪除重複事件](eb-custom-bus-ordering.md)。
## 錯誤
+ 發佈的 Avro 或 Protobuf 項目沒有`SchemaRegistryConfiguration`失敗，因為每個項目錯誤具有 `ErrorCode` 的 `VALIDATION_ERROR`和陳述 的訊息`SchemaRegistryConfiguration is required`。請求中的其他項目不受影響。
+ `ConnectionArn` 不命名為可用連線或屬於另一個帳戶的 會失敗項目，`VALIDATION_ERROR`並顯示名稱為登錄的訊息。
+ 找不到或無法讀取的結構描述，或無法對其還原序列化的承載，會使用 使該項目失敗`VALIDATION_ERROR`。此錯誤無法重試；請在重新發佈之前修正請求或發起人的登錄檔存取。
+ 無法到達的登錄檔會失敗 的請求`SchemaRegistryUnavailableException`。在 Confluent OAuth 路徑上，這可能會在重新整理登錄檔存取字符時發生。此錯誤是暫時性的；使用退避重試請求。
如需每個項目的結果和一般重試指引，請參閱 [將事件發佈至自訂事件匯流排](eb-custom-bus-publish.md)。