# Referencia de solicitud y respuesta de recursos personalizados de CloudFormation
CloudFormation administra los recursos personalizados mediante un protocolo de solicitud-respuesta que se comunica con su proveedor de recursos personalizados. Cada solicitud incluye un tipo de solicitud (`Create`, `Update` o `Delete`) y sigue este flujo de trabajo de alto nivel:
1. Un desarrollador de plantillas define un recurso personalizado con un `ServiceToken` y `ServiceTimeout` en la plantilla e inicia una operación de pila.
1. CloudFormation envía una solicitud JSON al proveedor de recursos personalizados a través de SNS o Lambda.
1. El proveedor de recursos personalizados procesa la solicitud y devuelve una respuesta JSON a una URL de bucket de Amazon S3 prefirmada antes de que venza el tiempo de espera.
1. CloudFormation lee la respuesta y continúa con la operación de la pila. Si no se recibe respuesta alguna antes de que finalice el tiempo de espera, se considera que la solicitud no se ha realizado en la forma correcta y la operación de la pila fallará.
Para obtener más información, consulte [Cómo funcionan los recursos personalizados](template-custom-resources.md#how-custom-resources-work).
En esta sección se describen la estructura, los parámetros y las respuestas esperadas para cada tipo de solicitud.
**nota**
El tamaño total del cuerpo de la respuesta no puede superar los 4096 bytes.
## Configuración de la plantilla
Al definir un recurso personalizado en una plantilla, el desarrollador de la plantilla utiliza [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) con las siguientes propiedades:
`ServiceToken`
Un ARN de tema de Amazon SNS o un ARN de función de Lambda de la misma región que la pila.
*Obligatorio*: sí
*Tipo:* cadena
`ServiceTimeout`
El tiempo máximo, en segundos, antes de que una operación de recurso personalizado agote el tiempo de espera. Este valor debe estar entre 1 y 3600. Valor predeterminado: 3600 segundos (1 hora).
*Obligatorio*: no
*Tipo:* cadena
Se admiten las propiedades del recurso adicional. Las propiedades de los recursos se incluirán como `ResourceProperties` en la solicitud. El proveedor de recursos personalizados debe determinar qué propiedades son válidas y sus valores aceptables.
## Objeto de solicitud
------
#### [ Create ]
Cuando el desarrollador de la plantilla crea una pila que contiene un recurso personalizado, CloudFormation envía una solicitud con `RequestType` establecido en `Create`.
Cree solicitudes que contengan los siguientes campos:
`RequestType`
`Create`.
*Obligatorio*: sí
*Tipo:* cadena
`RequestId`
Un ID único para la solicitud.
La combinación de `StackId` con `RequestId` forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
*Obligatorio*: sí
*Tipo:* cadena
`StackId`
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
La combinación de `StackId` con `RequestId` forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
*Obligatorio*: sí
*Tipo:* cadena
`ResponseURL`
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceType`
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: `_@-`.
*Obligatorio*: sí
*Tipo:* cadena
`LogicalResourceId`
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceProperties`
Este campo contiene el contenido del objeto `Properties` enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
*Obligatorio*: no
*Tipo*: objeto JSON
*Ejemplo*
```
{
"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 ]
Cuando el desarrollador de la plantilla realiza cambios en las propiedades de un recurso personalizado dentro de la plantilla y actualiza la pila, CloudFormation envía una solicitud al proveedor del recurso personalizado con `RequestType` establecido en `Update`. Esto significa que el código de su recurso personalizado no tiene que detectar cambios en los recursos, porque sabe que sus propiedades cambiaron cuando el tipo de solicitud es `Update`.
Actualice solicitudes que contengan los siguientes campos:
`RequestType`
`Update`.
*Obligatorio*: sí
*Tipo:* cadena
`RequestId`
Un ID único para la solicitud.
La combinación de `StackId` con `RequestId` forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
*Obligatorio*: sí
*Tipo:* cadena
`StackId`
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
La combinación de `StackId` con `RequestId` forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
*Obligatorio*: sí
*Tipo:* cadena
`ResponseURL`
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceType`
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: `_@-`. No puede cambiar el tipo durante una actualización.
*Obligatorio*: sí
*Tipo:* cadena
`LogicalResourceId`
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`PhysicalResourceId`
Un ID físico definido por el proveedor de recursos personalizados que es exclusivo de dicho proveedor.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceProperties`
Este campo contiene el contenido del objeto `Properties` enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
*Obligatorio*: no
*Tipo*: objeto JSON
`OldResourceProperties`
Usado solo para solicitudes `Update`. Los valores de propiedades de recursos declarados con anterioridad por el desarrollador de plantillas en la plantilla de CloudFormation.
*Obligatorio*: sí
*Tipo*: objeto JSON
*Ejemplo*
```
{
"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 ]
Cuando el desarrollador de la plantilla elimina la pila o elimina el recurso personalizado de la pila y, a continuación, actualiza la pila, CloudFormation envía una solicitud con `RequestType` establecido en `Delete`.
Elimine las solicitudes que contienen los siguientes campos:
`RequestType`
`Delete`.
*Obligatorio*: sí
*Tipo:* cadena
`RequestId`
Un ID único para la solicitud.
*Obligatorio*: sí
*Tipo:* cadena
`StackId`
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
*Obligatorio*: sí
*Tipo:* cadena
`ResponseURL`
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceType`
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: `_@-`.
*Obligatorio*: sí
*Tipo:* cadena
`LogicalResourceId`
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
*Obligatorio*: sí
*Tipo:* cadena
`PhysicalResourceId`
Un ID físico definido por el proveedor de recursos personalizados que es exclusivo de dicho proveedor.
*Obligatorio*: sí
*Tipo:* cadena
`ResourceProperties`
Este campo contiene el contenido del objeto `Properties` enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
*Obligatorio*: no
*Tipo*: objeto JSON
*Ejemplo*
```
{
"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 de respuesta
El proveedor de recursos personalizados envía una respuesta a la URL prefirmada para todos los tipos de recursos. Si el proveedor de recursos personalizados no envía una respuesta, CloudFormation espera hasta que se agote el tiempo de espera de la operación.
La respuesta debe ser un objeto JSON con los campos siguientes:
`Status`
Debe ser `SUCCESS` o `FAILED`.
*Obligatorio*: sí
*Tipo:* cadena
`RequestId`
Un ID único para la solicitud. Copie este valor exactamente como aparece en la solicitud.
*Obligatorio*: sí
*Tipo:* cadena
`StackId`
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado. Copie este valor exactamente como aparece en la solicitud.
*Obligatorio*: sí
*Tipo:* cadena
`LogicalResourceId`
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation. Copie este valor exactamente como aparece en la solicitud.
*Obligatorio*: sí
*Tipo:* cadena
`PhysicalResourceId`
Este valor debe ser un identificador exclusivo del proveedor de recursos personalizados y puede tener un tamaño máximo de 1 KB. El valor debe ser una cadena que no esté vacía y debe ser idéntica para todas las respuestas del mismo recurso.
Al actualizar los recursos personalizados, el valor devuelto para `PhysicalResourceId` determina el comportamiento de la actualización. Si el valor devuelto es el mismo, CloudFormation lo considera una actualización normal. Si el valor cambia, CloudFormation interpreta la actualización como un reemplazo y envía una solicitud de eliminación al antiguo recurso. Para obtener más información, 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).
*Obligatorio*: sí
*Tipo:* cadena
`Reason`
Describe el motivo de una respuesta de error.
Obligatorio si `Status` es `FAILED`. De lo contrario, es opcional.
*Obligatorio*: condicional
*Tipo:* cadena
`NoEcho`
Indique si se enmascara la salida del recurso personalizado cuando se recupera con la función `Fn::GetAtt`. Si se establece en `true`, todos los valores devueltos se enmascaran con asteriscos (\$1\$1\$1\$1\$1), *excepto los almacenados en la sección `Metadata` de la plantilla*. CloudFormation no transforma, modifica ni redacta ninguna información que incluya en la sección `Metadata`. El valor predeterminado es `false`.
Para obtener más información sobre el uso de `NoEcho` para enmascarar información confidencial, consulte la práctica recomendada de [No integre credenciales en sus plantillas](security-best-practices.md#creds).
Disponible solo para respuestas `Create` y `Update`. No se admite para las respuestas `Delete`.
*Obligatorio*: no
*Tipo*: booleano
`Data`
Los pares de nombre-valor definidos por el proveedor de recursos personalizados que se enviarán con la respuesta. Puede acceder a los valores proporcionados aquí por nombre en la plantilla con `Fn::GetAtt`.
Disponible solo para respuestas `Create` y `Update`. No se admite para las respuestas `Delete`.
Si los pares nombre-valor contienen información confidencial, debe usar el campo `NoEcho` para enmascarar la salida del recurso personalizado. De lo contrario, los valores son visibles a través de las API que muestran valores de propiedades (como `DescribeStackEvents`).
*Obligatorio*: no
*Tipo*: objeto JSON
### Ejemplos de respuestas satisfactorias
#### Respuesta `Create` y `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`Respuesta de
```
{
"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"
}
```
### Respuesta de ejemplo con error
```
{
"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"
}
```