# Recursos personalizados baseados no Amazon SNS O tópico apresentado a seguir mostra como configurar um recurso personalizado com um token de serviço que especifica o tópico do Amazon SNS para o qual o CloudFormation envia solicitações. Além disso, você aprende a sequência de eventos e de mensagens enviadas e recebidas como resultado da criação, da atualização e da exclusão da pilha de recursos personalizada. Com recursos personalizados e o Amazon SNS, você pode habilitar cenários como adicionar novos recursos a uma pilha e injetar dados dinâmicos em uma pilha. Por exemplo, quando você cria uma pilha, o CloudFormation pode enviar uma solicitação `Create` para um tópico monitorado por uma aplicação em execução em uma instância do Amazon EC2. A notificação do Amazon SNS aciona a aplicação para realizar tarefas de provisionamento adicionais, como recuperar um grupo de IPs elásticos na lista de permissão. Depois que todas essas ações forem concluídas, a aplicação enviará uma resposta (e quaisquer dados de saída) que notifica o CloudFormation para dar prosseguimento à operação de pilha. Quando você especifica um tópico do Amazon SNS como o destino de um recurso personalizado, o CloudFormation envia mensagens para o tópico do SNS especificado durante as operações de pilha que envolvem o recurso personalizado. Para realizar o processamento dessas mensagens e executar as ações necessárias, você deve ter um endpoint com suporte que seja assinante do tópico do SNS. Para obter uma introdução aos recursos personalizados e como eles funcionam, consulte [Como os recursos personalizados funcionam](template-custom-resources.md#how-custom-resources-work). Para obter mais informações sobre o Amazon SNS e como ele funciona, consulte o [Guia do desenvolvedor do Amazon Simple Notification Service](https://docs.aws.amazon.com/sns/latest/dg/). ## Uso do Amazon SNS para criar recursos personalizados **Topics** + [Etapa 1: Criar a pilha](#crpg-walkthrough-stack-creation) + [Etapa 2: Atualizações de pilha](#crpg-walkthrough-stack-updates) + [Etapa 3: Exclusão da pilha](#crpg-walkthrough-stack-deletion) ### Etapa 1: Criar a pilha 1. O desenvolvedor do modelo cria uma pilha do CloudFormation que contém um recurso personalizado. No exemplo de modelo apresentado abaixo, usamos o nome do tipo de recurso personalizado `Custom::SeleniumTester` para o recurso personalizado com ID lógico `MySeleniumTest`. Os nomes de tipo de recurso personalizados devem ser alfanuméricos e podem ter um comprimento máximo de 60 caracteres. O tipo de recurso personalizado é declarado com um token de serviço, propriedades opcionais específicas do provedor e atributos de [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt) opcionais que são definidos pelo provedor de recursos personalizados. Essas propriedades e os atributos podem ser usados para passar informações do template developer para o custom resource provider, e vice-versa. O token de serviço especifica um tópico do Amazon SNS configurado pelo provedor de recursos. ``` { "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : { "MySeleniumTest" : { "Type": "Custom::SeleniumTester", "Version" : "1.0", "Properties" : { "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest", "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } } }, "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } } } ``` **nota** Os nomes e os valores dos dados acessados ​​com `Fn::GetAtt` são retornados pelo provedor de recursos personalizados durante a resposta do provedor para o CloudFormation. Caso o custom resource provider seja um terceiro, o template developer deverá obter os nomes desses valores de retorno do custom resource provider. 1. O CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um `"RequestType" : "Create"` que contém informações sobre a pilha, as propriedades do recurso personalizado do modelo da pilha e um URL de S3 para a resposta. O tópico SNS usado para enviar a notificação é incorporado no modelo na propriedade `ServiceToken`. Para evitar usar um valor codificado, um template developer pode usar um parâmetro de modelo, de maneira que o valor seja informado no momento em que a pilha é iniciada. O exemplo a seguir mostra uma solicitação `Create` de recurso personalizado que inclui um nome de tipo de recurso personalizado `Custom::SeleniumTester`, criado com um `LogicalResourceId` de `MySeleniumTester`: ``` { "RequestType" : "Create", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "ResponseURL" : "http://pre-signed-S3-url-for-response", "ResourceType" : "Custom::SeleniumTester", "LogicalResourceId" : "MySeleniumTester", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } } ``` Para obter informações detalhadas sobre o objeto de solicitação para as solicitações `Create`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). 1. O custom resource provider processa os dados enviados pelo template developer e determina se a solicitação `Create` foi bem-sucedida. O provedor de recursos usa o URL do S3 enviado pelo CloudFormation para enviar uma resposta de `SUCCESS` ou de `FAILED`. O CloudFormation espera diferentes campos de resposta com base no tipo de resposta. Para obter informações sobre os campos de resposta para um tipo de solicitação em específico, consulte a documentação para esse tipo de solicitação na seção [Referência de solicitações e respostas](crpg-ref.md). Em resposta a uma solicitação de criação ou atualização, o provedor personalizado de recursos pode retornar elementos de dados no campo `Data` da resposta. Esses são os pares de nome/valor, e os *nomes* correspondem aos atributos `Fn::GetAtt` usados com o recurso personalizado no modelo de pilha. Os *valores* são os dados retornados quando o Template Developer chama `Fn::GetAtt` no recurso com o nome do atributo. Este é um exemplo de uma resposta de recurso personalizado: ``` { "Status" : "SUCCESS", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1", "Data" : { "resultsPage" : "http://www.myexampledomain/test-results/guid", "lastUpdate" : "2012-11-14T03:30Z" } } ``` Para obter informações detalhadas sobre o objeto de resposta para as solicitações `Create`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). Os campos `StackId`, `RequestId` e `LogicalResourceId` devem ser copiados na íntegra da solicitação. 1. O CloudFormation declara o status da pilha como `CREATE_COMPLETE` ou `CREATE_FAILED`. Caso a pilha tenha sido criada com êxito, o desenvolvedor de modelos pode usar os valores de saída do recurso personalizado criado acessando-os com [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt). Por exemplo, o modelo de recurso personalizado usado na ilustração utilizou `Fn::GetAtt` para copiar saídas de recurso para as saídas de pilha: ``` "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } } ``` ### Etapa 2: Atualizações de pilha Para atualizar uma pilha existente, é necessário enviar um modelo que especifique as atualizações para as propriedades dos recursos na pilha, conforme mostrado no exemplo abaixo. O CloudFormation atualiza somente os recursos que têm alterações especificadas no modelo. Para obter mais informações, consulte [Compreender atualização de comportamentos de recursos da pilha](using-cfn-updating-stacks-update-behaviors.md). É possível atualizar recursos personalizados que exigem uma substituição do recurso físico subjacente. Quando você atualiza um recurso personalizado em um modelo do CloudFormation, o CloudFormation envia uma solicitação de atualização a esse recurso personalizado. Caso um recurso personalizado exija uma substituição, o novo recurso personalizado deve enviar uma resposta com o novo ID físico. Quando o CloudFormation recebe a resposta, ele compara o `PhysicalResourceId` entre os recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo, conforme mostrado na [Etapa 3: Exclusão da pilha](#crpg-walkthrough-stack-deletion). **nota** Se você não fez alterações no recurso personalizado, o CloudFormation não enviará solicitações para ele durante uma atualização de pilha. 1. O template developer inicia uma atualização para a pilha que contém um recurso personalizado. Durante uma atualização, o template developer pode especificar novas propriedades no modelo da pilha. Este é um exemplo de um `Update` para o modelo de pilha que usa um tipo de recurso personalizado: ``` { "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : { "MySeleniumTest" : { "Type": "Custom::SeleniumTester", "Version" : "1.0", "Properties" : { "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest", "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] } } }, "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } } } ``` 1. O CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um `"RequestType" : "Update"` que contém informações semelhantes às da chamada `Create`, exceto por o campo `OldResourceProperties` conter as propriedades de recurso anteriores e ResourceProperties conter as propriedades de recurso atualizadas (caso haja alguma). Este é um exemplo de uma solicitação `Update`: ``` { "RequestType" : "Update", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "ResponseURL" : "http://pre-signed-S3-url-for-response", "ResourceType" : "Custom::SeleniumTester", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] }, "OldResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } } ``` Para obter informações detalhadas sobre o objeto de solicitação para as solicitações `Update`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). 1. O provedor de recursos personalizados realiza o processamento dos dados enviados pelo CloudFormation. O recurso personalizado executa a atualização e envia uma resposta de `SUCCESS` ou de `FAILED` para o URL do S3. Em seguida, o CloudFormation compara os `PhysicalResourceIDs` de recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá que a atualização requer uma substituição e enviará uma solicitação de exclusão para o recurso antigo. O exemplo a seguir demonstra a resposta do custom resource provider a uma solicitação `Update`. ``` { "Status" : "SUCCESS", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester2" } ``` Para obter informações detalhadas sobre o objeto de resposta para as solicitações `Update`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). Os campos `StackId`, `RequestId` e `LogicalResourceId` devem ser copiados na íntegra da solicitação. 1. O CloudFormation declara o status da pilha como `UPDATE_COMPLETE` ou `UPDATE_FAILED`. Em caso de falha na atualização, a pilha é revertida. Caso a pilha tenha sido atualizada com êxito, o template developer poderá acessar todos os novos valores de saída do recurso personalizado criado com `Fn::GetAtt`. ### Etapa 3: Exclusão da pilha 1. O desenvolvedor do modelo exclui uma pilha que contém um recurso personalizado. O CloudFormation obtém as propriedades atuais especificadas no modelo de pilha em conjunto com o tópico do SNS e se prepara para fazer uma solicitação ao provedor de recursos personalizados. 1. O CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um `"RequestType" : "Delete"` que contém informações atuais sobre a pilha, as propriedades do recurso personalizado do modelo da pilha e um URL de S3 para a resposta. Sempre que você exclui uma pilha ou faz uma atualização que remove ou substitui o recurso personalizado, o CloudFormation compara o `PhysicalResourceId` entre os recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo (`OldPhysicalResource`), conforme mostrado no exemplo a seguir de uma solicitação `Delete`. ``` { "RequestType" : "Delete", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "ResponseURL" : "http://pre-signed-S3-url-for-response", "ResourceType" : "Custom::SeleniumTester", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] } } ``` Para obter informações detalhadas sobre o objeto de solicitação para as solicitações `Delete`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). `DescribeStackResource`, `DescribeStackResources`e `ListStackResources` exibem o nome definido pelo usuário caso ele tenha sido especificado. 1. O provedor de recursos personalizados realiza o processamento dos dados enviados pelo CloudFormation e determina se a solicitação `Delete` ocorreu com êxito. O provedor de recursos usa o URL do S3 enviado pelo CloudFormation para enviar uma resposta de `SUCCESS` ou de `FAILED`. Para excluir com êxito uma pilha com um recurso personalizado, o custom resource provider devem responder com êxito a uma solicitação de exclusão. Este é um exemplo de uma resposta do custom resource provider a uma solicitação `Delete`: ``` { "Status" : "SUCCESS", "RequestId" : "unique-request-id", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1" } ``` Para obter informações detalhadas sobre o objeto de resposta para as solicitações `Delete`, consulte o tópico [Referência de solicitações e respostas](crpg-ref.md). Os campos `StackId`, `RequestId` e `LogicalResourceId` devem ser copiados na íntegra da solicitação. 1. O CloudFormation declara o status da pilha como `DELETE_COMPLETE` ou `DELETE_FAILED`.