本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon SNS 訊息傳遞狀態
Amazon SNS 支援使用下列 Amazon SNS 端點記錄傳送至主題的通知訊息交付狀態：
+ Amazon Data Firehose
+ Amazon Simple Queue Service
+ AWS Lambda
+ HTTPS
+ 平台應用程式端點
交付狀態日誌會傳送至 Amazon CloudWatch Logs，提供訊息交付操作的洞見。這些日誌可協助您：
+ 判斷訊息是否已成功交付至端點。
+ 識別從端點到 Amazon SNS 的回應。
+ 測量訊息駐留時間 （發佈時間戳記和遞交至端點之間的時間）。
您可以使用 AWS 管理主控台、 AWS SDKs、查詢 API 或 來設定交付狀態記錄 AWS CloudFormation。
# 交付狀態記錄的先決條件
本主題概述讓 Amazon SNS 將交付日誌寫入 CloudWatch 的必要 IAM 許可，並說明預設日誌群組命名慣例。這可確保您有正確的設定和存取，以監控和分析 CloudWatch 日誌中的訊息傳遞日誌。
**必要的 IAM 許可**
附加用於交付狀態記錄的 IAM 角色必須包含下列許可，才能讓 Amazon SNS 寫入 CloudWatch Logs。您可以使用具有這些許可的現有角色，或在設定期間建立新的角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:*"
}
]
}
```
------
**日誌群組命名慣例**
根據預設，Amazon SNS 會使用下列命名慣例，為交付狀態日誌建立 CloudWatch 日誌群組。此群組中的日誌串流對應至端點通訊協定 （例如 Lambda、Amazon SQS)。請確定您有在 CloudWatch Logs 主控台中檢視這些日誌的許可。
```
sns///
```
# 使用 設定交付狀態記錄 AWS 管理主控台
本主題說明如何啟用 Amazon SNS 主題的訊息交付狀態記錄，包括設定記錄設定、指派 IAM 角色，以及驗證 CloudWatch Logs 擷取交付日誌以進行監控和故障診斷。
1. 登入 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/home)。
1. 在導覽面板上，選擇 **Topics (主題)**。
1. 選取所需的**主題**，然後選擇**編輯**。
1. 展開**交付狀態記錄**區段。
1. 選擇您要啟用記錄的**通訊協定** （例如 HTTP、Lambda、Amazon SQS)。
1. 輸入**成功範例速率**，這是您要接收 CloudWatch Logs 之成功訊息的百分比。
1. 在 **IAM 角色**區段中，您必須設定**成功**和**失敗**記錄的角色：
+ **使用現有的服務角色** – 選取具有 Amazon SNS 將日誌寫入 CloudWatch 所需許可的現有 IAM 角色。
+ **建立新的服務角色** – 選擇**建立新的角色**，在 IAM 主控台中定義成功和失敗交付的 IAM 角色。如需許可詳細資訊，請參閱 [交付狀態記錄的先決條件](topics-attrib-prereq.md)。
1. 選擇**儲存變更**。
啟用記錄後，您可以檢視和剖析包含訊息傳遞狀態的 CloudWatch Logs。如需使用 CloudWatch 的詳細資訊，請參閱 [CloudWatch 文件](https://aws.amazon.com/documentation/cloudwatch)。
**驗證日誌設定**
1. 登入 CloudWatch Logs 主控台。
1. 找到名為 的日誌群組`sns///`。
1. 確保已設定的端點通訊協定存在日誌串流。
1. 傳送測試訊息到您的主題，並確認日誌項目出現，表示傳送成功或失敗。
# 使用 AWS SDKs 設定交付狀態記錄
AWS SDKs 提供多種語言APIs，以設定訊息傳遞狀態記錄的主題屬性。例如，使用 [SetTopicAttributes](https://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html) API 來設定：
+ `LambdaSuccessFeedbackRoleArn` – 將訊息成功交付至 Lambda 端點的 IAM 角色。
+ `LambdaSuccessFeedbackSampleRate` – 成功傳送訊息至 Lambda 端點的取樣率。
+ `LambdaFailureFeedbackRoleArn` – 傳遞失敗訊息至 Lambda 端點的 IAM 角色。
**範例 AWS CLI 命令**
```
aws sns set-topic-attributes \
--topic-arn arn:aws:sns:us-west-2:123456789012:MyTopic \
--attribute-name LambdaSuccessFeedbackRoleArn \
--attribute-value arn:aws:iam::123456789012:role/MyFeedbackRole
```
## 主題屬性
將下列主題屬性名稱值用於訊息傳遞狀態：
**HTTP**
+ `HTTPSuccessFeedbackRoleArn` – 訂閱 HTTP 端點之 Amazon SNS 主題的訊息傳遞狀態成功。
+ `HTTPSuccessFeedbackSampleRate` – 訂閱 HTTP 端點的 Amazon SNS 主題範例成功訊息的百分比。
+ `HTTPFailureFeedbackRoleArn` – 訂閱 HTTP 端點之 Amazon SNS 主題的訊息傳遞狀態失敗。
**Amazon Data Firehose**
+ `FirehoseSuccessFeedbackRoleArn` – 訂閱 Amazon Data Firehose 端點的 Amazon SNS 主題成功訊息傳遞狀態。
+ `FirehoseSuccessFeedbackSampleRate` – 訂閱 Amazon Data Firehose 端點的 Amazon SNS 主題範例成功訊息的百分比。
+ `FirehoseFailureFeedbackRoleArn` – 訂閱 Amazon Data Firehose 端點之 Amazon SNS 主題的訊息傳遞狀態失敗。
**AWS Lambda**
+ `LambdaSuccessFeedbackRoleArn` – 訂閱 Lambda 端點之 Amazon SNS 主題的訊息傳遞狀態成功。
+ `LambdaSuccessFeedbackSampleRate` – 訂閱 Lambda 端點之 Amazon SNS 主題的取樣成功訊息百分比。
+ `LambdaFailureFeedbackRoleArn` – 訂閱 Lambda 端點之 Amazon SNS 主題的訊息傳遞狀態失敗。
**平台應用程式端點**
+ `ApplicationSuccessFeedbackRoleArn` – 訂閱 AWS 應用程式端點之 Amazon SNS 主題的訊息傳遞狀態成功。
+ `ApplicationSuccessFeedbackSampleRate` – 要針對訂閱 AWS 應用程式端點的 Amazon SNS 主題取樣的成功訊息百分比。
+ `ApplicationFailureFeedbackRoleArn` – 訂閱 AWS 應用程式端點之 Amazon SNS 主題的訊息傳遞狀態失敗。
**注意**
此外，您可以設定應用程式屬性來直接記錄交付狀態，以推送通知服務。如需詳細資訊，請參閱[使用訊息傳遞狀態的 Amazon SNS 應用程式屬性](https://docs.aws.amazon.com/sns/latest/dg/sns-msg-status.html)。
**Amazon SQS**
+ `SQSSuccessFeedbackRoleArn` – 訂閱 Amazon SQS 端點的 Amazon SNS 主題成功訊息傳遞狀態。 Amazon SQS
+ `SQSSuccessFeedbackSampleRate` – 訂閱 Amazon SQS 端點的 Amazon SNS 主題範例成功訊息的百分比。 Amazon SQS
+ `SQSFailureFeedbackRoleArn` – 訂閱 Amazon SQS 端點之 Amazon SNS 主題的訊息傳遞狀態失敗。 Amazon SQS
平台應用程式端點的日誌會寫入與其他端點相同的 CloudWatch Logs 群組。
**注意**
`SuccessFeedbackRoleArn` 和 `FailureFeedbackRoleArn` 屬性是用來提供 Amazon SNS 寫入存取權，以代表您使用 CloudWatch Logs。`SuccessFeedbackSampleRate` 屬性用於指定成功傳送訊息的取樣率百分比 (0-100)。在您設定 `FailureFeedbackRoleArn` 屬性後，則所有傳送失敗的訊息都會產生 CloudWatch Logs。
# AWS 用於設定主題屬性的 SDK 範例
下列程式碼範例示範如何使用 `SetTopicAttributes`。
------
#### [ CLI ]
**AWS CLI**
**設定主題的屬性**
下列 `set-topic-attributes` 範例會設定指定主題的 `DisplayName` 屬性。
```
aws sns set-topic-attributes \
--topic-arn arn:aws:sns:us-west-2:123456789012:MyTopic \
--attribute-name DisplayName \
--attribute-value MyTopicDisplayName
```
此命令不會產生輸出。
+ 如需 API 詳細資訊，請參閱《AWS CLI 命令參考》**中的 [SetTopicAttributes](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sns/set-topic-attributes.html)。
------
#### [ Java ]
**SDK for Java 2.x**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/sns#code-examples)中設定和執行。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.sns.SnsClient;
import software.amazon.awssdk.services.sns.model.SetTopicAttributesRequest;
import software.amazon.awssdk.services.sns.model.SetTopicAttributesResponse;
import software.amazon.awssdk.services.sns.model.SnsException;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class SetTopicAttributes {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
attribute - The attribute action to use. Valid parameters are: Policy | DisplayName | DeliveryPolicy .
topicArn - The ARN of the topic.\s
value - The value for the attribute.
""";
if (args.length < 3) {
System.out.println(usage);
System.exit(1);
}
String attribute = args[0];
String topicArn = args[1];
String value = args[2];
SnsClient snsClient = SnsClient.builder()
.region(Region.US_EAST_1)
.build();
setTopAttr(snsClient, attribute, topicArn, value);
snsClient.close();
}
public static void setTopAttr(SnsClient snsClient, String attribute, String topicArn, String value) {
try {
SetTopicAttributesRequest request = SetTopicAttributesRequest.builder()
.attributeName(attribute)
.attributeValue(value)
.topicArn(topicArn)
.build();
SetTopicAttributesResponse result = snsClient.setTopicAttributes(request);
System.out.println(
"\n\nStatus was " + result.sdkHttpResponse().statusCode() + "\n\nTopic " + request.topicArn()
+ " updated " + request.attributeName() + " to " + request.attributeValue());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
}
```
+ 如需 API 詳細資訊，請參閱 *AWS SDK for Java 2.x API 參考*中的 [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForJavaV2/sns-2010-03-31/SetTopicAttributes)。
------
#### [ JavaScript ]
**適用於 JavaScript (v3) 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/sns#code-examples)中設定和執行。
在單獨的模組中建立用戶端並將其匯出。
```
import { SNSClient } from "@aws-sdk/client-sns";
// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});
```
匯入 SDK 和用戶端模組，然後呼叫 API。
```
import { SetTopicAttributesCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";
export const setTopicAttributes = async (
topicArn = "TOPIC_ARN",
attributeName = "DisplayName",
attributeValue = "Test Topic",
) => {
const response = await snsClient.send(
new SetTopicAttributesCommand({
AttributeName: attributeName,
AttributeValue: attributeValue,
TopicArn: topicArn,
}),
);
console.log(response);
// {
// '$metadata': {
// httpStatusCode: 200,
// requestId: 'd1b08d0e-e9a4-54c3-b8b1-d03238d2b935',
// extendedRequestId: undefined,
// cfId: undefined,
// attempts: 1,
// totalRetryDelay: 0
// }
// }
return response;
};
```
+ 如需詳細資訊，請參閱[《適用於 JavaScript 的 AWS SDK 開發人員指南》](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/sns-examples-managing-topics.html#sns-examples-managing-topicsstttopicattributes)。
+ 如需 API 詳細資訊，請參閱 *適用於 JavaScript 的 AWS SDK API 參考*中的 [SetTopicAttributes](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sns/command/SetTopicAttributesCommand)。
------
#### [ Kotlin ]
**適用於 Kotlin 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/sns#code-examples)中設定和執行。
```
suspend fun setTopAttr(
attribute: String?,
topicArnVal: String?,
value: String?,
) {
val request =
SetTopicAttributesRequest {
attributeName = attribute
attributeValue = value
topicArn = topicArnVal
}
SnsClient.fromEnvironment { region = "us-east-1" }.use { snsClient ->
snsClient.setTopicAttributes(request)
println("Topic ${request.topicArn} was updated.")
}
}
```
+ 如需 API 詳細資訊，請參閱《適用於 Kotlin 的AWS SDK API 參考》[https://sdk.amazonaws.com/kotlin/api/latest/index.html](https://sdk.amazonaws.com/kotlin/api/latest/index.html)中的 *SetTopicAttributes*。
------
#### [ PHP ]
**適用於 PHP 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/sns#code-examples)中設定和執行。
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
/**
* Configure the message delivery status attributes for an Amazon SNS Topic.
*
* This code expects that you have AWS credentials set up per:
* https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials.html
*/
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$attribute = 'Policy | DisplayName | DeliveryPolicy';
$value = 'First Topic';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->setTopicAttributes([
'AttributeName' => $attribute,
'AttributeValue' => $value,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
+ 如需 API 詳細資訊，請參閱 *適用於 PHP 的 AWS SDK API 參考*中的 [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForPHPV3/sns-2010-03-31/SetTopicAttributes)。
------
#### [ Ruby ]
**SDK for Ruby**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/sns#code-examples)中設定和執行。
```
# Service class to enable an SNS resource with a specified policy
class SnsResourceEnabler
# Initializes the SnsResourceEnabler with an SNS resource client
#
# @param sns_resource [Aws::SNS::Resource] The SNS resource client
def initialize(sns_resource)
@sns_resource = sns_resource
@logger = Logger.new($stdout)
end
# Sets a policy on a specified SNS topic
#
# @param topic_arn [String] The ARN of the SNS topic
# @param resource_arn [String] The ARN of the resource to include in the policy
# @param policy_name [String] The name of the policy attribute to set
def enable_resource(topic_arn, resource_arn, policy_name)
policy = generate_policy(topic_arn, resource_arn)
topic = @sns_resource.topic(topic_arn)
topic.set_attributes({
attribute_name: policy_name,
attribute_value: policy
})
@logger.info("Policy #{policy_name} set successfully for topic #{topic_arn}.")
rescue Aws::SNS::Errors::ServiceError => e
@logger.error("Failed to set policy: #{e.message}")
end
private
# Generates a policy string with dynamic resource ARNs
#
# @param topic_arn [String] The ARN of the SNS topic
# @param resource_arn [String] The ARN of the resource
# @return [String] The policy as a JSON string
def generate_policy(topic_arn, resource_arn)
{
Version: '2008-10-17',
Id: '__default_policy_ID',
Statement: [{
Sid: '__default_statement_ID',
Effect: 'Allow',
Principal: { "AWS": '*' },
Action: ['SNS:Publish'],
Resource: topic_arn,
Condition: {
ArnEquals: {
"AWS:SourceArn": resource_arn
}
}
}]
}.to_json
end
end
# Example usage:
if $PROGRAM_NAME == __FILE__
topic_arn = 'MY_TOPIC_ARN' # Should be replaced with a real topic ARN
resource_arn = 'MY_RESOURCE_ARN' # Should be replaced with a real resource ARN
policy_name = 'POLICY_NAME' # Typically, this is "Policy"
sns_resource = Aws::SNS::Resource.new
enabler = SnsResourceEnabler.new(sns_resource)
enabler.enable_resource(topic_arn, resource_arn, policy_name)
end
```
+ 如需詳細資訊，請參閱《[適用於 Ruby 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/sns-example-enable-resource.html)》。
+ 如需 API 詳細資訊，請參閱 *適用於 Ruby 的 AWS SDK API 參考*中的 [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForRubyV3/sns-2010-03-31/SetTopicAttributes)。
------
#### [ SAP ABAP ]
**適用於 SAP ABAP 的開發套件**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/sns#code-examples)中設定和執行。
```
TRY.
lo_sns->settopicattributes(
iv_topicarn = iv_topic_arn
iv_attributename = iv_attribute_name
iv_attributevalue = iv_attribute_value ).
MESSAGE 'Set/updated SNS topic attributes.' TYPE 'I'.
CATCH /aws1/cx_snsnotfoundexception.
MESSAGE 'Topic does not exist.' TYPE 'E'.
ENDTRY.
```
+ 如需 API 詳細資訊，請參閱《適用於 SAP ABAP 的AWS SDK API 參考》**中的 [SetTopicAttributes](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html)。
------
# 使用 設定交付狀態記錄 CloudFormation
若要`DeliveryStatusLogging`使用 設定 CloudFormation，請使用 JSON 或 YAML 範本來建立 CloudFormation 堆疊。如需詳細資訊，請參閱 CloudFormation 《 使用者指南》中的 `AWS::SNS::Topic` 資源的 `DeliveryStatusLogging` 屬性。以下是 JSON 和 YAML 中建立新主題或更新具有 Amazon SQS 通訊協定所有`DeliveryStatusLogging`屬性之現有主題的 CloudFormation 範本範例。
確保 中參考`SuccessFeedbackRoleArn`的 IAM 角色`FailureFeedbackRoleArn`具有所需的 CloudWatch Logs 許可。
------
#### [ JSON ]
```
"Resources": {
"MySNSTopic" : {
"Type" : "AWS::SNS::Topic",
"Properties" : {
"TopicName" : "TestTopic",
"DisplayName" : "TEST",
"SignatureVersion" : "2",
"DeliveryStatusLogging" : [{
"Protocol": "sqs",
"SuccessFeedbackSampleRate": "45",
"SuccessFeedbackRoleArn": "arn:aws:iam::123456789012:role/SNSSuccessFeedback_test1",
"FailureFeedbackRoleArn": "arn:aws:iam::123456789012:role/SNSFailureFeedback_test2"
}]
}
}
}
```
------
#### [ YAML ]
```
Resources:
MySNSTopic:
Type: AWS::SNS::Topic
Properties:
TopicName:TestTopic
DisplayName:TEST
SignatureVersion:2
DeliveryStatusLogging:
- Protocol: sqs
SuccessFeedbackSampleRate: 45
SuccessFeedbackRoleArn: arn:aws:iam::123456789012:role/SNSSuccessFeedback_test1
FailureFeedbackRoleArn: arn:aws:iam::123456789012:role/SNSFailureFeedback_test2
```
------