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á.
# Trabalho com a biblioteca do AWS CDK
Importe e use a biblioteca do kit de desenvolvimento em nuvem da AWS (CDK da AWS) para definir sua infraestrutura de nuvem da AWS com uma [linguagem de programação com suporte](languages.md).
## Importação da biblioteca do AWS CDK
A [Biblioteca do AWS CDK](libraries.md) geralmente é chamada pelo nome do pacote de TypeScript de `aws-cdk-lib`. O nome real do pacote varia de acordo com a linguagem. Veja a seguir um exemplo de como instalar e importar a biblioteca CDK:
**Example**
| | |
| --- |--- |
| **Instalar o** | `npm install aws-cdk-lib` |
| **Importar** | `import * as cdk from 'aws-cdk-lib';` |
| | |
| --- |--- |
| **Instalar o** | `npm install aws-cdk-lib` |
| **Importar** | `const cdk = require('aws-cdk-lib');` |
| | |
| --- |--- |
| **Instalar o** | `python -m pip install aws-cdk-lib` |
| **Importar** | `import aws_cdk as cdk` |
| | |
| --- |--- |
| **Em `pom.xml`, adicione** | `Group software.amazon.awscdk; artifact aws-cdk-lib` |
| **Importar** | `import software.amazon.awscdk.App;` |
| | |
| --- |--- |
| **Instalar o** | `dotnet add package Amazon.CDK.Lib` |
| **Importar** | `using Amazon.CDK;` |
| | |
| --- |--- |
| **Instalar o** | `go get github.com/aws/aws-cdk-go/awscdk/v2` |
| **Importar** | import (
"github.com/aws/aws-cdk-go/awscdk/v2"
)
|
A classe de base `construct` e o código de suporte estão na biblioteca `constructs`. Os constructos experimentais, nos quais a API ainda está sendo refinada, são distribuídos como módulos separados.
## Uso de Referência de API do AWS CDK
Use a [Referência de API do AWS CDK](libraries.md#libraries-reference) ao desenvolver com o AWS CDK.
O material de referência de cada módulo é dividido nas seções a seguir.
+ *Visão geral*: material introdutório que você precisará conhecer para trabalhar com o serviço no AWS CDK, incluindo conceitos e exemplos.
+ *Constructos*: classes de biblioteca que representam um ou mais recursos AWS concretos. Esses são os recursos ou padrões “selecionados” (L2) (recursos L3) que fornecem uma interface de alto nível com padrões sensatos.
+ *Classes*: classes de não constructos que fornecem a funcionalidade usada por constructos no módulo.
+ *Estruturas*: estruturas de dados (pacotes de atributos) que definem a estrutura de valores compostos, como propriedades (o argumento `props` de constructos) e opções.
+ *Interfaces*: as interfaces, cujos nomes começam todos com “I”, definem a funcionalidade mínima absoluta para o constructo correspondente ou outra classe. O CDK usa interfaces de constructos para representar recursos AWS definidos fora da sua aplicação do AWS CDK e referenciados por métodos como `Bucket.fromBucketArn()`.
+ *Enums*: coleções de valores nomeados para uso na especificação de determinados parâmetros de constructos. O uso de um valor enumerado permite que o CDK verifique a validade desses valores durante a síntese.
+ *Recursos do CloudFormation*: esses constructos L1, cujos nomes começam com “Cfn”, representam exatamente os recursos definidos na especificação do CloudFormation. Eles são gerados automaticamente a partir dessa especificação em cada versão do CDK. Cada constructo L2 ou L3 encapsula um ou mais recursos do CloudFormation.
+ *Tipos de propriedades do CloudFormation*: o conjunto de valores nomeados que definem as propriedades de cada recurso do CloudFormation.
## Interfaces comparadas com classes de constructos
O AWS CDK usa interfaces de uma forma específica que pode não ser óbvia, mesmo se você estiver familiarizado com interfaces como um conceito de programação.
O AWS CDK oferece suporte ao uso de recursos definidos fora das aplicações do CDK usando métodos como `Bucket.fromBucketArn()`. Os recursos externos não podem ser modificados e podem não ter todas as funcionalidades disponíveis com os recursos definidos em sua aplicação CDK usando, por exemplo, a classe `Bucket`. As interfaces, então, representam a funcionalidade mínima disponível no CDK para um determinado tipo de recurso AWS, *incluindo recursos externos*.
Ao instanciar recursos em sua aplicação CDK, você deve sempre usar classes concretas, como `Bucket`. Ao especificar o tipo de argumento que você está aceitando em um de seus próprios constructos, use o tipo de interface, como `IBucket`, se estiver preparado para lidar com recursos externos (ou seja, não precisará alterá-los). Se você precisar de um constructo definido pelo CDK, especifique o tipo mais geral que você pode usar.
Algumas interfaces são versões mínimas de propriedades ou pacotes de opções associados a classes específicas, em vez de constructos. Essas interfaces podem ser úteis na criação de subclasses para aceitar argumentos que você passará para sua classe principal. Se você precisar de uma ou mais propriedades adicionais, convém implementar ou derivar dessa interface ou de um tipo mais específico.
**nota**
Algumas linguagens de programação com suporte no AWS CDK não têm um atributo de interface. Nessas linguagens, as interfaces são apenas classes comuns. É possível identificá-las por seus nomes, que seguem o padrão de um “I” inicial seguido pelo nome de algum outro constructo (por exemplo, `IBucket`). As mesmas regras se aplicam.
## Gerenciamento de dependências
As dependências da sua aplicação ou biblioteca do AWS CDK são gerenciadas usando ferramentas de gerenciamento de pacotes. Essas ferramentas são comumente usadas com as linguagens de programação.
Normalmente, o AWS CDK oferece suporte à ferramenta de gerenciamento de pacotes padrão ou oficial da linguagem, se houver uma. Caso contrário, o AWS CDK terá suporte para a linguagem mais popular, ou a de suporte mais amplo. Você também poderá usar outras ferramentas, especialmente se elas funcionarem com as ferramentas compatíveis. No entanto, o suporte oficial para outras ferramentas é limitado.
O AWS CDK oferece suporte aos gerenciadores de pacotes a seguir:
| Linguagem | Ferramenta de gerenciamento de pacotes compatível |
| --- | --- |
| TypeScript/JavaScript | NPM (Node Package Manager) ou Yarn |
| Python | PIP (instalador de pacotes para Python) |
| Java | Maven |
| C\# | NuGet |
| Go | Módulos Go |
Quando você cria um novo projeto usando o comando `cdk init` da CLI do AWS CDK, as dependências das bibliotecas principais e constructos estáveis do CDK são especificadas automaticamente.
Para obter mais informações sobre o gerenciamento de dependências das linguagens de programação compatível, consulte o seguinte:
+ [Gerenciamento de dependências em TypeScript](work-with-cdk-typescript.md#work-with-cdk-typescript-dependencies).
+ [Gerenciamento de dependências em JavaScript](work-with-cdk-javascript.md#work-with-cdk-javascript-dependencies).
+ [Gerenciamento de dependências em Python](work-with-cdk-python.md#work-with-cdk-python-dependencies).
+ [Gerenciamento de dependências em Java](work-with-cdk-java.md#work-with-cdk-java-dependencies).
+ [Gerenciamento de dependências em C\#](work-with-cdk-csharp.md#work-with-cdk-csharp-dependencies).
+ [Gerenciamento de dependências em Go](work-with-cdk-go.md#work-with-cdk-go-dependencies).
## Comparação do AWS CDK em TypeScript com outras linguagens
O TypeScript foi a primeira linguagem com suporte para o desenvolvimento de aplicações do AWS CDK. Portanto, uma quantidade substancial de exemplos de código CDK é escrita em TypeScript. Se você estiver desenvolvendo em outra linguagem, pode ser útil comparar como o código do AWS CDK é implementado no TypeScript em comparação com a linguagem de sua escolha. Isso pode ajudá-lo a usar os exemplos em toda a documentação.
## Importação de um módulo
**Example**
O TypeScript suporta a importação de um namespace inteiro ou de objetos individuais de um namespace. Cada namespace inclui constructos e outras classes para uso com um determinado serviço AWS.
```
// Import main CDK library as cdk
import * as cdk from 'aws-cdk-lib'; // ES6 import preferred in TS
const cdk = require('aws-cdk-lib'); // Node.js require() preferred in JS
// Import specific core CDK classes
import { Stack, App } from 'aws-cdk-lib';
const { Stack, App } = require('aws-cdk-lib');
// Import AWS S3 namespace as s3 into current namespace
import { aws_s3 as s3 } from 'aws-cdk-lib'; // TypeScript
const s3 = require('aws-cdk-lib/aws-s3'); // JavaScript
// Having imported cdk already as above, this is also valid
const s3 = cdk.aws_s3;
// Now use s3 to access the S3 types
const bucket = s3.Bucket(...);
// Selective import of s3.Bucket
import { Bucket } from 'aws-cdk-lib/aws-s3'; // TypeScript
const { Bucket } = require('aws-cdk-lib/aws-s3'); // JavaScript
// Now use Bucket to instantiate an S3 bucket
const bucket = Bucket(...);
```
Assim como o TypeScript, o Python suporta importações de módulos com namespace e importações seletivas. Os namespaces em Python se parecem com **aws\_cdk.** *xxx*, em que *xxx* representa um nome de serviço da AWS, como **s3** para o Amazon S3. (Amazon S3 é usado nesses exemplos).
```
# Import main CDK library as cdk
import aws_cdk as cdk
# Selective import of specific core classes
from aws_cdk import Stack, App
# Import entire module as s3 into current namespace
import aws_cdk.aws_s3 as s3
# s3 can now be used to access classes it contains
bucket = s3.Bucket(...)
# Selective import of s3.Bucket into current namespace
from aws_cdk.s3 import Bucket
# Bucket can now be used to instantiate a bucket
bucket = Bucket(...)
```
As importações do Java funcionam de forma diferente das do TypeScript. Cada instrução de importação importa um único nome de classe de um determinado pacote ou todas as classes definidas nesse pacote (usando `\*`). As classes podem ser acessadas usando o nome da classe por si só, se tiver sido importada, ou o nome da classe *qualificada*, incluindo seu pacote.
As bibliotecas têm o mesmo de `software.amazon.awscdk.services.xxx` para a Biblioteca de Constructos da AWS (a biblioteca principal é `software.amazon.awscdk`). O ID do grupo Maven para pacotes do AWS CDK é `software.amazon.awscdk`.
```
// Make certain core classes available
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.App;
// Make all Amazon S3 construct library classes available
import software.amazon.awscdk.services.s3.*;
// Make only Bucket and EventType classes available
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.s3.EventType;
// An imported class may now be accessed using the simple class name (assuming that name
// does not conflict with another class)
Bucket bucket = Bucket.Builder.create(...).build();
// We can always use the qualified name of a class (including its package) even without an
// import directive
software.amazon.awscdk.services.s3.Bucket bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
// Java 10 or later can use var keyword to avoid typing the type twice
var bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
```
Em C\#, você importa tipos com a diretiva `using`. Há dois estilos. Um fornece acesso a todos os tipos no namespace especificado usando seus nomes simples. Com o outro, você pode se referir ao próprio namespace usando um alias.
Os pacotes são nomeados da mesma forma que `Amazon.CDK.AWS.xxx` para os pacotes da Biblioteca de Constructos da AWS. (O módulo principal é `Amazon.CDK`.)
```
// Make CDK base classes available under cdk
using cdk = Amazon.CDK;
// Make all Amazon S3 construct library classes available
using Amazon.CDK.AWS.S3;
// Now we can access any S3 type using its name
var bucket = new Bucket(...);
// Import the S3 namespace under an alias
using s3 = Amazon.CDK.AWS.S3;
// Now we can access an S3 type through the namespace alias
var bucket = new s3.Bucket(...);
// We can always use the qualified name of a type (including its namespace) even without a
// using directive
var bucket = new Amazon.CDK.AWS.S3.Bucket(...);
```
Cada módulo da Biblioteca de Constructos da AWS é fornecido como um pacote Go.
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
"github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
// now instantiate a bucket
bucket := awss3.NewBucket(...)
// use aliases for brevity/clarity
import (
cdk "github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
bucket := s3.NewBucket(...)
```
## Criação da instância de uma estrutura
As classes de constructos do AWS CDK têm o mesmo nome em todas as linguagens com suporte. A maioria das linguagens usa a palavra-chave `new` para instanciar uma classe (Python e Go não). Além disso, na maioria das linguagens, a palavra-chave `this` se refere à instância atual. (Python usa `self` por convenção.) É necessário passar uma referência à instância atual como parâmetro `scope` para cada constructo criado.
O terceiro argumento de um constructo do AWS CDK é `props`, um objeto contendo os atributos necessários para compilar o constructo. Esse argumento pode ser opcional, mas quando necessário, as linguagens suportadas o tratam de forma idiomática. Os nomes dos atributos também são adaptados aos padrões de nomenclatura padrão da linguagem.
**Example**
```
// Instantiate default Bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket');
// Instantiate Bucket with bucketName and versioned properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
bucketName: 'amzn-s3-demo-bucket',
versioned: true,
});
// Instantiate Bucket with websiteRedirect, which has its own sub-properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
websiteRedirect: {host: 'aws.amazon.com'}});
```
O Python não usa uma palavra-chave `new` ao instanciar uma classe. O argumento de propriedades é representado usando argumentos de palavra-chave e os argumentos são nomeados usando `snake_case`.
Se um valor de props for em si um pacote de atributos, será representado por uma classe com o nome da propriedade, que aceita argumentos de palavra-chave para as subpropriedades.
Em Python, a instância atual é passada para os métodos como o primeiro argumento, que é nomeado `self` por convenção.
```
# Instantiate default Bucket
bucket = s3.Bucket(self, "amzn-s3-demo-bucket")
# Instantiate Bucket with bucket_name and versioned properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket", versioned=true)
# Instantiate Bucket with website_redirect, which has its own sub-properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", website_redirect=s3.WebsiteRedirect(
host_name="aws.amazon.com"))
```
Em Java, o argumento props é representado por uma classe chamada `XxxxProps` (por exemplo, `BucketProps` para as props de constructos `Bucket`). Você constrói o argumento props usando um padrão de construtor.
Cada classe `XxxxProps` tem um construtor. Também existe um construtor conveniente para cada constructo que constrói os props e o constructo em uma única etapa, conforme mostrado no exemplo a seguir.
Props são nomeados da mesma forma que no TypeScript, usando `camelCase`.
```
// Instantiate default Bucket
Bucket bucket = Bucket(self, "amzn-s3-demo-bucket");
// Instantiate Bucket with bucketName and versioned properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
.bucketName("amzn-s3-demo-bucket").versioned(true)
.build();
# Instantiate Bucket with websiteRedirect, which has its own sub-properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
.websiteRedirect(new websiteRedirect.Builder()
.hostName("aws.amazon.com").build())
.build();
```
Em C\#, os props são especificados usando um inicializador de objeto para uma classe chamada `XxxxProps` (por exemplo, `BucketProps` para props do constructo `Bucket`).
Os props são nomeados de forma semelhante ao TypeScript, exceto usando `PascalCase`.
É conveniente usar a palavra-chave `var` ao instanciar um constructo, para que você não precise digitar o nome da classe duas vezes. No entanto, seu guia de estilo de código local pode variar.
```
// Instantiate default Bucket
var bucket = Bucket(self, "amzn-s3-demo-bucket");
// Instantiate Bucket with BucketName and Versioned properties
var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
BucketName = "amzn-s3-demo-bucket",
Versioned = true});
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
WebsiteRedirect = new WebsiteRedirect {
HostName = "aws.amazon.com"
}});
```
Para criar um constructo em Go, chame a função `NewXxxxxx` em que `Xxxxxxx` é o nome do constructo. As propriedades dos constructos são definidas como uma estrutura.
Em Go, todos os parâmetros de constructos são ponteiros, incluindo valores como números, booleanos e cadeias de caracteres. Use as funções de conveniência, como `jsii.String` para criar esses ponteiros.
```
// Instantiate default Bucket
bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), nil)
// Instantiate Bucket with BucketName and Versioned properties
bucket1 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
BucketName: jsii.String("amzn-s3-demo-bucket"),
Versioned: jsii.Bool(true),
})
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
bucket2 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
WebsiteRedirect: &awss3.RedirectTarget{
HostName: jsii.String("aws.amazon.com"),
}})
```
## Acesso a membros
É comum se referir a atributos ou propriedades de constructos e outras classes do AWS CDK e usar esses valores como, por exemplo, entradas para criar outros constructos. As diferenças de nomenclatura descritas anteriormente para os métodos também se aplicam aqui. Além disso, em Java, não é possível acessar os membros diretamente. Em vez disso, um método getter é fornecido.
**Example**
Os nomes são `camelCase`.
```
bucket.bucketArn
```
Os nomes são `snake_case`.
```
bucket.bucket_arn
```
Um método getter é fornecido para cada propriedade; esses nomes são `camelCase`.
```
bucket.getBucketArn()
```
Os nomes são `PascalCase`.
```
bucket.BucketArn
```
Os nomes são `PascalCase`.
```
bucket.BucketArn
```
## Constantes Enum
As constantes Enum têm como escopo uma classe e têm nomes em maiúsculas com sublinhados em todas as linguagens (às vezes chamadas de `SCREAMING_SNAKE_CASE`). Como os nomes das classes também usam a mesma letra maiúscula em todas as linguagens com suporte, exceto Go, os nomes de enumeração qualificados também são os mesmos nessas linguagens.
```
s3.BucketEncryption.KMS_MANAGED
```
Em Go, as constantes enum são atributos do namespace do módulo e são escritas da seguinte forma.
```
awss3.BucketEncryption_KMS_MANAGED
```
## Interfaces de objetos
O AWS CDK usa interfaces de objetos de TypeScript para indicar que uma classe implementa um conjunto esperado de métodos e propriedades. É possível reconhecer uma interface de objeto porque seu nome começa com `I`. Uma classe concreta indica as interfaces que ela implementa usando a palavra-chave `implements`.
**Example**
O JavaScript não tem um atributo de interface. É possível ignorar a palavra-chave `implements` e os nomes das classes que a seguem.
```
import { IAspect, IConstruct } from 'aws-cdk-lib';
class MyAspect implements IAspect {
public visit(node: IConstruct) {
console.log('Visited', node.node.path);
}
}
```
O Python não tem um atributo de interface. Entretanto, para o AWS CDK, é possível indicar a implementação da interface decorando sua classe com `@jsii.implements(interface)`.
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
```
import software.amazon.awscdk.IAspect;
import software.amazon.awscdk.IConstruct;
public class MyAspect implements IAspect {
public void visit(IConstruct node) {
System.out.format("Visited %s", node.getNode().getPath());
}
}
```
```
using Amazon.CDK;
public class MyAspect : IAspect
{
public void Visit(IConstruct node)
{
System.Console.WriteLine($"Visited ${node.Node.Path}");
}
}
```
As estruturas Go não precisam declarar explicitamente quais interfaces elas implementam. O compilador Go determina a implementação com base nos métodos e propriedades disponíveis na estrutura. Por exemplo, no código a seguir, `MyAspect` implementa a interface `IAspect` porque ela fornece um método `Visit` que usa um constructo.
```
type MyAspect struct {
}
func (a MyAspect) Visit(node constructs.IConstruct) {
fmt.Println("Visited", *node.Node().Path())
}
```