As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Status de entrega de mensagens do Amazon SNS
<a name="sns-topic-attributes"></a>

O Amazon SNS fornece suporte para registrar em log o status de entrega de mensagens de notificação enviadas a tópicos com os seguintes endpoints do Amazon SNS: 
+ Amazon Data Firehose
+ Amazon Simple Queue Service
+ AWS Lambda
+ HTTPS
+ Endpoint da aplicação da plataforma

Os registros de status de entrega são enviados para o Amazon CloudWatch Logs, fornecendo informações sobre as operações de entrega de mensagens. Esses registros ajudam você a:
+ Determinar se a mensagem foi entregue com êxito a um endpoint.
+ Identificar a resposta do endpoint para o Amazon SNS.
+ Medir o tempo de permanência da mensagem (tempo entre a data e hora da publicação e a entrega para o endpoint).

Você pode configurar o registro do status de entrega usando a Console de gerenciamento da AWS AWS SDKs,, Query API ou AWS CloudFormation.

# Pré-requisitos para o registro em log do status de entrega
<a name="topics-attrib-prereq"></a>

Este tópico descreve as permissões do IAM necessárias para permitir que o Amazon SNS grave registros de entrega e explica a convenção padrão de CloudWatch nomenclatura de grupos de registros. Isso garante que você tenha a configuração e o acesso corretos para monitorar e analisar os registros de entrega de mensagens nos CloudWatch registros.

**Permissões obrigatórias do IAM**

A função do IAM anexada ao registro do status de entrega deve incluir as seguintes permissões para permitir que o Amazon SNS grave nos registros. CloudWatch É possível usar um perfil existente com essas permissões ou criar outro durante a configuração.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}
```

------

**Convenção de nomenclatura de grupos de logs**

Por padrão, o Amazon SNS cria CloudWatch grupos de registros para registros de status de entrega usando a seguinte convenção de nomenclatura. Os fluxos de log dentro desse grupo correspondem aos protocolos de endpoint (por exemplo, Lambda, Amazon SQS). Verifique se você tem permissões para visualizar esses registros no console de CloudWatch registros.

```
sns/<region>/<account-id>/<topic-name>
```

# Configurando o registro do status de entrega usando o Console de gerenciamento da AWS
<a name="topics-attrib"></a>

Este tópico explica como habilitar o registro de status de entrega de mensagens para tópicos do Amazon SNS, incluindo a definição de configurações de registro, a atribuição de funções do IAM e a verificação de que CloudWatch os registros capturam registros de entrega para monitoramento e solução de problemas.

1. Faça login no [console do Amazon SNS](https://console.aws.amazon.com/sns/home).

1. No painel de navegação, escolha **Tópicos**.

1. Selecione o **tópico** desejado e escolha **Editar**.

1. Expanda a seção **Registro em log do status de entrega**.

1. Escolha o **protocolo** para o qual você deseja ativar o registro em log (por exemplo, HTTP, Lambda, Amazon SQS).

1. Insira a **taxa de amostragem de sucesso**, que é a porcentagem de mensagens bem-sucedidas das quais você deseja receber CloudWatch registros.

1. Na seção de **perfis do IAM**, configure os perfis para o registro em log de **sucesso** e de **falha**:
   + **Use uma função de serviço existente** — Selecione uma função do IAM existente que tenha as permissões necessárias para o Amazon SNS gravar registros. CloudWatch
   + **Crie um perfil de serviço**: selecione **Criar novos perfis** para definir os perfis do IAM para entregas bem-sucedidas e com falha no console do IAM. Para obter detalhes sobre a permissão, consulte [Pré-requisitos para o registro em log do status de entrega](topics-attrib-prereq.md).

1. Escolha **Salvar alterações**.

   Depois de ativar o registro, você pode visualizar e analisar os CloudWatch registros contendo o status de entrega da mensagem. Para obter mais informações sobre o uso CloudWatch, consulte a [CloudWatchdocumentação](https://aws.amazon.com/documentation/cloudwatch).

**Como verificar a configuração de log**

1. Faça login no console CloudWatch de registros.

1. Localize o grupo de logs chamado `sns/<region>/<account-id>/<topic-name>`.

1. Certifique-se de que existam fluxos de log para o protocolo de endpoint configurado.

1. Envie uma mensagem de teste para seu tópico e confirme se as entradas de log aparecem, indicando entregas bem-sucedidas ou com falha.

# Configurando o registro do status de entrega usando o AWS SDKs
<a name="msg-status-sdk"></a>

Eles AWS SDKs fornecem, APIs em vários idiomas, a definição de atributos de tópicos para o registro do status de entrega de mensagens. Por exemplo, use a [SetTopicAttributes](https://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html)API para configurar:
+ `LambdaSuccessFeedbackRoleArn`: perfil do IAM para entrega de mensagens bem-sucedida para endpoints do Lambda.
+ `LambdaSuccessFeedbackSampleRate`: taxa de amostragem de mensagens bem-sucedidas para endpoints do Lambda.
+ `LambdaFailureFeedbackRoleArn`: perfil do IAM para entrega de mensagens com falha para endpoints do Lambda.

**Exemplo de AWS CLI comando**

```
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
```

## Atributos de tópicos
<a name="topic-attributes"></a>

Use os seguintes valores de nome de atributo de tópico para o status de entrega de mensagens:

**HTTP**
+ `HTTPSuccessFeedbackRoleArn`: status de entrega de mensagem bem-sucedida para um tópico do Amazon SNS que está inscrito em um endpoint HTTP. 
+ `HTTPSuccessFeedbackSampleRate`: porcentagem de mensagens bem-sucedidas para amostrar para um tópico do Amazon SNS que está inscrito em um endpoint HTTP.
+ `HTTPFailureFeedbackRoleArn`: status de entrega de mensagem com falha para um tópico do Amazon SNS que está inscrito em um endpoint HTTP.

**Amazon Data Firehose**
+ `FirehoseSuccessFeedbackRoleArn`: status de entrega de mensagem bem-sucedida para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon Data Firehose.
+ `FirehoseSuccessFeedbackSampleRate`: porcentagem de mensagens bem-sucedidas para amostrar para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon Data Firehose.
+ `FirehoseFailureFeedbackRoleArn`: status de entrega de mensagem com falha para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon Data Firehose. 

**AWS Lambda**
+ `LambdaSuccessFeedbackRoleArn`: status de entrega de mensagem bem-sucedida para um tópico do Amazon SNS que está inscrito em um endpoint do Lambda.
+ `LambdaSuccessFeedbackSampleRate`: porcentagem de mensagens bem-sucedidas para amostrar para um tópico do Amazon SNS que está inscrito em um endpoint do Lambda.
+ `LambdaFailureFeedbackRoleArn`: status de entrega de mensagem com falha para um tópico do Amazon SNS que está inscrito em um endpoint do Lambda. 

**Endpoints da aplicação da plataforma**
+ `ApplicationSuccessFeedbackRoleArn`— Status de entrega de mensagens bem-sucedido para um tópico do Amazon SNS que está inscrito em um AWS endpoint do aplicativo.
+ `ApplicationSuccessFeedbackSampleRate`: porcentagem de mensagens bem-sucedidas para amostrar para um tópico do Amazon SNS que está inscrito em um endpoint de aplicação da AWS .
+ `ApplicationFailureFeedbackRoleArn`— Falha no status de entrega de mensagens para um tópico do Amazon SNS que está inscrito em um AWS endpoint do aplicativo.
**nota**  
Além disso, você pode configurar os atributos do aplicativo para registrar em log o status de entrega diretamente nos serviços de notificação por push. Para obter mais informações, consulte [Usar atributos de aplicativo do Amazon SNS para obter o status de entrega de mensagens](https://docs.aws.amazon.com/sns/latest/dg/sns-msg-status.html). 

**Amazon SQS**
+ `SQSSuccessFeedbackRoleArn`: status de entrega de mensagem bem-sucedida para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon SQS. 
+ `SQSSuccessFeedbackSampleRate`: porcentagem de mensagens bem-sucedidas para amostrar para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon SQS. 
+ `SQSFailureFeedbackRoleArn`: status de entrega de mensagem com falha para um tópico do Amazon SNS que está inscrito em um endpoint do Amazon SQS. 

Os registros dos endpoints do aplicativo da plataforma são gravados no mesmo grupo de CloudWatch registros dos outros endpoints.

**nota**  
 Os `<ENDPOINT>FailureFeedbackRoleArn` atributos `<ENDPOINT>SuccessFeedbackRoleArn` e são usados para dar ao Amazon SNS acesso de gravação para usar CloudWatch Logs em seu nome. O atributo `<ENDPOINT>SuccessFeedbackSampleRate` é para especificar a porcentagem de taxa de amostra (0-100) de mensagens bem-sucedidas. Depois de configurar o `<ENDPOINT>FailureFeedbackRoleArn` atributo, todas as entregas de mensagens com falha geram CloudWatch registros. 

# AWS Exemplos de SDK para configurar atributos de tópicos
<a name="topic-attributes-sdks"></a>

Os exemplos de código a seguir mostram como usar o `SetTopicAttributes`.

------
#### [ CLI ]

**AWS CLI**  
**Para definir um atributo para um tópico**  
O exemplo `set-topic-attributes` a seguir define o atributo `DisplayName` para o tópico especificado.  

```
aws sns set-topic-attributes \
    --topic-arn arn:aws:sns:us-west-2:123456789012:MyTopic \
    --attribute-name DisplayName \
    --attribute-value MyTopicDisplayName
```
Este comando não produz saída.  
+  Para obter detalhes da API, consulte [SetTopicAttributes](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sns/set-topic-attributes.html)em *Referência de AWS CLI Comandos*. 

------
#### [ Java ]

**SDK para Java 2.x**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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:    <attribute> <topicArn> <value>

                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);
        }
    }
}
```
+  Para obter detalhes da API, consulte [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForJavaV2/sns-2010-03-31/SetTopicAttributes)a *Referência AWS SDK for Java 2.x da API*. 

------
#### [ JavaScript ]

**SDK para JavaScript (v3)**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/sns#code-examples). 
Crie o cliente em um módulo separado e exporte-o.  

```
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({});
```
Importe o SDK e os módulos do cliente e chame a 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;
};
```
+  Para obter mais informações, consulte o [Guia do desenvolvedor do AWS SDK para JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/sns-examples-managing-topics.html#sns-examples-managing-topicsstttopicattributes). 
+  Para obter detalhes da API, consulte [SetTopicAttributes](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sns/command/SetTopicAttributesCommand)a *Referência AWS SDK para JavaScript da API*. 

------
#### [ Kotlin ]

**SDK para Kotlin**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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.")
    }
}
```
+  Para obter detalhes da API, consulte a [SetTopicAttributes](https://sdk.amazonaws.com/kotlin/api/latest/index.html)referência da API *AWS SDK for Kotlin*. 

------
#### [ PHP ]

**SDK para PHP**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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());
}
```
+  Para obter detalhes da API, consulte [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForPHPV3/sns-2010-03-31/SetTopicAttributes)a *Referência AWS SDK para PHP da API*. 

------
#### [ Ruby ]

**SDK para Ruby**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [Repositório de exemplos de código da 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
```
+  Para obter mais informações, consulte o [Guia do desenvolvedor do AWS SDK para Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/sns-example-enable-resource.html). 
+  Para obter detalhes da API, consulte [SetTopicAttributes](https://docs.aws.amazon.com/goto/SdkForRubyV3/sns-2010-03-31/SetTopicAttributes)a *Referência AWS SDK para Ruby da API*. 

------
#### [ SAP ABAP ]

**SDK para SAP ABAP**  
 Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no [AWS Code Examples Repository](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.
```
+  Para obter detalhes da API, consulte a [SetTopicAttributes](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html)referência da *API AWS SDK for SAP ABAP*. 

------

# Configurando o registro do status de entrega usando CloudFormation
<a name="msg-status-cloudformation"></a>

Para configurar `DeliveryStatusLogging` usando CloudFormation, use um modelo JSON ou YAML para criar uma CloudFormation pilha. Para obter mais informações, consulte a `DeliveryStatusLogging` propriedade do `AWS::SNS::Topic` recurso no Guia do CloudFormation usuário. Abaixo estão exemplos de CloudFormation modelos em JSON e YAML para criar um novo tópico ou atualizar um tópico existente com todos os `DeliveryStatusLogging` atributos do protocolo Amazon SQS.

Garanta que os papéis do IAM referenciados em `SuccessFeedbackRoleArn` e `FailureFeedbackRoleArn` tenham as permissões de CloudWatch registros necessárias.

------
#### [ 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
```

------