# Referência personalizada de solicitações e respostas de recursos do CloudFormation
O CloudFormation gerencia recursos personalizados por meio de um protocolo de solicitação-resposta que se comunica com seu provedor de recursos personalizados. Cada solicitação inclui um tipo de solicitação (`Create`, `Update` ou `Delete`) e segue esse fluxo de trabalho de alto nível:
1. Um desenvolvedor de modelos define um recurso personalizado com um `ServiceToken` e `ServiceTimeout` no modelo e inicia uma operação de pilha.
1. O CloudFormation envia uma solicitação JSON ao provedor de recursos personalizados por meio do SNS ou do Lambda.
1. O provedor de recursos personalizados processa a solicitação e retorna uma resposta JSON para um URL pré-assinado do bucket do Amazon S3 antes que o período de tempo limite expire.
1. O CloudFormation lê a resposta e prossegue para a operação da pilha. Se nenhuma resposta for recebida antes do tempo limite terminar, a solicitação será considerada malsucedida e a operação de pilha falhará.
Para obter mais informações, consulte [Como os recursos personalizados funcionam](template-custom-resources.md#how-custom-resources-work).
Esta seção descreve a estrutura, os parâmetros e as respostas esperadas para cada tipo de solicitação.
**nota**
O tamanho total do corpo da resposta não pode exceder 4096 bytes.
## Configuração do modelo
Ao definir um recurso personalizado em um modelo, o desenvolvedor do modelo usa [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html) com as seguintes propriedades:
`ServiceToken`
Um ARN de tópico do Amazon SNS ou um ARN de função do Lambda da mesma região que a pilha.
*Obrigatório*: Sim
*Tipo:* string
`ServiceTimeout`
O tempo máximo, em segundos, antes que a operação de um recurso personalizado atinja o tempo limite. Esse valor deve estar entre 1 e 3600. Padrão: 3600 segundos (1 hora).
*Obrigatório*: não
*Tipo:* string
São compatíveis propriedades adicionais de recursos. As propriedades do recurso serão incluídas como `ResourceProperties` na solicitação. O provedor de recursos personalizados deve determinar quais propriedades são válidas e seus valores aceitáveis.
## Objeto de solicitação
------
#### [ Create ]
Quando o desenvolvedor de modelos cria uma pilha que contém um recurso personalizado, o CloudFormation envia uma solicitação com `RequestType` definido como `Create`.
Crie solicitações que contenha os seguintes campos:
`RequestType`
`Create`.
*Obrigatório*: Sim
*Tipo:* string
`RequestId`
Um ID exclusivo para a solicitação.
Combinar `StackId` com `RequestId` forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.
*Obrigatório*: Sim
*Tipo:* string
`StackId`
O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.
Combinar `StackId` com `RequestId` forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.
*Obrigatório*: Sim
*Tipo:* string
`ResponseURL`
O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`ResourceType`
O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: `_@-`.
*Obrigatório*: Sim
*Tipo:* string
`LogicalResourceId`
O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`ResourceProperties`
Esse campo apresenta o conteúdo do objeto `Properties` enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.
*Obrigatório*: não
*Tipo*: objeto JSON
*Exemplo*
```
{
"RequestType" : "Create",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-create-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
#### [ Update ]
Quando o desenvolvedor de modelos faz alterações nas propriedades de uma pilha que contém um recurso personalizado e atualiza a pilha, o CloudFormation envia uma solicitação ao provedor de recursos personalizados com `RequestType` definido como `Update`. Isso significa que o código do recurso personalizado não precisa detectar as alterações nos recursos, pois sabe que as propriedades foram alteradas quando o tipo de solicitação é `Update`.
Atualize solicitações que contenham os seguintes campos:
`RequestType`
`Update`.
*Obrigatório*: Sim
*Tipo:* string
`RequestId`
Um ID exclusivo para a solicitação.
Combinar `StackId` com `RequestId` forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.
*Obrigatório*: Sim
*Tipo:* string
`StackId`
O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.
Combinar `StackId` com `RequestId` forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.
*Obrigatório*: Sim
*Tipo:* string
`ResponseURL`
O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`ResourceType`
O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: `_@-`. Não é possível alterar o tipo durante uma atualização.
*Obrigatório*: Sim
*Tipo:* string
`LogicalResourceId`
O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`PhysicalResourceId`
Um ID físico definido por um provedor de recursos personalizados exclusivo para esse provedor.
*Obrigatório*: Sim
*Tipo:* string
`ResourceProperties`
Esse campo apresenta o conteúdo do objeto `Properties` enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.
*Obrigatório*: não
*Tipo*: objeto JSON
`OldResourceProperties`
Usado apenas para solicitações `Update`. Os valores da propriedade do recurso que foram declarados anteriormente pelo desenvolvedor do modelo no modelo do CloudFormation.
*Obrigatório*: sim
*Tipo*: objeto JSON
*Exemplo*
```
{
"RequestType" : "Update",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-update-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "new-string",
"key2" : [ "new-list" ],
"key3" : { "key4" : "new-map" }
},
"OldResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
#### [ Delete ]
Quando o desenvolvedor de modelos exclui uma pilha ou remove um recurso personalizado do modelo, e depois atualiza a pilha, o CloudFormation envia uma solicitação com `RequestType` definido como `Delete`.
Exclua solicitações que contenha os seguintes campos:
`RequestType`
`Delete`.
*Obrigatório*: Sim
*Tipo:* string
`RequestId`
Um ID exclusivo para a solicitação.
*Obrigatório*: Sim
*Tipo:* string
`StackId`
O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.
*Obrigatório*: Sim
*Tipo:* string
`ResponseURL`
O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`ResourceType`
O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: `_@-`.
*Obrigatório*: Sim
*Tipo:* string
`LogicalResourceId`
O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.
*Obrigatório*: Sim
*Tipo:* string
`PhysicalResourceId`
Um ID físico definido por um provedor de recursos personalizados exclusivo para esse provedor.
*Obrigatório*: Sim
*Tipo:* string
`ResourceProperties`
Esse campo apresenta o conteúdo do objeto `Properties` enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.
*Obrigatório*: não
*Tipo*: objeto JSON
*Exemplo*
```
{
"RequestType" : "Delete",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-delete-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
## Objeto da resposta
O provedor de recursos personalizados envia uma resposta para o URL pré-assinado para todos os tipos de solicitação. Se o provedor de recursos personalizados não enviar uma resposta, o CloudFormation vai esperar até que a operação atinja o tempo limite.
A resposta deve ser um objeto JSON com os seguintes campos:
`Status`
Deve ser `SUCCESS` ou `FAILED`.
*Obrigatório*: Sim
*Tipo:* string
`RequestId`
Um ID exclusivo para a solicitação. Copie esse valor exatamente como ele aparece na solicitação.
*Obrigatório*: Sim
*Tipo:* string
`StackId`
O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado. Copie esse valor exatamente como ele aparece na solicitação.
*Obrigatório*: Sim
*Tipo:* string
`LogicalResourceId`
O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation. Copie esse valor exatamente como ele aparece na solicitação.
*Obrigatório*: Sim
*Tipo:* string
`PhysicalResourceId`
Esse valor deve ser um identificador exclusivo do fornecedor de recursos personalizados e pode ter até 1 KB de tamanho. O valor deve ser uma string não vazia e deve ser idêntico para todas as respostas do mesmo recurso.
Ao atualizar recursos personalizados, o valor retornado de `PhysicalResourceId` determina o comportamento da atualização. Se o valor retornado permanecer o mesmo, o CloudFormation vai considerar a atualização normal. Se o valor mudar, o CloudFormation vai interpretar a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo. Para obter mais informações, consulte [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html).
*Obrigatório*: Sim
*Tipo:* string
`Reason`
Descreve o motivo de uma resposta de falha.
Obrigatório se `Status` for `FAILED`. Caso contrário, será opcional.
*Obrigatório*: Condicional
*Tipo:* string
`NoEcho`
Indica se é necessário mascarar a saída do recurso personalizado quando ela for recuperada usando a função `Fn::GetAtt`. Se definido como `true`, todos os valores retornados serão mascarados com asteriscos (\$1\$1\$1\$1\$1), *exceto os armazenados na seção `Metadata` do modelo*. O CloudFormation não transforma, modifica nem edita nenhuma informação incluída na seção `Metadata`. O valor padrão é `false`.
Para obter mais informações sobre como usar `NoEcho` para mascarar informações confidenciais, consulte a prática recomendada [Não incorporar credenciais em seus modelos](security-best-practices.md#creds).
Disponível somente para respostas `Create` e `Update`. Não é compatível com respostas `Delete`.
*Obrigatório*: não
*Tipo*: booliano
`Data`
Os pares de nome/valor definidos pelo provedor de recursos personalizados a serem enviados com a resposta. É possível acessar os valores fornecidos aqui pelo nome no modelo com `Fn::GetAtt`.
Disponível somente para respostas `Create` e `Update`. Não é compatível com respostas `Delete`.
Se os pares de nome/valor contiverem informações confidenciais, você deverá utilizar o campo `NoEcho` para mascarar a saída do recurso personalizado. Caso contrário, os valores estarão visíveis por meio de APIs que exibem valores de propriedades (como `DescribeStackEvents`).
*Obrigatório*: não
*Tipo*: objeto JSON
### Exemplos de respostas de sucesso
#### Resposta `Create` e `Update`
```
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"NoEcho": true,
"Data": {
"key1": "value1",
"key2": "value2"
}
}
```
#### `Delete`Resposta do
```
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id"
}
```
### Exemplo de resposta com falha
```
{
"Status": "FAILED",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"Reason": "Required failure reason string"
}
```