Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Tags e o AWS CDK
As tags são elementos de chave-valor informativos que podem ser adicionados aos constructos da sua aplicação do CDK da AWS. Uma tag aplicada a um determinado constructo também se aplica a todos os seus filhos que podem receber tags. As tags são incluídas no modelo sintetizado do AWS CloudFormation a partir da sua aplicação e aplicadas aos recursos AWS que ele implanta. É possível usar tags para identificar e categorizar os recursos para as seguintes finalidades:
+ Simplificando o gerenciamento
+ Alocação de custos
+ Controle de acesso
+ Quaisquer outros propósitos que você conceba
**dica**
Para obter mais informações sobre como é possível usar tags com seus recursos da AWS, consulte [Práticas recomendadas para aplicação de tags em recursos da AWS](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html) no *Whitepaper da AWS*.
## Usar tags
A classe [Tags](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html) inclui o método estático `of()`, por meio do qual é possível adicionar ou remover tags do constructo especificado.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#addkey-value-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#addkey-value-props) aplica uma nova tag ao constructo fornecido e a todos os seus filhos.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#removekey-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#removekey-props) remove uma tag de um determinado constructo e de qualquer um de seus filhos, incluindo tags que um constructo secundário possa ter aplicado a si mesmo.
**nota**
A aplicação de tags é implementada usando [Aspectos e o AWS CDK](aspects.md). Aspectos são uma forma de aplicar uma operação (como as tags) a todos os constructos em um determinado escopo.
O exemplo a seguir aplica a tag **key** com o valor **value** a um constructo.
**Example**
```
Tags.of(myConstruct).add('key', 'value');
```
```
Tags.of(myConstruct).add('key', 'value');
```
```
Tags.of(my_construct).add("key", "value")
```
```
Tags.of(myConstruct).add("key", "value");
```
```
Tags.Of(myConstruct).Add("key", "value");
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{})
```
O exemplo a seguir exclui a tag **key** de um constructo.
**Example**
```
Tags.of(myConstruct).remove('key');
```
```
Tags.of(myConstruct).remove('key');
```
```
Tags.of(my_construct).remove("key")
```
```
Tags.of(myConstruct).remove("key");
```
```
Tags.Of(myConstruct).Remove("key");
```
```
awscdk.Tags_Of(myConstruct).Remove(jsii.String("key"), &awscdk.TagProps{})
```
Se você estiver usando constructos `Stage`, aplique a tag no nível `Stage` ou abaixo. As tags não são aplicadas além dos limites `Stage`.
## Prioridades de tags
O AWS CDK aplica e remove tags recursivamente. Se houver conflitos, a operação de tag com a prioridade mais alta vence. (As prioridades são definidas usando a propriedade opcional `priority`.) Se as prioridades de duas operações forem as mesmas, a operação com tag mais próxima da parte inferior da árvore de constructo vence. Por padrão, a aplicação de uma tag tem uma prioridade de 100 (exceto as tags adicionadas diretamente a um recurso do AWS CloudFormation, que tem uma prioridade de 50). A prioridade padrão para remover uma tag é 200.
O seguinte aplica uma tag com prioridade de 300 a uma constructo.
**Example**
```
Tags.of(myConstruct).add('key', 'value', {
priority: 300
});
```
```
Tags.of(myConstruct).add('key', 'value', {
priority: 300
});
```
```
Tags.of(my_construct).add("key", "value", priority=300)
```
```
Tags.of(myConstruct).add("key", "value", TagProps.builder()
.priority(300).build());
```
```
Tags.Of(myConstruct).Add("key", "value", new TagProps { Priority = 300 });
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{
Priority: jsii.Number(300),
})
```
## Propriedades opcionais
As tags oferecem suporte ao [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.TagProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.TagProps.html) que ajusta a forma como as tags são aplicadas ou removidas dos recursos. Todas as propriedades são opcionais.
`applyToLaunchedInstances` (Python: `apply_to_launched_instances`)
Disponível somente para add(). Por padrão, as tags são aplicadas às instâncias executadas em um grupo do Auto Scaling. Defina essa propriedade como **false** para ignorar instâncias iniciadas em um grupo do Auto Scaling.
`includeResourceTypes`/`excludeResourceTypes` (Python: `include_resource_types`/`exclude_resource_types`)
Use para manipular tags somente em um subconjunto de recursos, com base nos tipos de recursos do AWS CloudFormation. Por padrão, a operação é aplicada a todos os recursos na subárvore de constructo, mas isso pode ser alterado incluindo ou excluindo determinados tipos de recursos. Excluir tem precedência sobre incluir, se ambas forem especificadas.
`priority`
Use isso para definir a prioridade dessa operação em relação a outras operações `Tags.add()` e `Tags.remove()`. Valores mais altos têm precedência sobre valores mais baixos. O padrão é 100 para operações de adição (50 para tags aplicadas diretamente aos recursos do AWS CloudFormation) e 200 para operações de remoção.
O exemplo a seguir aplica a tag **tagname** com o valor **value** e a prioridade **100** aos recursos do tipo **AWS::Xxx::Yyy** no constructo. Ele não aplica a tag a instâncias lançadas em um grupo do Amazon EC2 Auto Scaling ou a recursos do tipo **AWS::Xxx::Zzz**. (Esses são espaços reservados para dois tipos de recursos arbitrários do AWS CloudFormation, mas diferentes.)
**Example**
```
Tags.of(myConstruct).add('tagname', 'value', {
applyToLaunchedInstances: false,
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 100,
});
```
```
Tags.of(myConstruct).add('tagname', 'value', {
applyToLaunchedInstances: false,
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 100
});
```
```
Tags.of(my_construct).add("tagname", "value",
apply_to_launched_instances=False,
include_resource_types=["AWS::Xxx::Yyy"],
exclude_resource_types=["AWS::Xxx::Zzz"],
priority=100)
```
```
Tags.of(myConstruct).add("tagname", "value", TagProps.builder()
.applyToLaunchedInstances(false)
.includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
.excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
.priority(100).build());
```
```
Tags.Of(myConstruct).Add("tagname", "value", new TagProps
{
ApplyToLaunchedInstances = false,
IncludeResourceTypes = ["AWS::Xxx::Yyy"],
ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
Priority = 100
});
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("tagname"), jsii.String("value"), &awscdk.TagProps{
ApplyToLaunchedInstances: jsii.Bool(false),
IncludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Yyy")},
ExcludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Zzz")},
Priority: jsii.Number(100),
})
```
O exemplo a seguir remove a tag **tagname** com prioridade **200** de recursos do tipo **AWS::Xxx::Yyy** no constructo, mas não de recursos do tipo **AWS::Xxx::Zzz**.
**Example**
```
Tags.of(myConstruct).remove('tagname', {
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 200,
});
```
```
Tags.of(myConstruct).remove('tagname', {
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 200
});
```
```
Tags.of(my_construct).remove("tagname",
include_resource_types=["AWS::Xxx::Yyy"],
exclude_resource_types=["AWS::Xxx::Zzz"],
priority=200,)
```
```
Tags.of((myConstruct).remove("tagname", TagProps.builder()
.includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
.excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
.priority(100).build());
)
```
```
Tags.Of(myConstruct).Remove("tagname", new TagProps
{
IncludeResourceTypes = ["AWS::Xxx::Yyy"],
ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
Priority = 100
});
```
```
awscdk.Tags_Of(myConstruct).Remove(jsii.String("tagname"), &awscdk.TagProps{
IncludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Yyy")},
ExcludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Zzz")},
Priority: jsii.Number(200),
})
```
## Exemplo
O exemplo a seguir adiciona a tag chave **StackType** com o valor **TheBest** a qualquer recurso criado dentro do `Stack` chamado `MarketingSystem`. Em seguida, ele o remove novamente de todos os recursos, exceto das sub-redes VPC do Amazon EC2. O resultado é que somente as sub-redes têm a tag aplicada.
**Example**
```
import { App, Stack, Tags } from 'aws-cdk-lib';
const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
excludeResourceTypes: ['AWS::EC2::Subnet']
});
```
```
const { App, Stack, Tags } = require('aws-cdk-lib');
const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
excludeResourceTypes: ['AWS::EC2::Subnet']
});
```
```
from aws_cdk import App, Stack, Tags
app = App();
the_best_stack = Stack(app, 'MarketingSystem')
# Add a tag to all constructs in the stack
Tags.of(the_best_stack).add("StackType", "TheBest")
# Remove the tag from all resources except subnet resources
Tags.of(the_best_stack).remove("StackType",
exclude_resource_types=["AWS::EC2::Subnet"])
```
```
import software.amazon.awscdk.App;
import software.amazon.awscdk.Tags;
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add("StackType", "TheBest");
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove("StackType", TagProps.builder()
.excludeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
.build());
```
```
using Amazon.CDK;
var app = new App();
var theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.Of(theBestStack).Add("StackType", "TheBest");
// Remove the tag from all resources except subnet resources
Tags.Of(theBestStack).Remove("StackType", new TagProps
{
ExcludeResourceTypes = ["AWS::EC2::Subnet"]
});
```
```
import "github.com/aws/aws-cdk-go/awscdk/v2"
app := awscdk.NewApp(nil)
theBestStack := awscdk.NewStack(app, jsii.String("MarketingSystem"), &awscdk.StackProps{})
// Add a tag to all constructs in the stack
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{})
// Remove the tag from all resources except subnet resources
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
ExcludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})
```
O código a seguir obtém o mesmo resultado. Considere qual abordagem (inclusão ou exclusão) torna sua intenção mais clara.
**Example**
```
Tags.of(theBestStack).add('StackType', 'TheBest',
{ includeResourceTypes: ['AWS::EC2::Subnet']});
```
```
Tags.of(theBestStack).add('StackType', 'TheBest',
{ includeResourceTypes: ['AWS::EC2::Subnet']});
```
```
Tags.of(the_best_stack).add("StackType", "TheBest",
include_resource_types=["AWS::EC2::Subnet"])
```
```
Tags.of(theBestStack).add("StackType", "TheBest", TagProps.builder()
.includeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
.build());
```
```
Tags.Of(theBestStack).Add("StackType", "TheBest", new TagProps {
IncludeResourceTypes = ["AWS::EC2::Subnet"]
});
```
```
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
IncludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})
```
## Aplicar tags de constructos individuais
`Tags.of(scope).add(key, value)` é a forma padrão de adicionar tags aos constructos no AWS CDK. Seu comportamento de caminhar em árvores, que aplica tags recursivamente todos os recursos que podem ter aplicação de tag sob um determinado escopo, é quase sempre o que você deseja. Às vezes, no entanto, você precisa aplicat tags a um constructo (ou constructos) específico e arbitrário.
Um desses casos envolve a aplicação de tags cujo valor é derivado de alguma propriedade do constructo que está tendo a aplicação de tag. A abordagem de aplicação de tags padrão aplica recursivamente a mesma chave e valor a todos os recursos correspondentes no escopo. No entanto, aqui o valor pode ser diferente para cada constructo com tags.
As tags são implementadas usando [aspectos](aspects.md), e o CDK chama o método `visit()` da tag para cada constructo sob o escopo que você especificou usando o `Tags.of(scope)`. Podemos chamar o `Tag.visit()` diretamente para aplicar uma tag a um único constructo.
**Example**
```
new cdk.Tag(key, value).visit(scope);
```
```
new cdk.Tag(key, value).visit(scope);
```
```
cdk.Tag(key, value).visit(scope)
```
```
Tag.Builder.create(key, value).build().visit(scope);
```
```
new Tag(key, value).Visit(scope);
```
```
awscdk.NewTag(key, value, &awscdk.TagProps{}).Visit(scope)
```
É possível marcar todos os constructos em um escopo, mas deixar que os valores das tags sejam derivados das propriedades de cada constructo. Para fazer isso, escreva um aspecto e aplique a tag no método `visit()` do aspecto, conforme mostrado no exemplo anterior. Em seguida, adicione o aspecto ao escopo desejado usando `Aspects.of(scope).add(aspect)`.
O exemplo a seguir aplica uma tag a cada recurso em uma pilha contendo o caminho do recurso.
**Example**
```
class PathTagger implements cdk.IAspect {
visit(node: IConstruct) {
new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
}
}
stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
```
```
class PathTagger {
visit(node) {
new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
}
}
stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
```
```
@jsii.implements(cdk.IAspect)
class PathTagger:
def visit(self, node: IConstruct):
cdk.Tag("aws-cdk-path", node.node.path).visit(node)
stack = MyStack(app)
cdk.Aspects.of(stack).add(PathTagger())
```
```
final class PathTagger implements IAspect {
public void visit(IConstruct node) {
Tag.Builder.create("aws-cdk-path", node.getNode().getPath()).build().visit(node);
}
}
stack stack = new MyStack(app);
Aspects.of(stack).add(new PathTagger());
```
```
public class PathTagger : IAspect
{
public void Visit(IConstruct node)
{
new Tag("aws-cdk-path", node.Node.Path).Visit(node);
}
}
var stack = new MyStack(app);
Aspects.Of(stack).Add(new PathTagger);
```
**dica**
A lógica da marcação condicional, incluindo prioridades, tipos de recursos e assim por diante, é incorporada à classe `Tag`. É possível usar esses recursos ao aplicar tags a recursos arbitrários; a tag não é aplicada se as condições não forem atendidas. Além disso, a classe `Tag` só aplica tags em recursos aplicáveis, então você não precisa testar se um constructo pode ser aplicável antes de aplicar uma tag.