使用二進位承載 - AWS IoT Core
二進位承載範例對 Protobuf 訊息承載進行解碼

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

使用二進位承載

若要以原始二進位資料 （而非JSON物件） 處理訊息承載，您可以使用 * 運算子在 SELECT 子句中加以參考。

二進位承載範例

使用 * 參考作為原始二進位資料的訊息承載時，您可以將資料新增至規則。如果您有空白或JSON承載，則產生的承載可以使用 規則新增資料。下列顯示支援 SELECT 子句的範例。

  • 對於二進位承載，您可以使用下方僅具有一個 * 的 SELECT 子句。

    • SELECT * FROM 'topic/subtopic'
    • SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0

  • 您也可以新增資料並使用下方 SELECT 子句。

    • SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
    • SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'

  • 您也可以使用這些 SELECT 子句搭配二進位承載使用。

    • 下列在 WHERE子句device_type中參考 。

      SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'

    • 也支援下方項目。

      {
	"sql": "SELECT * FROM 'topic/subtopic'",
	"actions": [
		{
			"republish": {
				"topic": "device/${device_id}"
			}
		}
	]
}

下方規則動作不支援二進位承載，因此您必須將它們解碼。

  • 對於某些不支援二進位承載輸入 (例如 Lambda 動作) 的規則，您必須解碼二進位承載。如果 Lambda 規則動作是 base64 編碼且位於JSON承載中，則它可以接收二進位資料。您可以將規則變更如下，以此執行此項操作。

    SELECT encode(*, 'base64') AS data FROM 'my_topic'

  • SQL 陳述式不支援字串做為輸入。若要將字串輸入轉換為 JSON，您可以執行下列命令。

    SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'

對 Protobuf 訊息承載進行解碼

協定緩衝區（protobuf）是一種開放原始碼資料格式，用於將結構化資料序列化為壓縮二進位形式。其可用於透過網路傳輸資料或將其儲存在檔案中。Protobuf 可讓您以小封包大小並以比其他訊息格式更快的速度傳送資料。 AWS IoT Core Rules 支援 protobuf，方法是提供 decode(value， decodingScheme) SQL函數，可讓您解碼 protobuf 編碼的訊息承載，以JSON格式化並將它們路由至下游服務。本節詳細說明在 step-by-step 規則中 AWS IoT Core 設定 protobuf 解碼的程序。

必要條件

建立描述項檔案

如果您已有描述項檔案，則可以略過此步驟。描述項檔案 (.desc) 是 .proto 檔案的編譯版本，屬於文字檔案，用於定義在 protobuf 序列化中使用的資料結構和訊息類型。要產生描述項檔案，您必須定義 .proto 檔案並使用 protoc 編譯器對其進行編譯。

  1. 建立用於定義訊息類型的 .proto 檔案。範例 .proto 檔案看起來可能與以下內容相似：

    syntax = "proto3";

message Person {
  optional string name = 1;
  optional int32 id = 2;
  optional string email = 3;
}

    在此範例 .proto 檔案中，您使用 proto3 語法並定義訊息類型 Person。Person 訊息定義會指定三個欄位 (名稱、ID 和電子郵件)。如需有關 .proto 檔案訊息格式的詳細資訊，請參閱 語言指南 (proto3)。

  2. 使用 protoc 編譯器編譯 .proto 檔案並產生描述項檔案。用於建立描述項 (.desc) 檔案的範例命令如下所示：

    protoc --descriptor_set_out=<FILENAME>.desc \
    --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \
    --include_imports \
    <PROTO_FILENAME>.proto

    此範例命令會產生描述項檔案 <FILENAME>.desc，該 AWS IoT Core 檔案 規則可用來解碼符合 中定義之資料結構的 protobuf 承載<PROTO_FILENAME>.proto。

    • --descriptor_set_out

      指定所要產生的描述項檔案 (<FILENAME>.desc) 名稱。

    • --proto_path

      指定編譯檔案所參考的任何已匯入 .proto 檔案的位置。如果您有多項已匯入的 .proto 檔案位於不同位置，則可以多次指定旗標。

    • --include_imports

      指定任何已匯入的 .proto 檔案也應加以編譯，並納入 <FILENAME>.desc 描述項檔案中。

    • <PROTO_FILENAME>.proto

      指定要編譯的 .proto 檔案名稱。

    如需 protoc 參考的詳細資訊，請參閱API參考。

將描述項檔案上傳至 S3 儲存貯體

建立描述項檔案 之後<FILENAME>.desc，請使用 AWS API AWS SDK或 將描述項檔案上傳至 Amazon S3 <FILENAME>.desc儲存貯體 AWS Management Console。

重要考量

  • 請確定您上傳描述項檔案到 中的 Amazon S3 儲存貯 AWS 帳戶 體，與您打算設定規則 AWS 區域 的相同。

  • 請確定您授予從 FileDescriptorSet S3 讀取 的 AWS IoT Core 存取權。如果您的 S3 儲存貯體已停用伺服器端加密 (SSE)，或者您的 S3 儲存貯體使用 Amazon S3-managed金鑰 (SSE-S3) 加密，則不需要其他政策組態。下列範例儲存貯體政策可實現此目的：

    {
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "Statement1",
			"Effect": "Allow",
			"Principal": {
				"Service": "iot.amazonaws.com"
			},
			"Action": "s3:Get*",
                      "Resource": "arn:aws:s3:::<BUCKET NAME>/<FILENAME>.desc"
		}
	]
}

  • 如果您的 S3 儲存貯體使用 AWS Key Management Service 金鑰 (SSE-KMS) 加密，請務必在存取 S3 儲存貯體時授予使用金鑰的 AWS IoT Core 許可。作法為您可以將下列陳述式新增至金鑰政策：

    {
	"Sid": "Statement1",
	"Effect": "Allow",
	"Principal": {
		"Service": "iot.amazonaws.com"
	},
	"Action": [
		"kms:Decrypt",
		"kms:GenerateDataKey*",
		"kms:DescribeKey"
	],
        "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
	
}

在規則中設定 protobuf 解碼

將描述項檔案上傳至 Amazon S3 儲存貯體後，請設定規則，使用 decode(value， decodingScheme) SQL函數解碼 protobuf 訊息承載格式。您可以在AWS IoT SQL參考的 decode(value， decodingScheme) SQL函數中找到詳細的函數簽章和範例。

以下是使用 decode(value， decodingScheme) 函數的範例SQL表達式：

SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'

在此範例表達式中：

  • 您可以使用 decode(value， decodingScheme) SQL函數來解碼 參考的二進位訊息承載*。這可以是二進位 protobuf 編碼承載，或代表 base64 編碼 protobuf 承載的JSON字串。

  • 所提供的訊息承載會使用 PROTO_FILENAME.proto 中定義的Person 訊息類型進行編碼。

  • 名為 BUCKET NAME 的 Amazon S3 儲存貯體含有從 PROTO_FILENAME.proto 產生的 FILENAME.desc。

完成組態後，請在規則訂閱的主題 AWS IoT Core 上發佈訊息至 。

限制

AWS IoT Core 規則支援具有下列限制的 protobuf：

  • 不支援在替代範本中解碼 protobuf 訊息承載。

  • 解碼 protobuf 訊息承載時，您可以在單一SQL表達式內使用解碼SQL函數最多兩次。

  • 傳入承載大小上限為 128 KiB (1KiB = 1024 位元組)，傳出承載大小上限為 128 KiB，而儲存在 Amazon S3 儲存貯體中的 FileDescriptorSet 物件大小上限為 32 KiB。

  • 不支援使用 SSE-C 加密加密的 Amazon S3 儲存貯體。

最佳實務

以下是一些最佳實務和疑難排解提示。

  • 在 Amazon S3 儲存貯體中備份原型檔案。

    理想的做法是備份 proto 檔案以防患未然。例如，如果在執行 protoc 時錯誤地修改了沒有備份的原型檔案，這可能會導致生產堆疊發生問題。有多種方法在 Amazon S3 儲存貯體中備份檔案 例如，您可以在 S3 儲存貯體中使用版本控制。如需有關如何備份 Amazon S3 儲存貯體中檔案的詳細資訊，請參閱 Amazon S3 開發人員指南。

  • 設定 AWS IoT 記錄以檢視日誌項目。

    設定 AWS IoT 記錄是很好的做法，以便您可以檢查 中帳戶的 AWS IoT 日誌 CloudWatch。當規則的SQL查詢呼叫外部 函數時， AWS IoT Core Rules 會產生具有 eventType的 日誌項目FunctionExecution，其中包含可協助您故障診斷的原因欄位。可能的錯誤包括找不到 Amazon S3 物件，或是 protobuf 檔案描述項無效。如需進一步了解如何設定 AWS IoT 記錄及查看日誌項目，請參閱設定 AWS IoT 記錄和規則引擎日誌項目。

  • 使用新的物件索引鍵來更新 FileDescriptorSet 以及更新規則中的物件索引鍵。

    您可以將更新後的描述項檔案上傳到 Amazon S3 儲存貯體來更新 FileDescriptorSet。系統可能需要最多 15 分鐘的時間來反映 FileDescriptorSet 的更新作業。為了避免這種延遲，理想做法是使用新的物件索引鍵上傳更新後的 FileDescriptorSet，並在規則中更新物件索引鍵。