# Creación de una definición de macro de CloudFormation
Al crear una definición de macro, la definición de macro hace que la función de Lambda subyacente esté disponible en la cuenta especificada, de modo que CloudFormation la llame para procesar las plantillas.
## Mapeo de eventos
Cuando CloudFormation invoca la función de Lambda de una macro, envía una solicitud en formato JSON con la siguiente estructura:
```
{
"region" : "us-east-1",
"accountId" : "$ACCOUNT_ID",
"fragment" : { ... },
"transformId" : "$TRANSFORM_ID",
"params" : { ... },
"requestId" : "$REQUEST_ID",
"templateParameterValues" : { ... }
}
```
+ `region`
La región en la que la reside la macro.
+ `accountId`
El ID de la cuenta desde la que la macro invoca la función de Lambda.
+ `fragment`
El contenido de la plantilla disponible para el procesamiento personalizado, en formato JSON.
+ Para las macros incluidas en la sección de plantilla `Transform`, esto es toda la plantilla, a excepción de la sección `Transform`.
+ Para macros incluidas en una llamada de función intrínseca `Fn::Transform`, esto incluye todos los nodos secundarios (y sus hijos) en función de la ubicación de la función intrínseca dentro de la plantilla, excepto para la función `Fn::Transform`. Para obtener más información, consulte [Alcance de la plantilla de macro](#template-macros-scope).
+ `transformId`
El nombre de la macro que invoca esta función.
+ `params`
Para las llamadas de la función `Fn::Transform`, todos los parámetros especificados para la función. CloudFormation no evalúa estos parámetros antes de transferirlos a la función.
Para macros incluidas en la sección de plantilla `Transform`, esta sección está vacía.
+ `requestId`
El ID de la solicitud que invoca esta función.
+ `templateParameterValues`
Todos los parámetros especificados en la sección [Parameters](parameters-section-structure.md) de la plantilla. CloudFormation evalúa estos parámetros antes de transferirlos a la función.
## Formato de respuesta
CloudFormation espera que la función de Lambda devuelva una respuesta con el siguiente formato JSON:
```
{
"requestId" : "$REQUEST_ID",
"status" : "$STATUS",
"fragment" : { ... },
"errorMessage": "optional error message for failures"
}
```
+ `requestId`
El ID de la solicitud que invoca esta función. Debe coincidir con el ID de la solicitud que proporciona CloudFormation al invocar la función.
+ `status`
El estado de la solicitud (no distingue entre mayúsculas y minúsculas). Debe definirse en `success`. CloudFormation trata todas las demás respuestas como error.
+ `fragment`
El contenido de la plantilla procesada para que CloudFormation lo incluya en la plantilla procesada, incluidos los elementos secundarios. CloudFormation sustituye el contenido de la plantilla que se transfiere a la función de Lambda con el fragmento de código de plantilla que recibe en la respuesta de Lambda.
El contenido de la plantilla procesada tiene que ser un formato JSON válido, y su inclusión en la plantilla procesada debe generar una plantilla válida.
Si la función no cambia realmente el contenido de la plantilla que CloudFormation le pasa, pero el usuario sigue necesitando incluir ese contenido en la plantilla procesada, la función debe devolver dicho contenido de plantilla a CloudFormation en su respuesta.
+ `errorMessage`
El mensaje de error que explica por qué falló la transformación. CloudFormation muestra este mensaje de error en el panel **Events** (Eventos) de la página **Stack details** (Detalles de la pila) para la pila.
Por ejemplo:
```
Error creating change set: Transform
Cuenta de AWS account
number::macro name failed with:
error message string.
```
## Creación de una definición de macro
**Crear una definición de macro de CloudFormation**
1. [Cree una función de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) que se encargue del procesamiento del contenido de la plantilla. Puede procesar cualquier parte de una plantilla, incluso la plantilla completa.
1. Cree una plantilla de CloudFormation que contenga un tipo de recurso `AWS::CloudFormation::Macro` y especifique las propiedades `Name` y `FunctionName`. La propiedad `FunctionName` debe contener el ARN de la función de Lambda para invocar cuándo CloudFormation ejecuta la macro.
1. (Opcional) Para ayudar en la depuración, también puede especificar las propiedades `LogGroupName` y `LogRoleArn` cuando cree el tipo de recurso `AWS::CloudFormation::Macro` para su macro. Estas propiedades le permiten especificar el grupo de registro de Registros de CloudWatch al que CloudFormation envía la información de registro de errores al invocar la función de Lambda subyacente de la macro y el rol que CloudFormation debe asumir al enviar entradas de registro a dichos registros.
1. [Cree una pila](cfn-console-create-stack.md) utilizando la plantilla con la macro de la cuenta en la que desee utilizarla. O [cree un conjunto de pilas con permisos autoadministrados](stacksets-getting-started-create-self-managed.md) mediante la plantilla con la macro en la cuenta de administrador y, a continuación, cree instancias de pilas en las cuentas de destino.
1. Una vez que CloudFormation haya creado correctamente las pilas que contienen la definición de la macro, esta estará disponible para su uso en dichas cuentas. Una macro se utiliza haciendo referencia a ella en una plantilla, en la ubicación adecuada relevante para el contenido de la plantilla que desea procesar.
## Alcance de la plantilla de macro
Las macros a las que se hace referencia en la sección `Transform` de una plantilla pueden procesar todo el contenido de dicha plantilla.
Las macros a las que se hace referencia en una función `Fn::Transform` pueden procesar el contenido de cualquiera de los elementos del mismo nivel (incluidos los elementos secundarios) de dicha función `Fn::Transform` en la plantilla.
Por ejemplo, en la siguiente plantilla de ejemplo, `AWS::Include` puede procesar todas las propiedades `MyBucket`, en función de la ubicación de la función `Fn::Transform` que lo contiene. `MyMacro` puede procesar el contenido de toda la plantilla debido a su inclusión en la sección `Transform`.
```
# Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
# Start of processable content for AWS::Include
Properties:
BucketName: amzn-s3-demo-bucket1
Tags: [{"key":"value"}]
'Fn::Transform':
- Name: 'AWS::Include'
Parameters:
Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
CorsConfiguration: []
# End of processable content for AWS::Include
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro
```
## Orden de evaluación de macro
Puede consultar varias macros de una determinada plantilla, incluidas transformaciones alojadas por CloudFormation, como [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html) y [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html).
Las macros se evalúan en orden, en función de su ubicación en la plantilla, desde la que esté más profundamente anidada hasta la más general. Las macros que están en la misma ubicación de la plantilla se evalúan en serie en función del orden en que aparecen en la lista.
Las transformaciones como, por ejemplo, `AWS::Include` y `AWS::Transform`, se tratan de la misma manera que cualquier otra macro en términos de orden y ámbito de acción.
Por ejemplo, en la siguiente plantilla de ejemplo, CloudFormation evalúa primero la macro `PolicyAdder`, ya que es la macro que está anidada más profundamente en la plantilla. A continuación, CloudFormation evalúa `MyMacro` antes de evaluar `AWS::Serverless`, ya que aparece antes de `AWS::Serverless` en la sección `Transform`.
```
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro, AWS::Serverless]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: amzn-s3-demo-bucket
Tags: [{"key":"value"}]
'Fn::Transform':
- Name: PolicyAdder
CorsConfiguration: []
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: ami-1234567890abcdef0
```