本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon SQS 的訊息中繼資料
<a name="sqs-message-metadata"></a>

使用訊息屬性為您的應用程式將自訂中繼資料新增至 Amazon SQS 訊息。使用訊息系統屬性來存放中繼資料以與其他 整合 AWS 服務，例如 AWS X-Ray。

## Amazon SQS 訊息屬性
<a name="sqs-message-attributes"></a>

Amazon SQS 可讓您使用訊息*屬性*，在訊息中包含結構化中繼資料 （例如時間戳記、地理空間資料、簽章和識別符）。每則訊息可以擁有多達 10 個屬性。訊息屬性為選用且與訊息內文分開 (但與訊息內文一起傳送)。您的消費者可以使用訊息屬性以特定方式處理訊息，而不必先處理訊息內文。如需使用 Amazon SQS 主控台以屬性傳送訊息的資訊，請參閱 [使用 Amazon SQS 傳送具有屬性的訊息](sqs-using-send-message-with-attributes.md)。

**注意**  
不要將訊息屬性與*訊息系統屬性*混淆：雖然您可以使用訊息屬性將自訂中繼資料連接至應用程式的 Amazon SQS 訊息，但您可以使用[訊息系統屬性](#sqs-message-system-attributes)來存放其他服務的中繼資料 AWS ，例如 AWS X-Ray。

**Topics**
+ [訊息屬性元件](#message-attribute-components)
+ [訊息屬性資料類型](#message-attribute-data-types)
+ [計算訊息屬性的 MD5 訊息摘要](#sqs-attributes-md5-message-digest-calculation)

### 訊息屬性元件
<a name="message-attribute-components"></a>

**重要**  
訊息屬性的所有元件都包含在 1 MiB 訊息大小限制中。  
`Name`、`Type`、`Value` 和訊息內文不能為空或 null。

每項訊息屬性均是由以下元件組成：
+ **名稱** – 訊息屬性名稱可包含以下字元：`A`-`Z`、`a`-`z`、`0`-`9`、底線 (`_`)、連字號 (`-`) 和句點 (`.`)。適用以下限制：
  + 長度上限為 256 個字元
  + 開頭不能是 `AWS.` 或 `Amazon.` (或任何大小寫變化)
  + 區分大小寫
  + 在訊息的所有屬性名稱中必須是唯一的
  + 開頭或結尾不能是句號
  + 序列中不能有句號
+ **類型** – 訊息屬性資料類型。支援的類型包括 `String`、`Number` 和 `Binary`。您也可以新增任何資料類型的自訂資訊。資料類型具有與訊息內文相同的限制 （如需詳細資訊，請參閱《*Amazon Simple Queue Service API 參考*`[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)`》中的 )。此外，適用下列限制：
  + 長度上限為 256 個字元
  + 區分大小寫
+ **值** – 訊息屬性值。若為 `String` 資料類型，屬性值的限制與訊息內文相同。

### 訊息屬性資料類型
<a name="message-attribute-data-types"></a>

訊息屬性資料類型指定 Amazon SQS 如何處理對應的訊息屬性值。例如，如果類型是 `Number`，Amazon SQS 會驗證數值。

Amazon SQS 支援邏輯資料類型 `String`、`Number` 和 `Binary`，搭配格式為 `.custom-data-type` 的選用自訂類型標籤
+ **字串** – `String` 屬性可以使用任何有效的 XML 字元儲存 Unicode 文字。
+ **數字** - `Number` 屬性可以存放正或負的數值。數字的精準度最多可達 38 位數，可介於 10^-128 至 10^\$1126 之間。
**注意**  
Amazon SQS 會移除前置和結尾的零。
+ **二進位** – 二進位屬性可儲存任何二進位資料，例如壓縮資料、加密資料或影像。
+ **自訂** – 若要建立自訂資料類型，請將自訂類型標籤附加到任何資料類型。例如：
  + `Number.byte`、`Number.short`、`Number.int` 和 `Number.float` 可協助區分數字類型。
  + `Binary.gif` 和 `Binary.png` 可協助區分檔案類型。
**注意**  
Amazon SQS 不會解譯、驗證或使用附加的資料。  
自訂類型標籤的限制與訊息內文相同。

### 計算訊息屬性的 MD5 訊息摘要
<a name="sqs-attributes-md5-message-digest-calculation"></a>

如果您使用 適用於 Java 的 AWS SDK，則可以略過本節。適用於 Java 的開發套件的 `MessageMD5ChecksumHandler` 類別支援 Amazon SQS 訊息屬性的 MD5 訊息摘要。

如果您使用查詢 API 或其中一個不支援 Amazon SQS 訊息屬性的 MD5 訊息摘要的 AWS SDKs，您必須使用下列準則來執行 MD5 訊息摘要計算。

**注意**  
在 MD5 訊息摘要計算中一律包含自訂資料類型尾碼。

#### 概觀
<a name="attributes-md5-message-digest-calculation-overview"></a>

以下概述 MD5 訊息摘要計算演算法：

1. 以遞增順序根據名稱排列所有訊息屬性。

1. 將各屬性 (`Name`、`Type` 和 `Value`) 的個別部分編碼至緩衝區。

1. 運算整個緩衝區的訊息摘要。

下圖顯示的是單一訊息屬性的 MD5 訊息摘要編碼：

![\[單一訊息屬性的 MD5 訊息摘要編碼。\]](http://docs.aws.amazon.com/zh_tw/AWSSimpleQueueService/latest/SQSDeveloperGuide/images/sqs-msg-attrib-md5.png)


#### 若要對單個 Amazon SQS 訊息屬性進行編碼
<a name="attributes-md5-message-digest-calculation-encode-single-attribute"></a>

1. 編碼名稱：長度 (4 個位元組) 和名稱的 UTF-8 位元組。

1. 編碼資料類型：長度 (4 個位元組) 和資料類型的 UTF-8 位元組。

1. 編碼值的傳輸類型 (`String` 或 `Binary`) (1 個位元組)。
**注意**  
`String` 和 `Number` 的邏輯資料類型使用 `String` 傳輸類型。  
`Binary` 邏輯資料類型使用 `Binary` 傳輸類型。

   1. 若為 `String` 傳輸類型，為編碼 1。

   1. 若為 `Binary` 傳輸類型，為編碼 2。

1. 為屬性值編碼。

   1. 若為 `String` 傳輸類型，請編碼屬性值：長度 (4 個位元組) 和值的 UTF-8 位元組。

   1. 若為 `Binary` 傳輸類型，請編碼屬性值：長度 (4 個位元組) 和值的原始位元組。

## Amazon SQS 訊息系統屬性
<a name="sqs-message-system-attributes"></a>

雖然您可以使用[訊息屬性](#sqs-message-attributes)將應用程式的自訂中繼資料連接到 Amazon SQS 訊息，但您仍可以使用*訊息系統屬性*來存放 AWS X-Ray等其他 AWS 服務的中繼資料。如需詳細資訊，請參閱 `[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)`和 `[SendMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)` API 動作的`MessageSystemAttribute`請求參數、`[ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)`API 動作的`AWSTraceHeader`屬性，以及 *Amazon Simple Queue Service API 參考*中的`[MessageSystemAttributeValue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_MessageSystemAttributeValue.html)`資料類型。

訊息系統屬性的結構與訊息屬性完全相同，但下列屬性除外：:
+ 目前，唯一支援的訊息系統屬性是 `AWSTraceHeader`。其類型必須為 `String`，且其值必須是格式正確的 AWS X-Ray 追蹤標頭字串。
+ 訊息系統屬性的大小不會計入訊息的總大小。