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\$1 | 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\$1](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\$1cdk.** *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\$1, 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\$1, 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())
}
```
# Trabalho com o AWS CDK em TypeScript
O TypeScript consiste em uma linguagem de cliente com suporte total para o kit de desenvolvimento em nuvem da AWS (CDK da AWS), e considerada estável. O trabalho com o AWS CDK em TypeScript usa ferramentas familiares, incluindo o compilador TypeScript (`tsc`) da Microsoft, o [Node.js](https://nodejs.org/) e o Node Package Manager (`npm`). Você também pode usar o [Yarn](https://yarnpkg.com/) se preferir, embora os exemplos neste Guia usem o NPM. Os módulos que compõem a Biblioteca de Constructos da AWS são distribuídos por meio do repositório NPM, [npmjs.org](https://www.npmjs.com/).
É possível usar qualquer editor ou IDE. Muitos desenvolvedores do AWS CDK usam o [Visual Studio Code](https://code.visualstudio.com/) (ou seu equivalente de código aberto [VSCodium](https://vscodium.com/)), que tem excelente suporte para TypeScript.
## Conceitos básicos de TypeScript
Para trabalhar com o AWS CDK, é necessário ter uma conta e credenciais da AWS e ter instalado o Node.js e o Kit de Ferramentas CDK da AWS. Consulte [Conceitos básicos do AWS CDK](getting-started.md).
Você também precisa do próprio TypeScript (versão 3.8 ou posterior). Se ainda não tiver, poderá instalá-lo usando `npm`.
```
$ npm install -g typescript
```
**nota**
Se você receber um erro de permissão e tiver acesso de administrador em seu sistema, tente `sudo npm install -g typescript`.
Mantenha o TypeScript atualizado com `npm update -g typescript` normal.
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
## Criação de um projeto
Você cria um novo projeto do AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `typescript`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language typescript
```
A criação de um projeto também instala o módulo [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) e suas dependências.
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador do TypeScript; por exemplo, não deve começar com um número nem conter espaços.
## Uso de `tsc` e `cdk` local
Na maioria das vezes, este guia pressupõe que você instale o TypeScript e o Kit de Ferramentas CDK globalmente (`npm install -g typescript aws-cdk`), e os exemplos de comandos fornecidos (como `cdk synth`) seguem essa suposição. Essa abordagem facilita a atualização dos dois componentes e, como ambos adotam uma abordagem rígida de compatibilidade com versões anteriores, geralmente há pouco risco em sempre usar as versões mais recentes.
Algumas equipes preferem especificar todas as dependências em cada projeto, incluindo ferramentas como o compilador TypeScript e o Kit de Ferramentas CDK. Essa prática permite que você fixe esses componentes em versões específicas e garanta que todos os desenvolvedores da sua equipe (e do seu ambiente de CI/CD) usem exatamente essas versões. Isso elimina uma possível fonte de mudança, ajudando a tornar as compilações e implantações mais consistentes e reproduzíveis.
O CDK inclui dependências tanto para o TypeScript quanto para o Kit de Ferramentas CDK no `package.json` do modelo de projeto do TypeScript. Portanto, se você quiser usar essa abordagem, não precisará fazer nenhuma alteração em seu projeto. Tudo o que você precisa fazer é usar comandos ligeiramente diferentes para compilar sua aplicação e emitir comandos `cdk`.
| Operação | Usar ferramentas globais | Usar ferramentas locais |
| --- | --- | --- |
| **Inicializar projeto** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` |
| **Compilar** | `tsc` | `npm run build` |
| **Execute o comando do Kit de Ferramentas CDK** | `cdk …` | `npm run cdk …` ou `npx aws-cdk …` |
`npx aws-cdk` executa a versão do Kit de Ferramentas CDK instalada localmente no projeto atual, se houver, retornando à instalação global, se houver. Se não existir uma instalação global, `npx` baixa uma cópia temporária do Kit de Ferramentas CDK e a executa. É possível especificar uma versão arbitrária do Kit de Ferramentas CDK usando a sintaxe `@`: `npx aws-cdk@2.0 --version` imprime `2.0.0`.
**dica**
Configure um alias para que você possa usar o comando `cdk` com uma instalação local do Kit de Ferramentas CDK.
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## Gerenciamento de módulos da Biblioteca de Constructos da AWS
Use o Node Package Manager (`npm`) para instalar e atualizar os módulos da Biblioteca de Constructos da AWS para uso por suas aplicações, bem como por outros pacotes necessários. (É possível usar `yarn` em vez de `npm`, se preferir.) `npm` também instala as dependências desses módulos automaticamente.
A maioria dos constructos da AWS está no pacote principal do CDK, chamado `aws-cdk-lib`, que é uma dependência padrão em novos projetos criados por `cdk init`. Os módulos “experimentais” da Biblioteca de Constructos da AWS, nos quais constructos de nível superior ainda estão em desenvolvimento, são nomeados como `@aws-cdk/-alpha`. O nome do serviço tem um prefixo *aws-*. Se você não tiver certeza do nome de um módulo, [procure-o no NPM](https://www.npmjs.com/search?q=%40aws-cdk).
**nota**
A [Referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) também mostra os nomes dos pacotes.
Por exemplo, o comando abaixo instala o módulo experimental para AWS CodeStar.
```
$ npm install @aws-cdk/aws-codestar-alpha
```
O suporte da Biblioteca de Constructos de alguns serviços está em mais de um namespace. Por exemplo, além de `aws-route53`, há três namespaces adicionais do Amazon Route 53, `aws-route53-targets`, `aws-route53-patterns` e `aws-route53resolver`.
As dependências do seu projeto são mantidas em `package.json`. É possível editar esse arquivo para bloquear algumas ou todas as suas dependências em uma versão específica ou para permitir que elas sejam atualizadas para versões mais recentes sob determinados critérios. Para atualizar as dependências do NPM do seu projeto para a versão mais recente permitida de acordo com as regras que você especificou em `package.json`:
```
$ npm update
```
No TypeScript, você importa módulos para o seu código com o mesmo nome usado para instalá-los usando o NPM. Recomendamos as práticas a seguir ao importar classes do AWS CDK e módulos da Biblioteca de Constructos da AWS em suas aplicações. Seguir essas diretrizes ajudará a tornar seu código consistente com outras aplicações do AWS CDK, além de ser mais fácil de entender.
+ Use diretivas `import` no estilo ES6, não `require()`.
+ Geralmente, importe classes individuais de `aws-cdk-lib`.
```
import { App, Stack } from 'aws-cdk-lib';
```
+ Se precisar de muitas classes de `aws-cdk-lib`, você pode usar um alias de namespace de `cdk`, em vez de importar as classes individuais. Evite fazer as duas coisas.
```
import * as cdk from 'aws-cdk-lib';
```
+ Geralmente, importe constructos de serviços AWS usando aliases curtos de namespace.
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```
## Gerenciamento de dependências em TypeScript
Em projetos do CDK em TypeScript, as dependências são especificadas no arquivo `package.json`, no diretório principal do projeto. Os módulos principais do AWS CDK estão em um único pacote `NPM` chamado `aws-cdk-lib`.
Quando você instala um pacote usando `npm install`, o NPM grava o pacote em `package.json` para você.
Se preferir, você pode usar o Yarn no lugar do NPM. No entanto, o CDK não oferece suporte ao modo plug-and-play do Yarn, que é o modo padrão no Yarn 2. Adicione o seguinte ao arquivo `.yarnrc.yml` do seu projeto para desativar esse atributo.
```
nodeLinker: node-modules
```
### Aplicações do CDK
Veja a seguir um exemplo de arquivo `package.json` gerado pelo comando `cdk init --language typescript`:
```
{
"name": "my-package",
"version": "0.1.0",
"bin": {
"my-package": "bin/my-package.js"
},
"scripts": {
"build": "tsc",
"watch": "tsc -w",
"test": "jest",
"cdk": "cdk"
},
"devDependencies": {
"@types/jest": "^26.0.10",
"@types/node": "10.17.27",
"jest": "^26.4.2",
"ts-jest": "^26.2.0",
"aws-cdk": "2.16.0",
"ts-node": "^9.0.0",
"typescript": "~3.9.7"
},
"dependencies": {
"aws-cdk-lib": "2.16.0",
"constructs": "^10.0.0",
"source-map-support": "^0.5.16"
}
}
```
Para aplicações CDK implantáveis, `aws-cdk-lib` deve ser especificado na seção `dependencies` de `package.json`. É possível usar um especificador de número de versão com acento circunflexo (^) para indicar que aceitará versões posteriores à especificada, desde que estejam na mesma versão principal.
Para constructos experimentais, especifique as versões exatas dos módulos da Biblioteca de Constructos alfa, que têm APIs que podem mudar. Não use ^ ou \$1, pois versões posteriores desses módulos podem trazer alterações na API que podem prejudicar sua aplicação.
Especifique as versões das bibliotecas e ferramentas necessárias para testar sua aplicação (por exemplo, a estrutura de teste `jest`) na seção `devDependencies` de `package.json`. Opcionalmente, use ^ para especificar que versões compatíveis posteriores sejam aceitáveis.
### Bibliotecas de constructos de terceiros
Se você estiver desenvolvendo uma biblioteca de constructos, especifique suas dependências usando uma combinação das seções `peerDependencies` e `devDependencies`, conforme mostrado no arquivo `package.json` de exemplo a seguir.
```
{
"name": "my-package",
"version": "0.0.1",
"peerDependencies": {
"aws-cdk-lib": "^2.14.0",
"@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
"constructs": "^10.0.0"
},
"devDependencies": {
"aws-cdk-lib": "2.14.0",
"@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
"constructs": "10.0.0",
"jsii": "^1.50.0",
"aws-cdk": "^2.14.0"
}
}
```
Em `peerDependencies`, use um acento circunflexo (^) para especificar a versão mais baixa de `aws-cdk-lib` com a qual sua biblioteca trabalha. Isso maximiza a compatibilidade da sua biblioteca com uma variedade de versões do CDK. Especifique as versões exatas dos módulos de Biblioteca de Constructos alfa, que têm APIs que podem mudar. O uso de `peerDependencies` garante que haja apenas uma cópia de todas as bibliotecas CDK na árvore `node_modules`.
Em `devDependencies`, especifique as ferramentas e bibliotecas que você precisa para testar, opcionalmente com ^ para indicar que versões compatíveis posteriores são aceitáveis. Especifique exatamente (sem ^ ou \$1) as versões mais baixas de `aws-cdk-lib` e outros pacotes do CDK com os quais você anuncia a compatibilidade da sua biblioteca. Essa prática garante que seus testes sejam executados nessas versões. Dessa forma, se você usar inadvertidamente um atributo encontrado apenas em versões mais recentes, seus testes poderão detectá-lo.
**Atenção**
`peerDependencies` são instalados automaticamente somente pelo NPM 7 e versões posteriores. Se você estiver usando o NPM 6 ou versão anterior, ou se estiver usando o Yarn, deverá incluir as dependências de suas dependências no `devDependencies`. Caso contrário, elas não serão instaladas e você receberá um aviso sobre dependências de pares não resolvidas.
### Instalação e atualização de dependências
Use o comando a seguir para instalar as dependências do seu projeto.
**Example**
```
# Install the latest version of everything that matches the ranges in 'package.json'
npm install
# Install the same exact dependency versions as recorded in 'package-lock.json'
npm ci
```
```
# Install the latest version of everything that matches the ranges in 'package.json'
$ yarn upgrade
# Install the same exact dependency versions as recorded in 'yarn.lock'
$ yarn install --frozen-lockfile
```
Para atualizar os módulos instalados, os comandos `npm install` e `yarn upgrade` anteriores podem ser usados. Qualquer um dos comandos atualiza os pacotes em `node_modules` para as versões mais recentes que atendem às regras em `package.json`. No entanto, não atualizam `package.json` por conta própria, o que talvez você queira fazer para definir uma nova versão mínima. Se você hospedar seu pacote no GitHub, poderá configurar as [atualizações de versão do Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) para atualizar `package.json` automaticamente. Como alternativa, use [npm-check-updates](https://www.npmjs.com/package/npm-check-updates).
**Importante**
Por padrão, quando você instala ou atualiza dependências, o NPM e o Yarn escolhem a versão mais recente de cada pacote que atenda aos requisitos especificados em `package.json`. Sempre existe o risco de que essas versões sejam quebradas (acidental ou intencionalmente). Teste minuciosamente depois de atualizar as dependências do seu projeto.
## Expressões idiomáticas do AWS em TypeScript
### Props
*Todas as classes da Biblioteca de Constructos da AWS são instanciadas usando três argumentos: o *escopo* no qual o constructo está sendo definido (seu pai na árvore de constructos), um *id* e adereços.* O argumento *props* consiste em um pacote de pares de chave/valor que o constructo usa para configurar os recursos AWS que ele cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
No TypeScript, a forma de `props` é definida usando uma interface que informa os argumentos obrigatórios e opcionais e seus tipos. Essa interface é definida para cada tipo de argumento `props`, geralmente específico para um único constructo ou método. Por exemplo, o constructo [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) (no módulo `aws-cdk-lib/aws-s3`) especifica um argumento `props` em conformidade com a interface [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html).
Se uma propriedade for em si um objeto, por exemplo, a propriedade [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect) de `BucketProps`, esse objeto terá sua própria interface à qual sua forma deverá estar em conformidade, nesse caso, [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html).
Se estiver subclassificando uma classe da Biblioteca de Constructos da AWS (ou substituindo um método que usa um argumento semelhante a adereços), você pode herdar da interface existente para criar uma nova que especifique quaisquer novos adereços que seu código exija. Ao chamar a classe principal ou o método base, você normalmente pode passar todo o argumento props recebido, pois quaisquer atributos fornecidos no objeto, mas não especificados na interface, serão ignorados.
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Passar o valor que você recebe para a cadeia de herança pode causar um comportamento inesperado. É mais seguro passar uma cópia rasa dos adereços que você recebeu com sua propriedade removida ou configurada para `undefined`. Por exemplo:
```
super(scope, name, {...props, encryptionKeys: undefined});
```
Como alternativa, nomeie suas propriedades para que fique claro que elas pertencem ao seu constructo. Dessa forma, é improvável que colidam com propriedades em versões futuras do AWS CDK. Se houver muitas delas, use um único objeto com nome apropriado para mantê-las.
### Valores ausentes
Valores ausentes em um objeto (como props) têm o valor `undefined` em TypeScript. A versão 3.7 da linguagem introduziu operadores que simplificam o trabalho com esses valores, facilitando a especificação de padrões e o encadeamento em “curto-circuito” quando um valor indefinido é atingido. Para obter mais informações sobre esses atributos, consulte as [Notas de versão do TypeScript 3.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), especificamente os dois primeiros recursos, encadeamento opcional e coalescência nula.
## Compilação e execução de aplicações do CDK
Normalmente, é necessário estar no diretório raiz do projeto ao criar e executar sua aplicação.
O Node.js não pode executar o TypeScript diretamente; em vez disso, sua aplicação é convertido em JavaScript usando o compilador TypeScript, `tsc`. Em seguida, o código JavaScript resultante é executado.
O AWS CDK faz isso automaticamente sempre que precisa executar sua aplicação. No entanto, pode ser útil compilar manualmente para verificar erros e executar testes. Para compilar sua aplicação TypeScript manualmente, emita `npm run build`. Você também pode emitir `npm run watch` para entrar no modo de observação, no qual o compilador TypeScript reconstrói automaticamente sua aplicação sempre que você salva as alterações em um arquivo de origem.
# Trabalhando com o AWS CDK em JavaScript
JavaScript é uma linguagem de cliente totalmente compatível com o AWS CDK e é considerada estável. Trabalhar com o AWS Cloud Development Kit (AWS CDK) JavaScript usa ferramentas conhecidas, incluindo o [Node.js](https://nodejs.org/) e o Node Package Manager (`npm`). Você também pode usar o [Yarn](https://yarnpkg.com/) se preferir, embora os exemplos neste Guia usem o NPM. [Os módulos que compõem a AWS Construct Library são distribuídos por meio do repositório NPM, npmjs.org.](https://www.npmjs.com/)
É possível usar qualquer editor ou IDE. Muitos desenvolvedores de AWS CDK usam o [Visual Studio Code](https://code.visualstudio.com/) (ou seu equivalente de código aberto [VSCodium](https://vscodium.com/)), que tem um bom suporte para o. JavaScript
## Comece com JavaScript
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte [Introdução ao AWS CDK.](getting-started.md)
JavaScript AWS Os aplicativos CDK não exigem pré-requisitos adicionais além desses.
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
## Criação de um projeto
Você cria um novo projeto AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `javascript`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language javascript
```
A criação de um projeto também instala o módulo [aws-cdk-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) e suas dependências.
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, caso contrário, o nome deve seguir a forma de um JavaScript identificador; por exemplo, ele não deve começar com um número ou conter espaços.
## Uso de `cdk` localmente
Na maioria das vezes, este guia pressupõe que você instale o Kit de Ferramentas CDK globalmente (`npm install -g aws-cdk`), e os exemplos de comandos fornecidos (como `cdk synth`) seguem essa suposição. Essa abordagem facilita a atualização do Kit de Ferramentas CDK e, como o CDK adota uma abordagem estrita em relação à compatibilidade com versões anteriores, geralmente há pouco risco em sempre usar a versão mais recente.
Algumas equipes preferem especificar todas as dependências em cada projeto, incluindo ferramentas como o Kit de Ferramentas CDK. Essa prática permite que você fixe esses componentes em versões específicas e garanta que todos os desenvolvedores da sua equipe (e do seu CI/CD ambiente) usem exatamente essas versões. Isso elimina uma possível fonte de mudança, ajudando a tornar as compilações e implantações mais consistentes e reproduzíveis.
O CDK inclui uma dependência para o CDK Toolkit no modelo do JavaScript projeto. Portanto`package.json`, se você quiser usar essa abordagem, não precisará fazer nenhuma alteração em seu projeto. Tudo o que você precisa fazer é usar comandos ligeiramente diferentes para compilar sua aplicação e emitir comandos `cdk`.
| Operação | Usar ferramentas globais | Usar ferramentas locais |
| --- | --- | --- |
| **Inicializar projeto** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` |
| **Execute o comando CDK Toolkit** | `cdk …` | `npm run cdk …` ou `npx aws-cdk …` |
`npx aws-cdk` executa a versão do CDK Toolkit instalada localmente no projeto atual, se houver, retornando à instalação global, se houver. Se não existir uma instalação global, `npx` baixa uma cópia temporária do CDK Toolkit e a executa. Você pode especificar uma versão arbitrária do CDK Toolkit usando a sintaxe `@`: `npx aws-cdk@1.120 --version` imprime `1.120.0`.
**dica**
Configure um alias para que você possa usar o comando `cdk` com uma instalação local do CDK Toolkit.
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## Gerenciando módulos da AWS Construct Libr
Use o Node Package Manager (`npm`) para instalar e atualizar os módulos da AWS Construct Library para uso por seus aplicativos, bem como por outros pacotes necessários. (É possível usar `yarn` em vez de `npm`, se preferir.) `npm` também instala as dependências desses módulos automaticamente.
A maioria das construções de AWS CDK está no pacote CDK principal, chamado`aws-cdk-lib`, que é uma dependência padrão em novos projetos criados por. `cdk init` Os módulos “experimentais” da AWS Construct Library, nos quais construções de nível superior ainda estão em desenvolvimento, são nomeados como. `aws-cdk-lib/-alpha` O nome do serviço tem um prefixo *aws-*. Se você não tiver certeza do nome de um módulo, [procure-o no NPM](https://www.npmjs.com/search?q=%40aws-cdk).
**nota**
A [Referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) também mostra os nomes dos pacotes.
Por exemplo, o comando abaixo instala o módulo experimental para AWS CodeStar.
```
npm install @aws-cdk/aws-codestar-alpha
```
O suporte da Biblioteca de Constructos de alguns serviços está em mais de um namespace. Por exemplo, além de `aws-route53`, há três namespaces adicionais do Amazon Route 53, `aws-route53-targets`, `aws-route53-patterns` e `aws-route53resolver`.
As dependências do seu projeto são mantidas em `package.json`. É possível editar esse arquivo para bloquear algumas ou todas as suas dependências em uma versão específica ou para permitir que elas sejam atualizadas para versões mais recentes sob determinados critérios. Para atualizar as dependências do NPM do seu projeto para a versão mais recente permitida de acordo com as regras que você especificou em `package.json`:
```
npm update
```
Em JavaScript, você importa módulos para o seu código com o mesmo nome usado para instalá-los usando o NPM. Recomendamos as seguintes práticas ao importar classes AWS CDK e módulos da AWS Construct Library em seus aplicativos. Seguir essas diretrizes ajudará a tornar seu código consistente com outros aplicativos AWS CDK, além de ser mais fácil de entender.
+ Use`require()`, não `import` diretivas ES6 de estilo. As versões mais antigas do Node.js não oferecem suporte a ES6 importações, portanto, o uso da sintaxe mais antiga é mais amplamente compatível. (Se você realmente quiser usar ES6 importações, use o [esm](https://www.npmjs.com/package/esm) para garantir que seu projeto seja compatível com todas as versões suportadas do Node.js.)
+ Geralmente, importe classes individuais de `aws-cdk-lib`.
```
const { App, Stack } = require('aws-cdk-lib');
```
+ Se precisar de muitas classes de `aws-cdk-lib`, você pode usar um alias de namespace de `cdk`, em vez de importar as classes individuais. Evite fazer as duas coisas.
```
const cdk = require('aws-cdk-lib');
```
+ Geralmente, importe Bibliotecas do AWS Construct usando aliases curtos de namespace.
```
const { s3 } = require('aws-cdk-lib/aws-s3');
```
## Gerenciando dependências em JavaScript
Em projetos JavaScript CDK, as dependências são especificadas no `package.json` arquivo no diretório principal do projeto. Os módulos AWS CDK principais estão em um único `NPM` pacote chamado`aws-cdk-lib`.
Quando você instala um pacote usando `npm install`, o NPM grava o pacote em `package.json` para você.
Se preferir, você pode usar o Yarn no lugar do NPM. No entanto, o CDK não suporta o modo Yarn, que é o plug-and-play modo padrão no Yarn 2. Adicione o seguinte ao arquivo `.yarnrc.yml` do seu projeto para desativar esse atributo.
```
nodeLinker: node-modules
```
### Aplicações do CDK
Veja a seguir um exemplo de arquivo `package.json` gerado pelo comando `cdk init --language typescript`. O arquivo gerado para JavaScript é semelhante, só que sem as entradas TypeScript relacionadas.
```
{
"name": "my-package",
"version": "0.1.0",
"bin": {
"my-package": "bin/my-package.js"
},
"scripts": {
"build": "tsc",
"watch": "tsc -w",
"test": "jest",
"cdk": "cdk"
},
"devDependencies": {
"@types/jest": "^26.0.10",
"@types/node": "10.17.27",
"jest": "^26.4.2",
"ts-jest": "^26.2.0",
"aws-cdk": "2.16.0",
"ts-node": "^9.0.0",
"typescript": "~3.9.7"
},
"dependencies": {
"aws-cdk-lib": "2.16.0",
"constructs": "^10.0.0",
"source-map-support": "^0.5.16"
}
}
```
Para aplicações CDK implantáveis, `aws-cdk-lib` deve ser especificado na seção `dependencies` de `package.json`. É possível usar um especificador de número de versão com acento circunflexo (^) para indicar que aceitará versões posteriores à especificada, desde que estejam na mesma versão principal.
Para construções experimentais, especifique as versões exatas dos módulos da biblioteca de construções alfa, APIs que podem mudar. Não use ^ ou \$1, pois versões posteriores desses módulos podem trazer alterações na API que podem prejudicar sua aplicação.
Especifique as versões das bibliotecas e ferramentas necessárias para testar sua aplicação (por exemplo, a estrutura de teste `jest`) na seção `devDependencies` de `package.json`. Opcionalmente, use ^ para especificar que versões compatíveis posteriores sejam aceitáveis.
### Bibliotecas de constructos de terceiros
Se você estiver desenvolvendo uma biblioteca de constructos, especifique suas dependências usando uma combinação das seções `peerDependencies` e `devDependencies`, conforme mostrado no arquivo `package.json` de exemplo a seguir.
```
{
"name": "my-package",
"version": "0.0.1",
"peerDependencies": {
"aws-cdk-lib": "^2.14.0",
"@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
"constructs": "^10.0.0"
},
"devDependencies": {
"aws-cdk-lib": "2.14.0",
"@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
"constructs": "10.0.0",
"jsii": "^1.50.0",
"aws-cdk": "^2.14.0"
}
}
```
Em `peerDependencies`, use um acento circunflexo (^) para especificar a versão mais baixa de `aws-cdk-lib` com a qual sua biblioteca trabalha. Isso maximiza a compatibilidade da sua biblioteca com uma variedade de versões do CDK. Especifique as versões exatas dos módulos da biblioteca de construção alfa, APIs que podem mudar. O uso de `peerDependencies` garante que haja apenas uma cópia de todas as bibliotecas CDK na árvore `node_modules`.
Em `devDependencies`, especifique as ferramentas e bibliotecas que você precisa para testar, opcionalmente com ^ para indicar que versões compatíveis posteriores são aceitáveis. Especifique exatamente (sem ^ ou \$1) as versões mais baixas de `aws-cdk-lib` e outros pacotes do CDK com os quais você anuncia a compatibilidade da sua biblioteca. Essa prática garante que seus testes sejam executados nessas versões. Dessa forma, se você usar inadvertidamente um atributo encontrado apenas em versões mais recentes, seus testes poderão detectá-lo.
**Atenção**
`peerDependencies` são instalados automaticamente somente pelo NPM 7 e versões posteriores. Se você estiver usando o NPM 6 ou versão anterior, ou se estiver usando o Yarn, deverá incluir as dependências de suas dependências no `devDependencies`. Caso contrário, elas não serão instaladas e você receberá um aviso sobre dependências de pares não resolvidas.
### Instalação e atualização de dependências
Use o comando a seguir para instalar as dependências do seu projeto.
**Example**
```
# Install the latest version of everything that matches the ranges in 'package.json'
npm install
# Install the same exact dependency versions as recorded in 'package-lock.json'
npm ci
```
```
# Install the latest version of everything that matches the ranges in 'package.json'
yarn upgrade
# Install the same exact dependency versions as recorded in 'yarn.lock'
yarn install --frozen-lockfile
```
Para atualizar os módulos instalados, os comandos `npm install` e `yarn upgrade` anteriores podem ser usados. Qualquer um dos comandos atualiza os pacotes em `node_modules` para as versões mais recentes que atendem às regras em `package.json`. No entanto, não atualizam `package.json` por conta própria, o que talvez você queira fazer para definir uma nova versão mínima. Se você hospedar seu pacote em GitHub, poderá configurar as atualizações de [versão do Dependabot para serem atualizadas](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) automaticamente. `package.json` Como alternativa, use [npm-check-updates](https://www.npmjs.com/package/npm-check-updates).
**Importante**
Por padrão, quando você instala ou atualiza dependências, o NPM e o Yarn escolhem a versão mais recente de cada pacote que atenda aos requisitos especificados em `package.json`. Sempre existe o risco de que essas versões sejam quebradas (acidental ou intencionalmente). Teste minuciosamente depois de atualizar as dependências do seu projeto.
## AWS Expressões idiomáticas do CDK em JavaScript
### Props
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o *escopo* no qual a construção está sendo definida (seu pai na árvore de construção), um *id* e *props*, um pacote de key/value pares que a construção usa para configurar os AWS recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
Usar um IDE ou editor que tenha um bom JavaScript preenchimento automático ajudará a evitar erros ortográficos nos nomes das propriedades. Se um constructo espera uma propriedade `encryptionKeys` e você a escreve `encryptionkeys` ao instanciá-lo, o valor que pretendia passar não foi transmitido. Isso pode causar um erro no momento da síntese, se a propriedade for necessária, ou fazer com que a propriedade seja ignorada silenciosamente se for opcional. No último caso, você pode obter um comportamento padrão que pretendia substituir. Tome cuidado especial aqui.
Ao criar uma subclasse de uma classe da AWS Construct Library (ou substituir um método que usa um argumento semelhante a adereços), talvez você queira aceitar propriedades adicionais para seu próprio uso. Esses valores serão ignorados pela classe principal ou pelo método substituído, porque eles nunca são acessados nesse código, então você geralmente pode transmitir todas as props recebidas.
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Passar o valor que você recebe para a cadeia de herança pode causar um comportamento inesperado. É mais seguro passar uma cópia rasa dos adereços que você recebeu com sua propriedade removida ou configurada para `undefined`. Por exemplo:
```
super(scope, name, {...props, encryptionKeys: undefined});
```
Como alternativa, nomeie suas propriedades para que fique claro que elas pertencem ao seu constructo. Dessa forma, é improvável que eles colidam com propriedades em futuras versões do AWS CDK. Se houver muitas delas, use um único objeto com nome apropriado para mantê-las.
### Valores ausentes
Valores ausentes em um objeto (como`props`) têm o valor `undefined` em JavaScript. As técnicas usuais se aplicam para lidar com eles. Por exemplo, uma expressão idiomática comum para acessar uma propriedade de um valor que pode ser indefinido é a seguinte:
```
// a may be undefined, but if it is not, it may have an attribute b
// c is undefined if a is undefined, OR if a doesn't have an attribute b
let c = a && a.b;
```
No entanto, se `a` pudesse ter algum outro valor “falso” além de `undefined`, é melhor tornar o teste mais explícito. Aqui, aproveitaremos o fato de que `null` e `undefined` são iguais para testar os dois ao mesmo tempo:
```
let c = a == null ? a : a.b;
```
**dica**
Node.js 14.0 e versões posteriores oferecem suporte a novos operadores que podem simplificar o tratamento de valores indefinidos. Para obter mais informações, consulte as propostas [opcionais de encadeamento](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md) e [coalescência nula](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md).
## Usando TypeScript exemplos com JavaScript
[TypeScript](https://www.typescriptlang.org/)é a linguagem que usamos para desenvolver o AWS CDK e foi a primeira linguagem suportada para o desenvolvimento de aplicativos. Por isso, muitos exemplos de código de AWS CDK disponíveis estão escritos nela. TypeScript Esses exemplos de código podem ser um bom recurso para JavaScript desenvolvedores; você só precisa remover as partes TypeScript específicas do código.
TypeScript os trechos geralmente usam o novo ECMAScript `import` e as `export` palavras-chave para importar objetos de outros módulos e declarar que os objetos serão disponibilizados fora do módulo atual. Node.js acaba de começar a oferecer suporte a essas palavras-chave em suas versões mais recentes. Dependendo da versão do Node.js que você está usando (ou deseja oferecer suporte), é possível reescrever as importações e exportações para usar a sintaxe mais antiga.
As importações podem ser substituídas por chamadas para a função `require()`.
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';
```
```
const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');
```
As exportações podem ser atribuídas ao objeto `module.exports`.
**Example**
```
export class Stack1 extends cdk.Stack {
// ...
}
export class Stack2 extends cdk.Stack {
// ...
}
```
```
class Stack1 extends cdk.Stack {
// ...
}
class Stack2 extends cdk.Stack {
// ...
}
module.exports = { Stack1, Stack2 }
```
**nota**
Uma alternativa para usar as importações e exportações de estilo antigo é usar o módulo [esm](https://www.npmjs.com/package/esm).
Depois de classificar as importações e exportações, é possível se aprofundar no código real. Você pode se deparar com esses recursos comumente usados TypeScript :
+ Anotações de tipo
+ Definições de interface
+ Conversões de tipo/transmissões
+ Modificadores de acesso
As anotações de tipo podem ser fornecidas para variáveis, membros da classe, parâmetros da função e tipos de retorno da função. Para variáveis, parâmetros e membros, os tipos são especificados seguindo o identificador com dois pontos e o tipo. Os valores de retorno da função seguem a assinatura da função e consistem em dois pontos e no tipo.
Para converter o código com anotação de tipo em JavaScript, remova os dois pontos e o tipo. Os membros da classe devem ter algum valor em JavaScript; defina-os como `undefined` se eles tiverem apenas uma anotação de tipo em. TypeScript
**Example**
```
var encrypted: boolean = true;
class myStack extends cdk.Stack {
bucket: s3.Bucket;
// ...
}
function makeEnv(account: string, region: string) : object {
// ...
}
```
```
var encrypted = true;
class myStack extends cdk.Stack {
bucket = undefined;
// ...
}
function makeEnv(account, region) {
// ...
}
```
Em TypeScript, as interfaces são usadas para dar um nome aos pacotes de propriedades obrigatórias e opcionais e seus tipos. Em seguida, você pode usar o nome da interface como uma anotação de tipo. TypeScript garantirá que o objeto que você usa como, por exemplo, argumento para uma função tenha as propriedades necessárias dos tipos certos.
```
interface myFuncProps {
code: lambda.Code,
handler?: string
}
```
JavaScript não tem um recurso de interface, portanto, depois de remover as anotações de tipo, exclua totalmente as declarações da interface.
Quando uma função ou método retorna um tipo de uso geral (como`object`), mas você deseja tratar esse valor como um tipo filho mais específico para acessar propriedades ou métodos que não fazem parte da interface do tipo mais geral, TypeScript você pode *converter* o valor usando `as` seguido por um nome de tipo ou interface. JavaScript não suporta (ou precisa) isso, então simplesmente remova `as` o identificador a seguir. Uma sintaxe de conversão menos comum é usar um nome de tipo entre colchetes, ``; essas conversões também devem ser removidas.
Finalmente, TypeScript suporta os modificadores de acesso `public``protected`, e `private` para membros de classes. Todos os alunos da turma JavaScript são públicos. Basta remover esses modificadores onde quer que você os veja.
Saber como identificar e remover esses TypeScript recursos ajuda muito a adaptar pequenos TypeScript trechos a. JavaScript Mas pode ser impraticável converter TypeScript exemplos mais longos dessa forma, pois é mais provável que eles usem outros TypeScript recursos. Para essas situações, recomendamos o [Sucrase](https://github.com/alangpierce/sucrase). O Sucrase não reclamará se o código usar uma variável indefinida, por exemplo, como `tsc` faria. Se for sintaticamente válido, com poucas exceções, o Sucrase pode traduzi-lo para. JavaScript Isso o torna particularmente valioso para converter trechos que podem não ser executáveis isoladamente.
## Migrando para TypeScript
Muitos JavaScript desenvolvedores migram à [TypeScript](https://www.typescriptlang.org/)medida que seus projetos se tornam maiores e mais complexos. TypeScript é um superconjunto de JavaScript — todo JavaScript código é válido TypeScript , portanto, nenhuma alteração em seu código é necessária — e também é uma linguagem de CDK compatível. AWS As anotações de tipo e outros TypeScript recursos são opcionais e podem ser adicionados ao seu aplicativo AWS CDK à medida que você achar valor neles. TypeScript também oferece acesso antecipado a novos JavaScript recursos, como encadeamento opcional e coalescência nula, antes de serem finalizados, sem exigir que você atualize o Node.js.
TypeScriptAs interfaces “baseadas em formas” da, que definem pacotes de propriedades obrigatórias e opcionais (e seus tipos) em um objeto, permitem que erros comuns sejam detectados enquanto você escreve o código e facilitam que seu IDE forneça preenchimento automático robusto e outras dicas de codificação em tempo real.
A codificação TypeScript envolve uma etapa adicional: compilar seu aplicativo com o TypeScript compilador,. `tsc` Para aplicativos AWS CDK típicos, a compilação requer alguns segundos no máximo.
A maneira mais fácil de migrar um aplicativo JavaScript AWS CDK existente para o novo projeto TypeScript é criar um novo TypeScript projeto usando `cdk init app --language typescript` e depois copiar seus arquivos de origem (e quaisquer outros arquivos necessários, como ativos como o código-fonte da função AWS Lambda) para o novo projeto. Renomeie seus JavaScript arquivos para finalizar `.ts` e começar a desenvolver em TypeScript.
# Trabalhando com o AWS CDK em Python
Python é uma linguagem cliente totalmente compatível com o AWS Cloud Development Kit (AWS CDK) e é considerada estável. Trabalhar com o AWS CDK em Python usa ferramentas familiares, incluindo a implementação padrão do Python CPython (), ambientes virtuais com e o instalador do `virtualenv` pacote Python. `pip` Os módulos que compõem a AWS Construct Library são distribuídos via [pypi.org](https://pypi.org/search/?q=aws-cdk). A versão Python do AWS CDK até usa identificadores no estilo Python (por exemplo, nomes de métodos). `snake_case`
É possível usar qualquer editor ou IDE. [Muitos desenvolvedores de AWS CDK usam o [Visual Studio Code (ou seu equivalente de código](https://code.visualstudio.com/) aberto [VSCodium](https://vscodium.com/)), que tem um bom suporte para Python por meio de uma extensão oficial.](https://marketplace.visualstudio.com/items?itemName=ms-python.python) O editor IDLE incluído no Python será suficiente para começar. Os módulos Python para o AWS CDK têm dicas de tipo, que são úteis para uma ferramenta de linting ou um IDE que oferece suporte à validação de tipo.
## Conceitos básicos do Python
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte [Introdução ao AWS CDK.](getting-started.md)
Os aplicativos Python AWS CDK exigem o Python 3.9 ou posterior. Se você ainda não o tiver instalado, [baixe uma versão compatível](https://www.python.org/downloads/) para seu sistema operacional em [python.org](https://www.python.org/). Se você usa Linux, seu sistema pode ter vindo com uma versão compatível ou é possível instalá-la usando o gerenciador de pacotes da sua distribuição (`yum`, `apt`, etc.). Usuários de Mac podem se interessar pelo [Homebrew](https://brew.sh/), um gerenciador de pacotes no estilo Linux para macOS.
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
O instalador do pacote Python, `pip`, e o gerenciador de ambiente virtual, `virtualenv`, também são necessários . As instalações do Windows de versões compatíveis do Python incluem essas ferramentas. No Linux, `pip` e `virtualenv` podem ser fornecidos como pacotes separados em seu gerenciador de pacotes. Ou, então, você pode instalá-los com o seguinte comando:
```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```
Se você encontrar um erro de permissão, execute os comandos acima com o sinalizador `--user` para que os módulos sejam instalados em seu diretório de usuário ou use `sudo` para obter as permissões para instalar os módulos em todo o sistema.
**nota**
É comum que as distribuições Linux usem o nome executável de `python3` para Python 3.x e que `python` se refira uma instalação do Python 2.x. Algumas distribuições têm um pacote opcional que você pode instalar que faz com que o comando `python` se refira ao Python 3. Caso contrário, é possível ajustar o comando usado para executar sua aplicação editando `cdk.json` no diretório principal do projeto.
**nota**
No Windows, talvez você queira invocar o Python (e o `pip`) usando o executável `py`, o [inicializador Python para Windows](https://docs.python.org/3/using/windows.html#launcher). Entre outras coisas, o lançador permite que você especifique facilmente qual versão instalada do Python deseja usar.
Se digitar `python` na linha de comando resultar em uma mensagem sobre a instalação do Python na Windows Store, mesmo depois de instalar uma versão do Python para Windows, abra o painel de configurações de aliases de execução de aplicações do Windows e desative as duas entradas do App Installer para Python.
## Criação de um projeto
Você cria um novo projeto AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `python`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador do Python; por exemplo, não deve começar com um número nem conter espaços.
Para trabalhar com o novo projeto, ative o respectivo ambiente virtual. Isso permite que as dependências do projeto sejam instaladas localmente na pasta do projeto, em vez de globalmente.
```
$ source .venv/bin/activate
```
**nota**
Você pode reconhecer isso como o Mac/Linux comando para ativar um ambiente virtual. Os modelos do Python incluem um arquivo em lote, `source.bat`, que permite que o mesmo comando seja utilizado no Windows. O comando tradicional do Windows `.\venv\Scripts\activate` também funciona.
Se você inicializou seu projeto AWS CDK usando o CDK Toolkit v1.70.0 ou anterior, seu ambiente virtual estará no diretório em vez de. `.env` `.venv`
**Importante**
Ative o ambiente virtual do projeto sempre que começar a trabalhar nele. Caso contrário, você não terá acesso aos módulos instalados lá, e os módulos que você instalar entrarão no diretório global do módulo do Python (ou resultarão em um erro de permissão).
Depois de ativar seu ambiente virtual pela primeira vez, instale as dependências padrão da aplicação:
```
$ python -m pip install -r requirements.txt
```
## Gerenciando módulos da AWS Construct Libr
Use o instalador de pacotes Python,`pip`, para instalar e atualizar os módulos da AWS Construct Library para uso por seus aplicativos, bem como por outros pacotes necessários. `pip`também instala as dependências desses módulos automaticamente. Se seu sistema não reconhecer `pip` como um comando independente, invoque `pip` como um módulo Python, desta forma:
```
$ python -m pip
```
A maioria das construções de AWS CDK está pronta. `aws-cdk-lib` Os módulos experimentais estão em módulos separados chamados de `aws-cdk..alpha`. O nome do serviço inclui um prefixo *aws*. Se você não tiver certeza do nome de um módulo, [procure-o no PyPI](https://pypi.org/search/?q=aws-cdk). Por exemplo, o comando abaixo instala a AWS CodeStar biblioteca.
```
$ python -m pip install aws-cdk.aws-codestar-alpha
```
Alguns constructos de serviços estão em mais de um namespace. Por exemplo, além de `aws-cdk.aws-route53`, há três namespaces adicionais do Amazon Route 53, denominados `aws-route53-targets`, `aws-route53-patterns` e `aws-route53resolver`.
**nota**
A [edição Python de referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) também mostra os nomes dos pacotes.
Os nomes usados para importar módulos da AWS Construct Library em seu código Python são semelhantes aos seguintes.
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```
Recomendamos as seguintes práticas ao importar classes AWS CDK e módulos da AWS Construct Library em seus aplicativos. Seguir essas diretrizes ajudará a tornar seu código consistente com outros aplicativos AWS CDK, além de ser mais fácil de entender.
+ Geralmente, importe classes individuais de `aws_cdk` de nível superior.
```
from aws_cdk import App, Construct
```
+ Se você precisar de muitas classes de `aws_cdk`, poderá usar um alias de namespace de `cdk` em vez de importar classes individuais. Evite fazer as duas coisas.
```
import aws_cdk as cdk
```
+ Geralmente, importe AWS Construct Libraries usando aliases curtos de namespace.
```
import aws_cdk.aws_s3 as s3
```
Depois de instalar um módulo, atualize o arquivo `requirements.txt` do seu projeto, que lista as dependências do seu projeto. É melhor fazer isso manualmente em vez de usar `pip freeze`. `pip freeze` captura as versões atuais de todos os módulos instalados em seu ambiente virtual Python, o que pode ser útil durante o empacotamento de um projeto para ser executado em outro lugar.
Normalmente, porém, `requirements.txt` deve listar somente as dependências de nível superior (módulos dos quais sua aplicação depende diretamente) e não as dependências dessas bibliotecas. Essa estratégia simplifica a atualização de suas dependências.
É possível editar `requirements.txt` para permitir atualizações; basta substituir `==` que precede o número da versão por `~=` para permitir atualizações para uma versão compatível superior ou remover totalmente o requisito de versão para especificar a versão mais recente disponível do módulo.
Com o arquivo `requirements.txt` editado adequadamente para permitir atualizações, emita este comando para atualizar os módulos instalados do seu projeto a qualquer momento:
```
$ pip install --upgrade -r requirements.txt
```
## Gerenciamento de dependências em Python
No Python, você especifica dependências colocando-as em `requirements.txt` para aplicações ou `setup.py` para bibliotecas de constructos. As dependências são, então, gerenciadas com a ferramenta PIP. PIP é chamado de uma das seguintes maneiras:
```
pip
python -m pip
```
A invocação `python -m pip` funciona na maioria dos sistemas; `pip` requer que o executável do PIP esteja no caminho do sistema. Se `pip` não funcionar, tente substituir por `python -m pip`.
O comando `cdk init --language python` cria um ambiente virtual para seu novo projeto. Isso permite que cada projeto tenha suas próprias versões de dependências e também um arquivo `requirements.txt` básico. É necessário ativar esse ambiente virtual executando `source .venv/bin/activate` sempre que começar a trabalhar com o projeto. No Windows, execute `.\venv\Scripts\activate` em vez disso
### Aplicações do CDK
Veja a seguir um exemplo de arquivo `requirements.txt`. Como o PIP não tem um atributo de bloqueio de dependências, recomendamos que você use o operador == para especificar as versões exatas de todas as dependências, conforme mostrado aqui.
```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```
A instalação de um módulo com `pip install` não o adiciona automaticamente a `requirements.txt`. É necessário fazer isso sozinho. Se quiser atualizar para uma versão posterior de uma dependência, edite o número da versão em `requirements.txt`.
Para instalar ou atualizar as dependências do seu projeto depois de criar ou editar `requirements.txt`, execute o seguinte:
```
python -m pip install -r requirements.txt
```
**dica**
O comando `pip freeze` gera as versões de todas as dependências instaladas em um formato que pode ser gravado em um arquivo de texto. Isso pode ser usado como um arquivo de requisitos com `pip install -r`. Esse arquivo é conveniente para fixar todas as dependências (inclusive as transitivas) nas versões exatas com as quais você testou. Para evitar problemas ao atualizar pacotes posteriormente, use um arquivo separado para isso, como `freeze.txt` (não `requirements.txt`). Em seguida, regenere ao atualizar as dependências do seu projeto.
### Bibliotecas de constructos de terceiros
Nas bibliotecas, as dependências são especificadas em `setup.py`, para que as dependências transitivas sejam baixadas automaticamente quando o pacote é consumido por uma aplicação. Caso contrário, toda aplicação que quiser usar seu pacote precisará copiar suas dependências para `requirements.txt`. Um exemplo de `setup.py` é mostrado aqui.
```
from setuptools import setup
setup(
name='my-package',
version='0.0.1',
install_requires=[
'aws-cdk-lib==2.14.0',
],
...
)
```
Para trabalhar no pacote para desenvolvimento, crie ou ative um ambiente virtual e execute o comando a seguir.
```
python -m pip install -e .
```
Embora o PIP instale automaticamente dependências transitivas, só pode haver uma cópia instalada de qualquer pacote. A versão mais alta especificada na árvore de dependências é selecionada; as aplicações sempre têm a última palavra em qual versão dos pacotes serão instalados.
## AWS Expressões idiomáticas do CDK em Python
### Conflitos de linguagem
Em Python, `lambda` é uma palavra-chave de linguagem, então você não pode usá-la como um nome para o módulo da biblioteca de construção do AWS Lambda ou para as funções do Lambda. A convenção do Python para esses conflitos é usar um sublinhado à direita, como em `lambda_`, no nome da variável.
Por convenção, o segundo argumento para construções AWS CDK é denominado. `id` Ao escrever suas próprias pilhas e constructos, chamar um parâmetro `id` “sombreia” a função integrada do Python `id()`, que retorna o identificador exclusivo de um objeto. Essa função não é usada com muita frequência, mas se você precisar dela em seu constructo, renomeie o argumento, como `construct_id`.
### Argumentos e propriedades
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o *escopo* no qual a construção está sendo definida (seu pai na árvore de construção), um *id* e *props*, um pacote de key/value pares que a construção usa para configurar os recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
*escopo* e *id* devem sempre ser passados como argumentos posicionais, não como argumentos de palavra-chave, porque seus nomes mudam se o constructo aceitar uma propriedade chamada *escopo* ou *id*.
No Python, props são expressos como argumentos de palavras-chave. Se um argumento contiver estruturas de dados aninhadas, elas serão expressas usando uma classe que usa seus próprios argumentos de palavra-chave na instanciação. O mesmo padrão é aplicado a outras chamadas de método que usam um argumento estruturado.
Por exemplo, em um método `add_lifecycle_rule` de um bucket do Amazon S3, a propriedade `transitions` é uma lista de instâncias `Transition`.
```
bucket.add_lifecycle_rule(
transitions=[
Transition(
storage_class=StorageClass.GLACIER,
transition_after=Duration.days(10)
)
]
)
```
Ao estender uma classe ou substituir um método, talvez você queira aceitar argumentos adicionais para seus próprios propósitos que não sejam compreendidos pela classe principal. Nesse caso, é necessário aceitar os argumentos que não lhe interessam usando a expressão idiomática \$1\$1kwargs e usar argumentos somente com palavras-chave para aceitar os argumentos nos quais tem interesse. Ao chamar o construtor do pai ou o método substituído, passe somente os argumentos que ele espera (geralmente apenas \$1\$1kwargs). Passar argumentos inesperados para a classe ou o método resulta em um erro.
```
class MyConstruct(Construct):
def __init__(self, id, *, MyProperty=42, **kwargs):
super().__init__(self, id, **kwargs)
# ...
```
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Isso não causará problemas técnicos para os usuários do seu constructo ou método (como sua propriedade não é passada “para cima na cadeia”, a classe principal ou o método substituído simplesmente usará um valor padrão), mas isso pode causar confusão. É possível evitar esse problema em potencial nomeando suas propriedades de forma que elas claramente pertençam ao seu constructo. Se houver muitas propriedades novas, agrupe-as em uma classe com nome apropriado e passe-a como um único argumento de palavra-chave.
### Valores ausentes
O AWS CDK é usado `None` para representar valores ausentes ou indefinidos. Ao trabalhar com \$1\$1kwargs, use o método `get()` do dicionário para fornecer um valor padrão se uma propriedade não for fornecida. Evite usar `kwargs[…]`, pois isso aumenta `KeyError` para valores ausentes.
```
encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing
```
Alguns métodos de AWS CDK (como `tryGetContext()` obter um valor de contexto de tempo de execução) podem retornar`None`, o que você precisará verificar explicitamente.
### Uso de interfaces
O Python não tem um atributo de interface como algumas outras linguagens, embora tenha [classes básicas abstratas](https://docs.python.org/3/library/abc.html), que são semelhantes. (Se você não está familiarizado com interfaces, a Wikipedia tem [uma boa introdução](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, a linguagem na qual o AWS CDK é implementado, fornece interfaces, e as construções e outros objetos AWS CDK geralmente exigem um objeto que adira a uma interface específica, em vez de herdar de uma classe específica. Portanto, o AWS CDK fornece seu próprio recurso de interface como parte da camada [JSII](https://github.com/aws/jsii).
Para indicar que uma classe implementa uma interface específica, você pode usar o decorador `@jsii.implements`:
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
### Armadilhas de tipo
O Python usa tipagem dinâmica, em que todas as variáveis podem se referir a um valor de qualquer tipo. Os parâmetros e valores de retorno podem ser anotados com tipos, mas essas são “dicas” e não são impostas. Isso significa que, em Python, é fácil passar o tipo incorreto de valor para uma construção de AWS CDK. Em vez de receber um erro de tipo durante a compilação, como ocorre em uma linguagem com digitação estática, você pode receber um erro de tempo de execução quando a camada JSII (que se traduz entre o Python e o núcleo do AWS TypeScript CDK) não consegue lidar com o tipo inesperado.
Em nossa experiência, os erros de tipo que os programadores de Python cometem tendem a se enquadrar nessas categorias.
+ Passar um único valor em que um constructo espera um contêiner (lista ou dicionário do Python) ou vice-versa.
+ Passar um valor de um tipo associado a um constructo de camada 1 (`CfnXxxxxx`) para um constructo L2 ou L3, ou vice-versa.
## Evitando erros de tipo
Os módulos Python do AWS CDK incluem anotações de tipo, para que você possa usar ferramentas que os ajudem a detectar erros de tipo antes da implantação.
### Integração com IDE (recomendada)
O Visual Studio Code com Pylance fornece verificação de tipos em tempo real à medida que você escreve código:
1. Instale a extensão [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
1. Configure a verificação estrita de tipo em`.vscode/settings.json`:
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. Os erros de digitação agora aparecem imediatamente com rabiscos vermelhos e mensagens de erro detalhadas
[PyCharm](https://www.jetbrains.com/pycharm/)também fornece verificação de tipos integrada com recursos semelhantes.
### Verificação do tipo de linha de comando
Para CI/CD pipelines ou validação pré-confirmação, use um desses verificadores de tipo:
**MyPy (Baseado em Python):**
```
pip install mypy
mypy app.py
```
**Pyright (mais rápido, JavaScript baseado, com o mesmo motor do Pylance):**
```
npm install -g pyright
pyright app.py
```
### Fluxo de trabalho recomendado
1. Durante o desenvolvimento: use Pyright ou Pylance para obter feedback instantâneo
1. Antes de confirmar: Execute `mypy app.py` ou `pyright app.py`
1. Em CI/CD: faça da verificação de tipo uma etapa necessária antes da implantação
# Trabalhando com o AWS CDK em Java
Java é uma linguagem de cliente totalmente compatível com o AWS CDK e é considerada estável. Você pode desenvolver aplicativos AWS CDK em Java usando ferramentas familiares, incluindo o JDK (da Oracle ou uma distribuição do OpenJDK, como o Amazon Corretto) e o Apache Maven.
O AWS CDK é compatível com Java 8 e versões posteriores. No entanto, recomendamos usar a versão mais recente possível, pois as versões posteriores da linguagem incluem melhorias que são particularmente convenientes para o desenvolvimento de aplicativos AWS CDK. Por exemplo, o Java 9 introduz o `Map.of()` método (uma maneira conveniente de declarar hashmaps que seriam escritos como literais de objeto em). TypeScript O Java 10 introduz a inferência de tipos locais usando a palavra-chave `var`.
**nota**
A maioria dos exemplos de código neste Guia do desenvolvedor funciona com Java 8. Alguns exemplos usam `Map.of()`; esses exemplos incluem comentários observando que exigem o Java 9.
Você pode usar qualquer editor de texto ou um IDE Java que possa ler projetos Maven para trabalhar em seus aplicativos AWS CDK. Fornecemos dicas sobre o [Eclipse](https://www.eclipse.org/downloads/) neste guia, mas o IntelliJ IDEA e outros IDEs podem importar projetos Maven e podem ser usados para desenvolver aplicativos CDK em Java. NetBeans AWS
É possível escrever aplicativos AWS CDK em linguagens hospedadas pela JVM que não sejam Java (por exemplo, Kotlin, Groovy, Clojure ou Scala), mas a experiência pode não ser particularmente idiomática e não podemos fornecer suporte para essas linguagens.
## Conceitos básicos do Java
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte [Introdução ao AWS CDK.](getting-started.md)
Os aplicativos Java AWS CDK exigem o Java 8 (v1.8) ou posterior. Recomendamos o [Amazon Corretto](https://aws.amazon.com/corretto/), mas é possível usar qualquer distribuição do OpenJDK ou o [JDK da Oracle](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). Você também precisará do [Apache Maven](https://maven.apache.org/download.cgi) 3.5 ou versão posterior. Você também pode usar ferramentas como o Gradle, mas os esqueletos de aplicativos gerados pelo AWS CDK Toolkit são projetos Maven.
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
## Criação de um projeto
Você cria um novo projeto AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `java`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language java
```
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador de Java; por exemplo, não deve começar com um número nem conter espaços.
O projeto resultante inclui uma referência ao pacote Maven do `software.amazon.awscdk`. Ele e suas dependências são instalados automaticamente pelo Maven.
Se você estiver usando um IDE, agora pode abrir ou importar o projeto. No Eclipse, por exemplo, escolha **Arquivo** > **Importar** > **Maven** > **Projetos existentes do Maven**. Certifique-se de que as configurações do projeto estejam definidas para usar o Java 8 (1.8).
## Gerenciando módulos da AWS Construct Libr
Use o Maven para instalar os pacotes da AWS Construct Library, que estão no grupo`software.amazon.awscdk`. A maioria dos constructo está no artefato `aws-cdk-lib`, que é adicionado aos novos projetos Java por padrão. Os módulos para serviços cujo suporte de CDK de alto nível ainda está sendo desenvolvido estão em pacotes “experimentais” separados, nomeados com uma versão curta (sem ou prefixo da AWS Amazon) do nome do serviço. [Pesquise no Repositório Central do Maven](https://search.maven.org/search?q=software.amazon.awscdk) para encontrar os nomes de todas as bibliotecas AWS CDK e AWS Construct Module.
**nota**
A [edição Java da referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/java/index.html) também mostra os nomes dos pacotes.
O suporte da AWS Construct Library de alguns serviços está em mais de um namespace. Por exemplo, o Amazon Route 53 tem sua funcionalidade dividida em `software.amazon.awscdk.route53`, `route53-patterns`, `route53resolver` e `route53-targets`.
O pacote AWS CDK principal é importado em código Java como`software.amazon.awscdk`. Os módulos dos vários serviços na AWS Construct Library estão abaixo `software.amazon.awscdk.services` e são nomeados de forma semelhante ao nome do pacote Maven. Por exemplo, o namespace do módulo do Amazon S3 é `software.amazon.awscdk.services.s3`.
Recomendamos escrever uma `import` instrução Java separada para cada classe da AWS Construct Library usada em cada um dos seus arquivos de origem Java e evitar importações de caracteres curinga. Você sempre pode usar o nome totalmente qualificado de um tipo (incluindo seu namespace) sem uma declaração `import`.
Se sua aplicação depender de um pacote experimental, edite o `pom.xml` do seu projeto `` e adicione um novo elemento `` no contêiner . Por exemplo, o `` elemento a seguir especifica o módulo da biblioteca de construção CodeStar experimental:
```
software.amazon.awscdkcodestar-alpha2.0.0-alpha.10
```
**dica**
Se você usa um IDE Java, ele provavelmente tem atributos para gerenciar dependências do Maven. No entanto, recomendamos editar `pom.xml` diretamente, a menos que você tenha certeza absoluta de que a funcionalidade do IDE corresponde ao que você faria manualmente.
## Gerenciamento de dependências em Java
Em Java, as dependências são especificadas em `pom.xml` e instaladas usando o Maven. O contêiner `` inclui um elemento `` para cada pacote. A seguir está uma seção `pom.xml` para uma aplicação Java típico do CDK.
```
software.amazon.awscdkaws-cdk-lib2.14.0software.amazon.awscdkappsync-alpha2.10.0-alpha.0
```
**dica**
Muitos Java IDEs têm suporte integrado ao Maven e `pom.xml` editores visuais, que podem ser convenientes para gerenciar dependências.
O Maven não oferece suporte ao bloqueio de dependências. Embora seja possível especificar intervalos de versões em `pom.xml`, recomendamos que você sempre use versões exatas para manter suas compilações repetíveis.
O Maven instala automaticamente dependências transitivas, mas só pode haver uma cópia instalada de cada pacote. A versão mais alta especificada na árvore POM é selecionada; as aplicações sempre têm a última palavra em qual versão dos pacotes serão instalados.
O Maven instala ou atualiza automaticamente suas dependências sempre que você constrói (`mvn compile`) ou empacota (`mvn package`) seu projeto. O Kit de Ferramentas CDK faz isso automaticamente toda vez que você o executa, então geralmente não há necessidade de invocar manualmente o Maven.
## AWS Expressões idiomáticas do CDK em Java
### Props
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o *escopo* no qual a construção está sendo definida (seu pai na árvore de construção), um *id* e *props*, um pacote de key/value pares que a construção usa para configurar os recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
Em Java, os props são expressos usando o [padrão Builder](https://en.wikipedia.org/wiki/Builder_pattern). Cada tipo de constructo tem um tipo de props correspondente; por exemplo, o constructo `Bucket` (que representa um bucket do Amazon S3) usa como props uma instância de `BucketProps`.
A `BucketProps` classe (como toda classe de adereços da AWS Construct Library) tem uma classe interna chamada`Builder`. O tipo `BucketProps.Builder` oferece métodos para definir as várias propriedades de uma instância `BucketProps`. Cada método retorna a instância `Builder`, para que as chamadas do método possam ser encadeadas para definir várias propriedades. No final da cadeia, você liga `build()` para realmente produzir o objeto `BucketProps`.
```
Bucket bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps.Builder()
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build());
```
Constructos e outras classes que usam um objeto semelhante a props como argumento final oferecem um atalho. A classe tem uma `Builder` própria que instancia ela e seu objeto de props em uma única etapa. Dessa forma, você não precisa instanciar explicitamente (por exemplo) `BucketProps` e um `Bucket`, e não precisa de uma importação para o tipo props.
```
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build();
```
Ao derivar seu próprio constructo de um constructo existente, talvez você queira aceitar propriedades adicionais. Recomendamos que você siga esses padrões do construtor. No entanto, isso não é tão simples quanto criar uma subclasse de uma classe de constructo. Você mesmo deve fornecer as partes móveis das duas novas classes `Builder`. É possível preferir simplesmente que seu constructo aceite um ou mais argumentos adicionais. É necessário fornecer construtores adicionais quando um argumento for opcional.
### Estruturas genéricas
Em alguns APIs, o AWS CDK usa JavaScript matrizes ou objetos não digitados como entrada para um método. (Veja, por exemplo, AWS CodeBuild o [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue)método de.) Em Java, esses objetos são representados como `java.util.Map`. Nos casos em que os valores são todos cadeias de caracteres, você pode usar `Map`.
O Java não fornece uma maneira de escrever literais para esses contêineres, como fazem algumas outras linguagens. No Java 9 e versões posteriores, você pode usar [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-) para definir convenientemente mapas de até dez entradas em linha com uma dessas chamadas.
```
java.util.Map.of(
"base-directory", "dist",
"files", "LambdaStack.template.json"
)
```
Para criar mapas com mais de dez entradas, use [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-).
Se você estiver usando o Java 8, poderá fornecer seus próprios métodos semelhantes a esses.
JavaScript matrizes são representadas como `List