Este é o Guia do Desenvolvedor 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á.
No AWS Cloud Development Kit (AWS CDK), os tokens são espaços reservados para valores que não são conhecidos ao definir construções ou sintetizar pilhas. Esses valores serão totalmente resolvidos na implantação, quando sua infraestrutura real for criada. Ao desenvolver AWS CDK aplicativos, você trabalhará com tokens para gerenciar esses valores em todo o seu aplicativo.
Exemplo de token
A seguir temos um exemplo de uma pilha CDK que define uma constructo para um bucket do Amazon Simple Storage Service (Amazon S3). Como o nome do nosso bucket ainda não é conhecido, o valor de bucketName é armazenado como um token:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// Store value of the S3 bucket name
const myBucketName = myBucket.bucketName;
// Print the current value for the S3 bucket name at synthesis
console.log("myBucketName: " + bucketName);
}
}Quando executamos cdk synth para sintetizar nossa pilha, o valor de myBucketName será exibido no formato de token ${Token[TOKEN.. Esse formato de token é resultado de como ele AWS CDK codifica os tokens. Neste exemplo, o token é codificado como uma string:1234]}
$cdk synth --quietmyBucketName: ${Token[TOKEN.21]}
Como o valor do nome do nosso bucket não é conhecido na síntese, o token é renderizado como myBucket. Nosso AWS CloudFormation modelo usa a função <unique-hash>Ref intrínseca para referenciar seu valor, que será conhecido na implantação:
Resources:
myBucket5AF9C99B:
# ...
Outputs:
bucketNameOutput:
Description: The name of the S3 bucket
Value:
Ref: myBucket5AF9C99BPara obter mais informações sobre como o hash exclusivo é gerado, consulte Lógica gerada IDs em seu AWS CloudFormation modelo.
Passando tokens
Os tokens podem ser passados como se fossem o valor real que representam. Veja a seguir um exemplo que passa o token do nome do nosso bucket para uma construção de uma AWS Lambda função:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Define a Lambda function
const myFunction = new lambda.Function(this, "myFunction", {
runtime: lambda.Runtime.NODEJS_20_X,
handler: "index.handler",
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
functionName: myBucketName + "Function", // Pass token for the S3 bucket name
environment: {
BUCKET_NAME: myBucketName, // Pass token for the S3 bucket name
}
});
}
}Quando sintetizamos nosso modelo, as funções intrínsecas Ref e as funções intrínsecas Fn::Join são usadas para especificar os valores, que serão conhecidos na implantação:
Resources:
myBucket5AF9C99B:
Type: AWS::S3::Bucket
# ...
myFunction884E1557:
Type: AWS::Lambda::Function
Properties:
# ...
Environment:
Variables:
BUCKET_NAME:
Ref: myBucket5AF9C99B
FunctionName:
Fn::Join:
- ""
- - Ref: myBucket5AF9C99B
- Function
# ...Como funciona a codificação de token
Tokens são objetos que implementam a interface IResolvable, que contém um único método resolve. Durante a síntese, AWS CDK ele chama esse método para produzir o valor final dos tokens em seu CloudFormation modelo.
nota
Você raramente trabalhará diretamente com a interface IResolvable. Provavelmente, você verá apenas versões codificadas por string dos tokens.
Tipos de codificação de token
Os tokens participam do processo de síntese para produzir valores arbitrários de qualquer tipo. Outras funções normalmente aceitam apenas argumentos de tipos básicos, como string ou number. Para usar tokens nesses casos, você pode codificá-los em um dos três tipos usando métodos estáticos na classe cdk.Token.
-
Token.asStringpara gerar uma codificação de string (ou chamar.toString()no objeto do token). -
Token.asListpara gerar uma codificação de lista. -
Token.asNumberpara gerar uma codificação numérica.
Eles pegam um valor arbitrário, que pode ser um IResolvable, e os codificam em um valor primitivo do tipo indicado.
Importante
Como qualquer um dos tipos anteriores pode ser potencialmente um token codificado, tenha cuidado ao analisar ou tentar ler seu conteúdo. Por exemplo, se você tentar analisar uma string para extrair um valor dela, e a string for um token codificado, sua análise falhará. Da mesma forma, se você tentar consultar o comprimento de uma matriz ou realizar operações matemáticas com um número, primeiro verifique se eles não são tokens codificados.
Como verificar se há tokens em sua aplicação
Para verificar se um valor tem um token não resolvido, chame o método Token.isUnresolved (Python: is_unresolved). Veja a seguir um exemplo que verifica se o valor do nome do nosso bucket do Amazon S3 é um token. Se não for um token, então validamos o tamanho do nome do bucket:
// ...
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (cdk.Token.isUnresolved(myBucketName)) {
console.log("Token identified.");
} else if (!cdk.Token.isUnresolved(myBucketName) && myBucketName.length > 10) {
throw new Error('Maximum length for name is 10 characters.');
};
// ...Quando executamos cdk synth, myBucketName é identificado como um token:
$cdk synth --quietToken identified.
nota
Você pode usar codificações de token para escapar do sistema de tipos. Por exemplo, você pode codificar em string um token que produz um valor numérico no momento da síntese. Se você usar essas funções, é sua responsabilidade garantir que seu modelo seja resolvido em um estado utilizável após a síntese.
Trabalhando com tokens codificados por string
Os tokens codificados por string são semelhantes aos seguintes:
${TOKEN[Bucket.Name.1234]}
Eles podem ser transmitidos como strings regulares e podem ser concatenados, conforme mostrado no exemplo a seguir.
const functionName = bucket.bucketName + 'Function';Você também pode usar interpolação de strings, se seu idioma for compatível, conforme mostrado no exemplo a seguir.
const functionName = `${bucket.bucketName}Function`;Evite manipular a string de outras formas. Por exemplo, pegar uma substring de uma string provavelmente quebrará o token da string.
Trabalhando com tokens codificados em lista
Os tokens codificados em lista são semelhantes aos seguintes:
["#{TOKEN[Stack.NotificationArns.1234]}"]
A única coisa segura a fazer com essas listas é passá-las diretamente para outros constructos. Os tokens no formato de lista de strings não podem ser concatenados, nem um elemento pode ser retirado do token. A única maneira segura de manipulá-los é usando funções intrínsecas AWS CloudFormation como Fn.Select.
Trabalhando com tokens codificados por números
Os tokens codificados por números são um conjunto de pequenos números negativos de ponto flutuante que se parecem com os seguintes.
-1.8881545897087626e+289Assim como acontece com os tokens da lista, você não pode modificar o valor do número, pois isso provavelmente quebrará o token numérico.
A seguir temos um exemplo de um constructo que contém um token codificado como um número:
import { Stack, Duration, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
const vpc = new ec2.Vpc(this, 'MyVpc', {
maxAzs: 3, // Maximum number of availability zones to use
});
// Define an RDS database cluster
const dbCluster = new rds.DatabaseCluster(this, 'MyRDSCluster', {
engine: rds.DatabaseClusterEngine.AURORA,
instanceProps: {
vpc,
},
});
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// Print the value for our token at synthesis
console.log("portToken: " + portToken);
}
}Quando executamos cdk synth, o valor de portToken é exibido como um token codificado por número:
$cdk synth --quietportToken: -1.8881545897087968e+289
Passar tokens codificados por números
Quando você passa tokens codificados em números para outros constructos, pode fazer sentido convertê-los em strings primeiro. Por exemplo, se você quiser usar o valor de uma string codificada por número como parte de uma string concatenada, convertê-la ajuda na legibilidade.
No exemplo a seguir, portToken é um token codificado em números que queremos passar para nossa função do Lambda como parte de connectionString:
import { Stack, Duration, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Example connection string with the port token as a number
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portToken}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}Se passarmos esse valor para connectionString, o valor de saída quando executamos cdk synth pode ser confuso devido à string codificada por números:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:-1.888154589708796e+289/mydatabase
Para converter um token codificado por número em uma string, use cdk.Tokenization.stringifyNumber(. No exemplo a seguir, convertemos o token codificado por número em uma string antes de definir nossa string de conexão:token)
import { Stack, Duration, Tokenization, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
const portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portAsString}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
// ...
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}Quando executamos o cdk synth, o valor da nossa string de conexão é representado em um formato mais limpo e claro:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:${Token[TOKEN.242]}/mydatabase
Valores lentos
Além de representar valores de tempo de implantação, como AWS CloudFormation parâmetros, os tokens também são comumente usados para representar valores preguiçosos de tempo de síntese. Esses são valores para os quais o valor final será determinado antes da conclusão da síntese, mas não no ponto em que o valor é construído. Use tokens para passar uma string literal ou um valor numérico para outro constructo, enquanto o valor real no momento da síntese pode depender de algum cálculo que ainda não foi feito.
Você pode criar tokens representando valores lentos de tempo de sintetizador usando métodos estáticos na Lazy classe, como Lazy.string e Lazy.number. Esses métodos aceitam um objeto cuja propriedade produce é uma função que aceita um argumento de contexto e retorna o valor final quando chamada.
O exemplo a seguir cria um grupo do Auto Scaling cuja capacidade é determinada após sua criação.
let actualValue: number;
new AutoScalingGroup(this, 'Group', {
desiredCapacity: Lazy.numberValue({
produce(context) {
return actualValue;
}
})
});
// At some later point
actualValue = 10;Conversão para JSON
Às vezes, você deseja produzir uma string JSON de dados arbitrários e talvez não saiba se os dados contêm tokens. Para codificar adequadamente qualquer estrutura de dados em JSON, independentemente de ela conter tokens, use o método stack.toJsonString, conforme mostrado no exemplo a seguir.
const stack = Stack.of(this);
const str = stack.toJsonString({
value: bucket.bucketName
});