# Criar uma definição de macro do CloudFormation
Quando você cria uma definição de macro, ela disponibiliza a função do Lambda subjacente na conta especificada para que o CloudFormation possa invocá-la ao processar os modelos.
## Mapeamento de eventos
Quando o CloudFormation invoca a função do Lambda de uma macro, ele envia uma solicitação no formato JSON com a seguinte estrutura:
```
{
"region" : "{{us-east-1}}",
"accountId" : "{{$ACCOUNT_ID}}",
"fragment" : { {{...}} },
"transformId" : "{{$TRANSFORM_ID}}",
"params" : { {{...}} },
"requestId" : "{{$REQUEST_ID}}",
"templateParameterValues" : { {{...}} }
}
```
+ `region`
A região na qual a macro reside.
+ `accountId`
O ID de conta da conta da qual a macro está invocando a função Lambda.
+ `fragment`
O conteúdo do modelo disponível para processamento personalizado, no formato JSON.
+ Para macros incluídas no modelo `Transform`, essa seção é o modelo inteiro, exceto pela seção `Transform`.
+ Para macros incluídas em uma chamada de função intrínseca `Fn::Transform`, isso inclui todos os nós irmãos (e os filhos deles) com base na localização da função intrínseca no modelo, exceto pela função `Fn::Transform`. Para obter mais informações, consulte [Escopo de modelo de macro](#template-macros-scope).
+ `transformId`
O nome da macro que invoca essa função.
+ `params`
Para chamadas à função `Fn::Transform`, quaisquer parâmetros especificados para a função. O CloudFormation não avalia esses parâmetros antes de passá-los para a função.
Para macros incluídas na seção do modelo `Transform`, essa seção é vazia.
+ `requestId`
O ID da solicitação que invoca essa função.
+ `templateParameterValues`
Quaisquer parâmetros especificados na seção [Parameters](parameters-section-structure.md) do modelo. O CloudFormation avalia esses parâmetros antes de passá-los para a função.
## Formato de resposta
O CloudFormation espera que a função do Lambda subjacente retorne uma resposta no seguinte formato JSON:
```
{
"requestId" : "{{$REQUEST_ID}}",
"status" : "{{$STATUS}}",
"fragment" : { {{...}} },
"errorMessage": "optional error message for failures"
}
```
+ `requestId`
O ID da solicitação que invoca essa função. Isso deve corresponder ao ID de solicitação fornecido pelo CloudFormation ao invocar a função.
+ `status`
O status da solicitação (não diferencia maiúsculas de minúsculas). Ele deve ser definido como `success`. O CloudFormation trata qualquer outra resposta como uma falha.
+ `fragment`
O conteúdo do modelo processado para o CloudFormation incluir no modelo processado, incluindo irmãos. O CloudFormation substitui o conteúdo do modelo que é transmitido para a função do Lambda pelo fragmento de modelo que ele recebe na resposta do Lambda.
O conteúdo do modelo processado deve ser um JSON válido, e sua inclusão no modelo processado deve resultar em um modelo válido.
Se a função não chegar a alterar o conteúdo do modelo que o CloudFormation transmite a ela, mas você ainda precisar incluir esse conteúdo no modelo processado, a função precisará retornar conteúdo do modelo ao CloudFormation em sua resposta.
+ `errorMessage`
A mensagem de erro que explica por que a transformação falhou. O CloudFormation exibe a mensagem de erro no painel **Events** (Eventos) da página **Stack details** (Detalhes da pilha) para sua nova pilha.
Por exemplo:
```
Error creating change set: Transform
{{Conta da AWS account
number}}::{{macro name}} failed with:
{{error message string}}.
```
## Criar uma definição de macro
**Para criar uma definição de macro do CloudFormation**
1. [Desenvolva uma função do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) que processe o conteúdo de um modelo. Ela pode processar qualquer parte de um modelo, até o modelo inteiro.
1. Crie um modelo do CloudFormation contendo um tipo de recurso `AWS::CloudFormation::Macro` e especifique as propriedades `Name` e `FunctionName`. A propriedade `FunctionName` deve conter o ARN da função do Lambda a ser invocada quando o CloudFormation executar a macro.
1. (opcional) Para ajudar na depuração, você também pode especificar as propriedades `LogGroupName` e `LogRoleArn` ao criar o tipo de recurso `AWS::CloudFormation::Macro` para a macro. Essas propriedades permitem especificar o grupo de logs do CloudWatch para o qual o CloudFormation envia informações de registro de erros em log ao invocar a função do Lambda subjacente da macro e o perfil que o CloudFormation deve assumir ao enviar entradas para esses logs.
1. [Crie uma pilha](cfn-console-create-stack.md) usando o modelo com a macro na conta em que você deseja usá-la. Ou [crie um conjunto de pilhas com permissões autogerenciadas](stacksets-getting-started-create-self-managed.md) usando o modelo com a macro na conta de administrador, depois crie instâncias de pilhas nas contas de destino.
1. Depois que o CloudFormation criar com êxito as pilhas que contêm a definição da macro, ela estará disponível para uso nessas contas. Você usa uma macro fazendo referência a ela em um modelo, no local apropriado relevante para o conteúdo do modelo que você deseja processar.
## Escopo de modelo de macro
Macros referenciadas na seção `Transform` de um modelo podem processar todo o conteúdo desse modelo.
Macros referenciadas em uma função `Fn::Transform` podem processar o conteúdo de qualquer um dos elementos irmãos (incluindo filhos) dessa função `Fn::Transform` no modelo.
Por exemplo, no modelo de exemplo abaixo, `AWS::Include` pode processar todas as propriedades `MyBucket` com base na localização da função `Fn::Transform` que o contém. `MyMacro` pode processar o conteúdo de todo o modelo devido à sua inclusão na seção `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
```
## Ordem de avaliação de macros
É possível fazer referência a várias macros em um determinado modelo, incluindo transformações hospedadas pelo 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) e [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html).
As macros são avaliadas em ordem, com base na sua localização no modelo, da mais profundamente aninhada até a mais genérica. Macros no mesmo local do modelo são avaliadas em série com base na ordem em que estão listadas.
Transformações como `AWS::Include` e `AWS::Transform` são tratadas como qualquer outra macro em termos de ordem e escopo de ação.
Por exemplo, no modelo de exemplo abaixo, o CloudFormation avalia primeiro a macro `PolicyAdder`, pois ela é a mais profundamente aninhada no modelo. Depois, o CloudFormation avalia `MyMacro` antes de avaliar `AWS::Serverless` porque ela está listada antes de `AWS::Serverless` na seção `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}}
```