aws sns

向AWS Simple Notification Service (SNS) 主题发布消息，入站消息data作为通知payload发送。节点将SNS响应metadata作为出站消息的一部分返回。

配置

Topic configuration（主题配置）

定义要发布消息的目标SNS主题。

Topic ARN pattern

要发布到的SNS主题的Amazon Resource Name (ARN)。

可使用标准AWS格式指定topic ARN：

• Full ARN：arn:aws:sns:us-east-1:123456789012:MyNewTopic

ARN可包含模板表达式，以根据消息数据动态选择主题：

• arn:aws:sns:${metadata.region}:123456789012:${topicName}
• arn:aws:sns:us-east-1:123456789012:notifications-$[severity]

AWS Credentials

Provide authentication credentials to access your AWS SNS service.

AWS Access Key ID

The access key ID for your AWS account. This credential is used to sign requests to AWS SNS.

AWS Secret Access Key

The secret access key corresponding to your access key ID.

注意：若使用Professional Edition，建议使用 Secrets storage 安全存储私密密钥。

AWS Region

The AWS region where your SNS topic is deployed. The region must match the location of your SNS topic.

注意：节点对AWS SNS操作使用固定超时：建立连接10秒，SNS服务处理并响应请求5秒。

JSON Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbSnsNodeConfiguration",
  "type": "object",
  "properties": {
    "topicArnPattern": {
      "type": "string",
      "minLength": 1,
      "description": "ARN of the SNS topic to publish to (supports templatization)."
    },
    "accessKeyId": {
      "type": "string",
      "minLength": 1,
      "description": "AWS Access Key ID for authentication."
    },
    "secretAccessKey": {
      "type": "string",
      "minLength": 1,
      "description": "AWS Secret Access Key for authentication."
    },
    "region": {
      "type": "string",
      "minLength": 1,
      "description": "AWS region where the SNS topic is deployed."
    }
  },
  "required": [
    "topicArnPattern",
    "accessKeyId",
    "secretAccessKey",
    "region"
  ],
  "additionalProperties": false
}

输出消息格式

节点通过将AWS SNS响应信息添加到消息metadata来转换入站消息，同时保留原始消息data。

Success case（成功时）

消息成功发布到SNS时，以下字段会添加到消息metadata：

• messageId – Unique identifier assigned by AWS SNS to the published message. This ID can be used to track the message delivery status.
• requestId – Unique identifier for the API request to AWS. Useful for troubleshooting and correlating with AWS CloudTrail logs.

Example:

Original message metadata:

1
2
3
{
  "deviceType": "sensor"
}

After successful publish, metadata becomes:

1
2
3
4
5
{
  "deviceType": "sensor",
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requestId": "12345678-1234-1234-1234-123456789012"
}

The message data remains unchanged.

Failure case

When publishing fails, the following field is added to the message metadata:

• error – Contains the exception class name and error message in the format: class <ExceptionClass>: <error message>

Example:

Original message metadata:

1
2
3
{
  "deviceType": "sensor"
}

After a failure (e.g., topic not found), metadata becomes:

1
2
3
4
{
  "deviceType": "sensor",
  "error": "class com.amazonaws.services.sns.model.NotFoundException: Topic does not exist"
}

The message data remains unchanged.

Message acknowledgement behavior

The node’s message acknowledgement behavior is controlled by the ACTORS_RULE_EXTERNAL_NODE_FORCE_ACK environment variable:

• When set to true – The incoming message is acknowledged and marked as successfully processed immediately upon receipt. A new message is created with the updated metadata and is enqueued for processing by the next node.
• When set to false (default) – The incoming message remains in an in-processing state throughout the entire SNS publish operation. The message is transformed in place, its metadata is updated with the SNS response fields, and the modified message is passed to the next node after the publish completes.

消息处理算法

1. 节点构建SNS发布请求：
   • The topic ARN pattern is processed, replacing templates with values from the incoming message data and metadata.
   • A PublishRequest is created with the message data as the notification payload and the resolved topic ARN as the destination.
2. The publish request is sent asynchronously to AWS SNS with the configured timeouts:
   • Connection timeout (10 seconds) applies to establishing the connection to AWS SNS.
   • Request timeout (5 seconds) applies to waiting for the SNS service to accept the message and return a response.
3. When SNS responds successfully:
   • The message ID from AWS (unique identifier for the published message) is added to the message metadata as messageId.
   • The request ID from AWS (unique identifier for the API request) is added to the message metadata as requestId.
   • The resulting message is forwarded via the Success connection.
4. If an error occurs during publishing:
   • Error details are added to the message metadata under the error key.
   • The message is forwarded via the Failure connection.

输出连接

• Success
  • The message was successfully published to the SNS topic.
  • The SNS service accepted the message and returned a message ID.
  • Response metadata (messageId and requestId) is included in the outgoing message metadata.
• Failure
  • Timeout: Failed to establish a connection to AWS SNS or the SNS service did not respond within the configured timeout periods (10 seconds for connection, 5 seconds for request).
  • SNS error: The AWS SNS service returned an error, such as invalid credentials, insufficient permissions, non-existent topic, or invalid topic ARN format.
  • Unexpected error: An unexpected error occurred during message processing.

示例

示例1 — 基本通知

向SNS主题发布简单通知消息以分发告警。

入站消息

Data：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "id": {
    "entityType": "ALARM",
    "id": "bfb13620-7737-400b-9c89-d569a0835de6"
  },
  "createdTime": 1755173119647,
  "tenantId": {
    "entityType": "TENANT",
    "id": "888e6780-78f5-11f0-8e01-57f51829cedc"
  },
  "type": "Overheating",
  "originator": {
    "entityType": "DEVICE",
    "id": "b3e86d40-78f5-11f0-8e01-57f51829cedc"
  },
  "severity": "CRITICAL",
  "acknowledged": false,
  "cleared": false,
  "startTs": 1755173119647,
  "endTs": 1755173119647,
  "name": "Overheating",
  "status": "ACTIVE_UNACK",
  "details": {
    "summary": "The temperature has persistently exceeded 85 °C for at least 10 minutes, while vibration (3.8–4.1 mm/s) and acoustic deviation (9–10.5%) remain normal. Immediate attention is required to prevent possible thermal damage."
  }
}

节点配置

1
2
3
4
5
6
{
  "topicArnPattern": "arn:aws:sns:us-east-1:123456789012:device-alerts",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "region": "us-east-1"
}

出站消息

Data：未更改。

Metadata（仅显示新增字段）：

1
2
3
4
{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requestId": "12345678-1234-1234-1234-123456789012"
}

Routed via the Success connection.

结果

alarm通知已成功发布到SNS主题。AWS消息ID和请求ID已添加到metadata。

示例2 — 无效主题的错误处理

Attempt to publish to a non-existent SNS topic, resulting in a failure.

Incoming message

Data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "id": {
    "entityType": "ALARM",
    "id": "bfb13620-7737-400b-9c89-d569a0835de6"
  },
  "createdTime": 1755173119647,
  "tenantId": {
    "entityType": "TENANT",
    "id": "888e6780-78f5-11f0-8e01-57f51829cedc"
  },
  "type": "Overheating",
  "originator": {
    "entityType": "DEVICE",
    "id": "b3e86d40-78f5-11f0-8e01-57f51829cedc"
  },
  "severity": "CRITICAL",
  "acknowledged": false,
  "cleared": false,
  "startTs": 1755173119647,
  "endTs": 1755173119647,
  "name": "Overheating",
  "status": "ACTIVE_UNACK",
  "details": {
    "summary": "The temperature has persistently exceeded 85 °C for at least 10 minutes, while vibration (3.8–4.1 mm/s) and acoustic deviation (9–10.5%) remain normal. Immediate attention is required to prevent possible thermal damage."
  }
}

节点配置

1
2
3
4
5
6
{
  "topicArnPattern": "arn:aws:sns:us-east-1:123456789012:non-existent-topic",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "region": "us-east-1"
}

出站消息

Data：未更改。

Metadata（仅显示新增字段）：

1
2
3
{
  "error": "class com.amazonaws.services.sns.model.NotFoundException: Topic does not exist"
}

Routed via the Failure connection.

结果

SNS发布操作失败，因为指定的主题不存在。错误详情已记录到消息metadata并经 Failure 连接路由。