支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Kinesis Firehose Kinesis Firehose [連接器](connectors.md)會透過 Amazon Data Firehose 交付串流將資料發佈至目的地，例如 Amazon S3、Amazon Redshift 或 Amazon OpenSearch Service。 此連接器是 Kinesis 交付串流的資料生產者。它會接收 MQTT 主題上的輸入資料，然後將資料傳送到指定的交付串流。然後，交付串流會將資料記錄傳送到設定的目的地 (例如，S3 儲存貯體)。 此連接器具有下列版本。 | 版本 | ARN | | --- | --- | | 5 | `arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/5` | | 4 | `arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/4` | | 3 | `arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/3` | | 2 | `arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/2` | | 1 | `arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/1` | 如需版本變更的詳細資訊，請參閱 [Changelog](#kinesis-firehose-connector-changelog)。 ## 要求 此連接器有下列要求： ------ #### [ Version 4 - 5 ] + AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。 **注意** 若要使用 Python 3.8，請執行下列命令，以建立從預設 Python 3.7 安裝資料夾到已安裝 Python 3.8 二進位檔的符號連結。 ``` sudo ln -s {{path-to-python-3.8}}/python3.8 /usr/bin/python3.7 ``` 這會設定您的裝置以符合 AWS IoT Greengrass的 Python 需求。 + 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose * + [Greengrass 群組角色](group-role.md)設定為允許目標交付串流上的 `firehose:PutRecord`和 `firehose:PutRecordBatch`動作，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1528133056761", "Action":[ "firehose:PutRecord", "firehose:PutRecordBatch" ], "Effect":"Allow", "Resource":[ "arn:aws:firehose:{{us-east-1}}:{{123456789012}}:deliverystream/{{stream-name}}" ] } ] } ``` ------ 此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \* 命名配置)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 ------ #### [ Versions 2 - 3 ] + AWS IoT Greengrass 核心軟體 1.7 版或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。 + 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose * + 設定為允許目標交付串流上 `firehose:PutRecord`和 `firehose:PutRecordBatch`動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1528133056761", "Action":[ "firehose:PutRecord", "firehose:PutRecordBatch" ], "Effect":"Allow", "Resource":[ "arn:aws:firehose:{{us-east-1}}:{{123456789012}}:deliverystream/{{stream-name}}" ] } ] } ``` ------ 此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \* 命名配置)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 ------ #### [ Version 1 ] + AWS IoT Greengrass 核心軟體 1.7 版或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。 + 設定的 Kinesis 交付串流。如需詳細資訊，請參閱[《Amazon Kinesis Firehose 開發人員指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 *Amazon Kinesis Firehose * + 設定為允許對目標交付串流`firehose:PutRecord`執行動作的 [Greengrass 群組角色](group-role.md)，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1528133056761", "Action":[ "firehose:PutRecord" ], "Effect":"Allow", "Resource":[ "arn:aws:firehose:{{us-east-1}}:{{123456789012}}:deliverystream/{{stream-name}}" ] } ] } ``` ------ 此連接器可讓您動態覆寫輸入訊息承載中的預設交付串流。如果您的實作使用此功能，IAM 政策應包含所有目標串流做為資源。您可以為資源授予細微或條件式存取 (例如，使用萬用字元 \* 命名配置)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 ------ ## 連接器參數 此連接器提供下列參數： ------ #### [ Versions 5 ] `DefaultDeliveryStreamArn` 要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。 群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。 在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN** 必要：`true` 類型：`string` 有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$` `DeliveryStreamQueueSize` 同樣交付串流的新記錄遭拒絕前，記憶體中保留的記錄數上限。最小值為 2000。 在 AWS IoT 主控台中顯示名稱：**要緩衝的記錄數量上限 （每個串流）** 必要：`true` 類型：`string` 有效模式： `^([2-9]\\d{3}|[1-9]\\d{4,})$` `MemorySize` 配置給此連接器的記憶體數量 (KB)。 AWS IoT 主控台中的顯示名稱：**記憶體大小** 必要：`true` 類型：`string` 有效模式： `^[0-9]+$` `PublishInterval` 將記錄發佈至 Firehose 的間隔 （以秒為單位）。若要停止批次處理，請將此數值設為 0。 在 AWS IoT 主控台中顯示名稱：**發佈間隔** 必要：`true` 類型：`string` 有效值：`0 - 900` 有效模式： `[0-9]|[1-9]\\d|[1-9]\\d\\d|900` `IsolationMode` 此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。 群組的預設容器化設定不會套用至連接器。 在 AWS IoT 主控台中顯示名稱：**容器隔離模式** 必要：`false` 類型：`string` 有效值：`GreengrassContainer` 或 `NoContainer` 有效模式： `^NoContainer$|^GreengrassContainer$` ------ #### [ Versions 2 - 4 ] `DefaultDeliveryStreamArn` 要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。 群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。 在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN** 必要：`true` 類型：`string` 有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$` `DeliveryStreamQueueSize` 同樣交付串流的新記錄遭拒絕前，記憶體中保留的記錄數上限。最小值為 2000。 在 AWS IoT 主控台中顯示名稱：**要緩衝的記錄數目上限 （每個串流）** 必要：`true` 類型：`string` 有效模式： `^([2-9]\\d{3}|[1-9]\\d{4,})$` `MemorySize` 配置給此連接器的記憶體數量 (KB)。 AWS IoT 主控台中的顯示名稱：**記憶體大小** 必要：`true` 類型：`string` 有效模式： `^[0-9]+$` `PublishInterval` 將記錄發佈至 Firehose 的間隔 （以秒為單位）。若要停止批次處理，請將此數值設為 0。 在 AWS IoT 主控台中顯示名稱：**發佈間隔** 必要：`true` 類型：`string` 有效值：`0 - 900` 有效模式： `[0-9]|[1-9]\\d|[1-9]\\d\\d|900` ------ #### [ Version 1 ] `DefaultDeliveryStreamArn` 要傳送資料之預設 Firehose 交付串流的 ARN。輸入訊息承載中的 `delivery_stream_arn` 屬性可以覆寫目的地串流。 群組角色必須允許所有目標交付串流上的適當動作。如需詳細資訊，請參閱[要求](#kinesis-firehose-connector-req)。 在 AWS IoT 主控台中顯示名稱：**預設交付串流 ARN** 必要：`true` 類型：`string` 有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$` ------ **Example** **建立連接器範例 (AWS CLI)** 下列 CLI 命令`ConnectorDefinition`會使用包含連接器的初始版本來建立 。 ``` aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyKinesisFirehoseConnector", "ConnectorArn": "arn:aws:greengrass:{{region}}::/connectors/KinesisFirehose/versions/5", "Parameters": { "DefaultDeliveryStreamArn": "arn:aws:firehose:{{region}}:{{account-id}}:deliverystream/stream-name", "DeliveryStreamQueueSize": "5000", "MemorySize": "65535", "PublishInterval": "10", "IsolationMode" : "GreengrassContainer" } } ] }' ``` 在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。 ## 輸入資料 此連接器接受 MQTT 主題上的串流內容，然後將內容傳送到目標交付串流。它接受兩種輸入資料： + `kinesisfirehose/message` 主題上的 JSON 資料。 + `kinesisfirehose/message/binary/#` 主題上的二進位資料。 ------ #### [ Versions 2 - 5 ] **主題篩選條件：** `kinesisfirehose/message` 使用此主題傳送包含 JSON 資料的訊息。 **訊息屬性** `request` 要傳送到交付串流和目標交付串流 (如果與預設串流不同) 的資料。 必要：`true` 類型：`object`包含下列屬性： `data` 要傳送到交付串流的資料。 必要：`true` 類型：`string` `delivery_stream_arn` 目標 Kinesis 交付串流的 ARN。包含此屬性來覆寫預設的交付串流。 必要：`false` 類型：`string` 有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$` `id` 請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果您不使用此功能，您可以省略此屬性或指定空白字串。 必要：`false` 類型：`string` 有效模式： `.*` **範例輸入** ``` { "request": { "delivery_stream_arn": "arn:aws:firehose:{{region}}:{{account-id}}:deliverystream/stream2-name", "data": "Data to send to the delivery stream." }, "id": "request123" } ```   **主題篩選條件：** `kinesisfirehose/message/binary/#` 使用此主題傳送包含二進位資料的訊息。連接器不剖析二進位資料。資料會依現狀串流。 若要將輸入請求映射到輸出回應，請將訊息主題中的 `#` 萬用字元換成任意請求 ID。例如，如果您將訊息發佈到 `kinesisfirehose/message/binary/request123`，回應物件中的 `id` 屬性會設為 `request123`。 如果您不想將請求映射到回應，您可以將訊息發佈到 `kinesisfirehose/message/binary/`。請務必包含結尾的斜線。 ------ #### [ Version 1 ] **主題篩選條件：** `kinesisfirehose/message` 使用此主題傳送包含 JSON 資料的訊息。 **訊息屬性** `request` 要傳送到交付串流和目標交付串流 (如果與預設串流不同) 的資料。 必要：`true` 類型：`object`包含下列屬性： `data` 要傳送到交付串流的資料。 必要：`true` 類型：`string` `delivery_stream_arn` 目標 Kinesis 交付串流的 ARN。包含此屬性來覆寫預設的交付串流。 必要：`false` 類型：`string` 有效模式： `arn:aws:firehose:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):deliverystream/([a-zA-Z0-9_\-.]+)$` `id` 請求的任意 ID。此屬性用於將輸入請求映射到輸出回應。當指定時，回應物件中的 `id` 屬性會設為這個值。如果您不使用此功能，您可以省略此屬性或指定空白字串。 必要：`false` 類型：`string` 有效模式： `.*` **範例輸入** ``` { "request": { "delivery_stream_arn": "arn:aws:firehose:{{region}}:{{account-id}}:deliverystream/stream2-name", "data": "Data to send to the delivery stream." }, "id": "request123" } ```   **主題篩選條件：** `kinesisfirehose/message/binary/#` 使用此主題傳送包含二進位資料的訊息。連接器不剖析二進位資料。資料會依現狀串流。 若要將輸入請求映射到輸出回應，請將訊息主題中的 `#` 萬用字元換成任意請求 ID。例如，如果您將訊息發佈到 `kinesisfirehose/message/binary/request123`，回應物件中的 `id` 屬性會設為 `request123`。 如果您不想將請求映射到回應，您可以將訊息發佈到 `kinesisfirehose/message/binary/`。請務必包含結尾的斜線。 ------ ## 輸出資料 這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。 ------ #### [ Versions 2 - 5 ] **訂閱中的主題篩選條件** `kinesisfirehose/message/status` **範例輸出** 回應中包含批次中所傳送之各筆資料記錄的狀態。 ``` { "response": [ { "ErrorCode": "error", "ErrorMessage": "test error", "id": "request123", "status": "fail" }, { "firehose_record_id": "xyz2", "id": "request456", "status": "success" }, { "firehose_record_id": "xyz3", "id": "request890", "status": "success" } ] } ``` 如果連接器偵測到可重試的錯誤 （例如連線錯誤），它會在下一個批次中重試發佈。指數退避由 AWS SDK 處理。因可重試錯誤而失敗的請求會加回佇列末端，進一步發佈。 ------ #### [ Version 1 ] **訂閱中的主題篩選條件** `kinesisfirehose/message/status` **範例輸出：成功** ``` { "response": { "firehose_record_id": "1lxfuuuFomkpJYzt/34ZU/r8JYPf8Wyf7AXqlXm", "status": "success" }, "id": "request123" } ``` **範例輸出：失敗** ``` { "response" : { "error": "ResourceNotFoundException", "error_message": "An error occurred (ResourceNotFoundException) when calling the PutRecord operation: Firehose test1 not found under account 123456789012.", "status": "fail" }, "id": "request123" } ``` ------ ## 用量範例 使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。 **注意** 如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。 [連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。 1. 確定您符合連接器的[要求](#kinesis-firehose-connector-req)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。 將[範例程式碼](#kinesis-firehose-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 Core SDK](lambda-functions.md#lambda-sdks-core)。然後，建立在根層級包含 PY 檔案和 `greengrasssdk` 資料夾的 zip 套件。此 zip 套件是您上傳至 的部署套件 AWS Lambda。 建立 Python 3.7 Lambda 函數後，發佈函數版本並建立別名。 1. 設定 Greengrass 群組。 1. 依別名新增 Lambda 函數 （建議）。將 Lambda 生命週期設定為長期 （或在 CLI `"Pinned": true` 中）。 1. 新增連接器並設定其[參數](#kinesis-firehose-connector-param)。 1. 新增訂閱，允許連接器在支援主題篩選條件上接收 [JSON 輸入資料](#kinesis-firehose-connector-data-input)並傳送[輸出資料](#kinesis-firehose-connector-data-output)。 + 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。 + 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。 1. 部署群組。 1. 在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。 完成測試後，您可以將 Lambda 生命週期設定為隨需 （或在 CLI `"Pinned": false`中） 並部署群組。這會讓函數停止傳送訊息。 ### 範例 下列範例 Lambda 函數會將輸入訊息傳送至連接器。此訊息包含 JSON 資料。 ``` import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'kinesisfirehose/message' def create_request_with_all_fields(): return { "request": { "data": "Message from Firehose Connector Test" }, "id" : "req_123" } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return ``` ## 授權 Kinesis Firehose 連接器包含下列第三方軟體/授權： + [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache License 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License + [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域 + [jmespath](https://pypi.org/project/jmespath/)/MIT License + [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT License 此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 變更記錄 下表說明每個版本連接器的變更。 | 版本 | 變更 | | --- | --- | | 5 | 已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 | | 4 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 | | 3 | 修正以降低過多記錄，以及其他次要錯誤修正。 | | 2 | 新增在指定間隔將批次資料記錄傳送至 Firehose 的支援。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/kinesis-firehose-connector.html) | | 1 | 初始版本。 | Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。 ## 另請參閱 + [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md) + [Greengrass 連接器入門 (主控台)](connectors-console.md) + [Greengrass 連接器入門 (CLI)](connectors-cli.md) + [什麼是 Amazon Kinesis Data Firehose？](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) *Amazon Kinesis 開發人員指南*中的