O [Guia de referência da API do AWS SDK para JavaScript V3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) descreve em detalhes todas as operações da API para o AWS SDK para JavaScript versão 3 (V3). 

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á.

# Configure o SDK para JavaScript
<a name="configuring-the-jssdk"></a>

Antes de usar o SDK para JavaScript invocar serviços web usando a API, você deve configurar o SDK. No mínimo, você deve configurar:
+ A AWS região na qual você solicitará serviços
+ Como seu código é autenticado com AWS

Além dessas configurações, talvez você também precise configurar permissões para os recursos da AWS . Por exemplo, limite o acesso a um bucket do Amazon S3 ou restrinja uma tabela do Amazon DynamoDB para acesso somente leitura.

O [Guia de Referência de Ferramentas AWS SDKs e Ferramentas](https://docs.aws.amazon.com/sdkref/latest/guide/) também contém configurações, recursos e outros conceitos fundamentais comuns entre muitos dos AWS SDKs. 

Os tópicos desta seção descrevem as formas de configurar o SDK JavaScript para Node.js e JavaScript executá-lo em um navegador da Web.

**Topics**
+ [Configuração por serviço](global-config-object.md)
+ [Defina a AWS região](setting-region.md)
+ [Definir credenciais](setting-credentials.md)
+ [Considerações sobre Node.js](node-js-considerations.md)
+ [Considerações sobre o script de navegador](browser-js-considerations.md)

# Configuração por serviço
<a name="global-config-object"></a>

Você pode configurar o SDK passando informações de configuração para um objeto de serviço.

A configuração em nível de serviço fornece controle significativo sobre serviços individuais, permitindo que você atualize a configuração de objetos de serviço individuais quando suas necessidades variam da configuração padrão.

**nota**  
Na versão 2.x, a configuração do AWS SDK para JavaScript serviço pode ser passada para construtores de clientes individuais. No entanto, essas configurações primeiro serão mescladas automaticamente em uma cópia da configuração global do SDK: `AWS.config`.  
Além disso, a chamada de `AWS.config.update({/* params *})` somente atualizou a configuração para clientes de serviço instanciados depois que a chamada de atualização foi feita, e não para clientes existentes.  
Esse comportamento era uma fonte frequente de confusão e dificultava a adição de configuração ao objeto global que afeta apenas um subconjunto de clientes de serviço de forma compatível com versões futuras. Na versão 3, não há mais uma configuração global gerenciada pelo SDK. A configuração deve ser transmitida para cada cliente de serviço instanciado. Ainda é possível compartilhar a mesma configuração entre vários clientes, mas essa configuração não será automaticamente mesclada com um estado global.

## Definir a configuração por serviço
<a name="service-specific-configuration"></a>

Cada serviço que você usa no SDK JavaScript é acessado por meio de um objeto de serviço que faz parte da API desse serviço. Por exemplo, para acessar o serviço Amazon S3, você cria o objeto de serviço Amazon S3. Especifique as definições de configuração específicas de um serviço como parte do construtor desse objeto de serviço. 

Por exemplo, se você precisar acessar objetos do Amazon EC2 em várias AWS regiões, crie um objeto de serviço do Amazon EC2 para cada região e, em seguida, defina a configuração regional de cada objeto de serviço adequadamente.

```
var ec2_regionA = new EC2({region: 'ap-southeast-2', maxAttempts: 15});
var ec2_regionB = new EC2({region: 'us-west-2', maxAttempts: 15});
```

# Defina a AWS região
<a name="setting-region"></a>

Uma AWS região é um conjunto nomeado de AWS recursos na mesma área geográfica. Um exemplo de uma Região é `us-east-1`, que é a Região Leste dos EUA (Norte da Virgínia). Você especifica uma região ao criar um cliente de serviço no SDK para JavaScript que o SDK acesse o serviço nessa região. Alguns serviços só estão disponíveis em regiões específicas.

O SDK do JavaScript não seleciona uma região por padrão. No entanto, você pode definir a AWS Região usando uma variável de ambiente ou um `config` arquivo de configuração compartilhado.

## Em um construtor de classes do cliente
<a name="setting-region-constructor"></a>

Ao instanciar um objeto de serviço, você pode especificar a AWS região desse recurso como parte do construtor da classe cliente, conforme mostrado aqui.

```
const s3Client = new S3.S3Client({region: 'us-west-2'});
```

## Usar uma variável de ambiente
<a name="setting-region-environment-variable"></a>

Defina a região usando a variável de ambiente `AWS_REGION`. Se você definir essa variável, o SDK para a JavaScript lê e a usa.

## Usar um arquivo config compartilhado
<a name="setting-region-config-file"></a>

Assim como o arquivo de credenciais compartilhado permite armazenar credenciais para uso pelo SDK, você pode manter sua AWS região e outras configurações em um arquivo compartilhado com o nome `config` do SDK a ser usado. Se a variável de `AWS_SDK_LOAD_CONFIG` ambiente for definida como um valor verdadeiro, o SDK JavaScript pesquisará automaticamente um `config` arquivo quando ele for carregado. Onde você salva o arquivo `config` depende do sistema operacional:
+ Usuários de Linux, macOS ou Unix: `~/.aws/config`
+ Usuários do Windows: `C:\Users\USER_NAME\.aws\config`

Se não tiver um arquivo `config` compartilhado, você poderá criar um no diretório designado. No exemplo a seguir, o arquivo `config` define a região e o formato de saída.

```
[default]
   region=us-west-2
   output=json
```

Para obter mais informações sobre como usar arquivos compartilhados `config` e `credentials` arquivos, consulte Arquivos de [configuração e credenciais compartilhados no Guia](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) de *referência de ferramentas AWS SDKs e ferramentas*.

## Ordem de precedência para definir a região
<a name="setting-region-order-of-precedence"></a>

A ordem de precedência de definição da região é a seguinte:

1. Se uma região for passada para um construtor de classe de cliente, essa região será usada.

1. Se uma região for definida na variável de ambiente, essa região será usada.

1. Caso contrário, a região definida no arquivo de configuração compartilhado será usada.

# Definir credenciais
<a name="setting-credentials"></a>

AWS usa credenciais para identificar quem está ligando para os serviços e se o acesso aos recursos solicitados é permitido. 

Seja em execução em um navegador da Web ou em um servidor Node.js, seu JavaScript código deve obter credenciais válidas antes de poder acessar os serviços por meio da API. As credenciais podem ser definidas por serviço, passando credenciais diretamente para um objeto de serviço.

Há várias maneiras de definir credenciais que diferem entre o Node.js e JavaScript nos navegadores da Web. Os tópicos nesta seção descrevem como definir credenciais em Node.js ou navegadores da web. Em cada caso, as opções são apresentadas na ordem recomendada.

## Melhores práticas para credenciais
<a name="credentials-best-practices"></a>

A definição de credenciais apropriada garante que o aplicativo ou o script de navegador possa acessar os serviços e os recursos necessários ao mesmo tempo que minimiza a exposição a problemas de segurança que possam afetar aplicativos de missão crítica ou comprometer dados confidenciais.

Um princípio importante a ser aplicado durante a definição de credenciais é sempre conceder o menor privilégio necessário para a tarefa. É mais seguro fornecer permissões mínimas nos recursos e adicionar mais permissões adicionais conforme necessário, em vez de fornecer permissões que excedam o menor privilégio e, dessa forma, precisar corrigir problemas de segurança que possam ser descobertos depois. Por exemplo, a menos que você precise ler e gravar recursos individuais, como objetos em um bucket do Amazon S3 ou uma tabela do DynamoDB, defina essas permissões como somente leitura.

Para obter mais informações sobre como conceder o privilégio mínimo, consulte a seção [Conceder privilégio mínimo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) do tópico Melhores práticas no *Guia do usuário do IAM*.

**Topics**
+ [Melhores práticas para credenciais](#credentials-best-practices)
+ [Definir credenciais no Node.js](setting-credentials-node.md)
+ [Definir credenciais em um navegador da web](setting-credentials-browser.md)

# Definir credenciais no Node.js
<a name="setting-credentials-node"></a>

Recomendamos que novos usuários que estejam se desenvolvendo localmente e que não recebam um método de autenticação do empregador se configurem Centro de Identidade do AWS IAM. Para obter mais informações, consulte [Autenticação do SDK com AWS](getting-your-credentials.md).

Há várias maneiras em Node.js de fornecer as credenciais para o SDK. Algumas dessas são mais seguras e outras oferecem mais comodidade durante o desenvolvimento de aplicativos. Ao obter credenciais em Node.js, tome cuidado ao confiar em mais de uma origem, como uma variável de ambiente e um arquivo JSON carregado. Altere as permissões em que o código é executado sem perceber a alteração que aconteceu.

AWS SDK para JavaScript A V3 fornece uma cadeia de provedores de credenciais padrão no Node.js, portanto, você não precisa fornecer um provedor de credenciais explicitamente. A [cadeia de fornecedores de credenciais](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html#credentialProviderChain) padrão tenta resolver as credenciais de várias fontes diferentes em uma determinada precedência, até que uma credencial seja retornada de uma das fontes. [Você pode encontrar a cadeia de fornecedores de credenciais do SDK for JavaScript V3 aqui.](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain)

## Cadeia de provedores de credenciais
<a name="credchain"></a>

Todos SDKs têm uma série de locais (ou fontes) que eles verificam para obter credenciais válidas para usar para fazer uma solicitação a um AWS service (Serviço da AWS). Depois que as credenciais válidas são encontradas, a pesquisa é interrompida. Essa busca sistemática é chamada de cadeia de provedores de credenciais padrão. 

Para cada etapa da cadeia, há várias maneiras de atribuir os valores. A definição de valores diretamente no código sempre tem precedência, seguida pela configuração como variáveis de ambiente e, em seguida, no AWS `config` arquivo compartilhado. Para obter mais informações, consulte [Precedência de configurações](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#precedenceOfSettings) no *Guia AWS SDKs de referência de ferramentas*. 

O *Guia de Referência de Ferramentas AWS SDKs e Ferramentas* tem informações sobre as configurações do SDK usadas por todos AWS SDKs e pelo AWS CLI. Para saber mais sobre como configurar o SDK por meio do AWS `config` arquivo compartilhado, consulte Arquivos de [configuração e credenciais compartilhados](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). Para saber mais sobre como configurar o SDK por meio da definição de variáveis de ambiente, consulte [Suporte a variáveis de ambiente](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html).

Para se autenticar AWS, ele AWS SDK para JavaScript verifica os provedores de credenciais na ordem listada na tabela a seguir.

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html)

Se você seguiu a abordagem recomendada para novos usuários começarem, configurou a autenticação do Centro de Identidade do AWS IAM durante a [Autenticação do SDK com AWS](getting-your-credentials.md) do tópico Conceitos básicos. Outros métodos de autenticação são úteis para situações diferentes. Para evitar riscos de segurança, recomendamos sempre usar credenciais de curto prazo. Para outros procedimentos de método de autenticação, consulte [Autenticação e acesso](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) no *AWS SDKs Guia de referência de ferramentas*.

Os tópicos nesta seção descrevem como carregar credenciais em Node.js.

**Topics**
+ [Cadeia de provedores de credenciais](#credchain)
+ [Carregar credenciais de perfis do IAM no Node.js para o Amazon EC2](loading-node-credentials-iam.md)
+ [Carregar credenciais de uma função do Lambda do Node.js](loading-node-credentials-lambda.md)

# Carregar credenciais de perfis do IAM no Node.js para o Amazon EC2
<a name="loading-node-credentials-iam"></a>

Se executar o aplicativo Node.js em uma instância do Amazon EC2, você poderá aproveitar perfis do IAM para o Amazon EC2 fornecer credenciais automaticamente para a instância. Se você configurar a instância para usar perfis do IAM, o SDK selecionará automaticamente as credenciais do IAM do aplicativo, eliminando a necessidade de fornecer credenciais manualmente.

Para obter mais informações sobre como adicionar perfis do IAM a uma instância do Amazon EC2, consulte [perfis do IAM para o Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html).

# Carregar credenciais de uma função do Lambda do Node.js
<a name="loading-node-credentials-lambda"></a>

Ao criar uma AWS Lambda função, você deve criar uma função especial do IAM que tenha permissão para executar a função. Essa função é chamada de *função de execução*. Ao configurar uma função do Lambda, você deve especificar o perfil do IAM que criou como a função de execução correspondente.

A função de execução fornece a função do Lambda com as credenciais de que precisa para executar e invocar outros serviços da Web. Dessa maneira, você não precisa fornecer credenciais para o código Node.js gravado em uma função do Lambda.

Para obter mais informações sobre como criar uma função de execução do Lambda, consulte [Gerenciar permissões: usar um perfil do IAM (função de execução)](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#lambda-intro-execution-role) no *Guia do desenvolvedor do AWS Lambda *.

# Definir credenciais em um navegador da web
<a name="setting-credentials-browser"></a>

Há várias maneiras de fornecer as credenciais para o SDK de scripts de navegador. Algumas dessas são mais seguras e outras oferecem mais comodidade durante o desenvolvimento de scripts.

 Aqui estão as maneiras como é possível fornecer as credenciais em ordem de recomendação:

1. Usar o Amazon Cognito Identity para autenticar usuários e fornecer credenciais

1. Usar identidade federada da web

**Atenção**  
Não recomendamos fazer uma codificação rígida das credenciais da AWS nos scripts. A codificação rígida de credenciais oferece um risco de expor o ID de chave de acesso e a chave de acesso secreta.

**Topics**
+ [Usar o Amazon Cognito Identity para autenticar usuários](loading-browser-credentials-cognito.md)

# Usar o Amazon Cognito Identity para autenticar usuários
<a name="loading-browser-credentials-cognito"></a>

A forma recomendada de obter credenciais da AWS para os scripts do seu navegador é usar o cliente de credenciais do Amazon Cognito Identity, `CognitoIdentityClient`. O Amazon Cognito permite a autenticação de usuários por meio de provedores de identidade terceirizados.

Para usar o Amazon Cognito Identity, você deve primeiro criar um banco de identidades no console do Amazon Cognito. Um grupo de identidades representa o grupo de identidades fornecido pelo aplicativo para os usuários. As identidades atribuídas a usuários identificam com exclusividade cada conta de usuário. As identidades do Amazon Cognito não são credenciais. Elas são trocadas por credenciais usando o suporte à federação de identidades da web no AWS Security Token Service (AWS STS).

O Amazon Cognito ajuda a gerenciar a abstração de identidades entre vários provedores de identidade. A identidade carregada acaba sendo trocada por credenciais no AWS STS.

## Configurar o objeto de credenciais do Amazon Cognito Identity
<a name="browser-cognito-configuration"></a>

Se você ainda não tiver criado um, crie um banco de identidades para usar com os scripts do navegador no [console do Amazon Cognito](https://console.aws.amazon.com/cognito) antes de configurar o cliente do Amazon Cognito. Crie e associe os perfis do IAM autenticados e não autenticados para o banco de identidades. Para obter mais informações, consulte [Tutorial: criação de um banco de identidades](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-identity-pool.html) no *Guia do desenvolvedor do Amazon Cognito*.

Usuários não autenticados não têm a identidade verificada, tornando esse perfil apropriado para usuários convidados de seu aplicativo ou nos casos em que não importa se os usuários têm suas identidades verificadas. Os usuários autenticados fazem login no aplicativo por meio de um provedor de identidade de terceiros que verifica as identidades. Certifique-se de definir o escopo das permissões dos recursos de forma apropriada para que você não conceda acesso a eles a partir de usuários não autenticados.

Depois de configurar um banco de identidades, use o método `fromCognitoIdentityPool` do `@aws-sdk/credential-providers` para recuperar as credenciais do banco de identidades. No exemplo a seguir de criação de um cliente do Amazon S3, substitua *AWS\$1REGION* pela região e *IDENTITY\$1POOL\$1ID* pelo ID do banco de identidades.

```
// Import required AWS SDK clients and command for Node.js
import {S3Client} from "@aws-sdk/client-s3";
import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers";

const REGION = AWS_REGION;

const s3Client = new S3Client({
  region: REGION,
  credentials: fromCognitoIdentityPool({
    clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient.
    identityPoolId: 'IDENTITY_POOL_ID',
    logins: {
            // Optional tokens, used for authenticated login.
        },
  })
});
```

A propriedade opcional `logins` é um mapa de nomes de provedor de identidade para os tokens de identidade para esses provedores. Como você obtém o token do seu provedor de identidade depende do provedor que usa. Por exemplo, se você estiver usando um grupo de usuários do Amazon Cognito como seu provedor de autenticação, poderá usar um método semelhante ao descrito abaixo.

```
// Get the Amazon Cognito ID token for the user. 'getToken()' below.
let idToken = getToken();
let COGNITO_ID = "COGNITO_ID"; // 'COGNITO_ID' has the format 'cognito-idp.REGION.amazonaws.com/COGNITO_USER_POOL_ID'
let loginData = {
  [COGNITO_ID]: idToken,
};
const s3Client = new S3Client({
    region: REGION,
    credentials: fromCognitoIdentityPool({
    clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient.
    identityPoolId: 'IDENTITY_POOL_ID',
    logins: loginData
  })
});

// Strips the token ID from the URL after authentication.
window.getToken = function () {
  var idtoken = window.location.href;
  var idtoken1 = idtoken.split("=")[1];
  var idtoken2 = idtoken1.split("&")[0];
  var idtoken3 = idtoken2.split("&")[0];
  return idtoken3;
};
```

## Alternar entre usuários não autenticados e usuários autenticados
<a name="browser-switching-unauthenticated-users"></a>

O Amazon Cognito é compatível com usuários autenticados e não autenticados. Os usuários não autenticados receberão acesso aos recursos se eles não estiverem conectados a nenhum dos provedores de identidade. Esse nível de acesso é útil para exibir conteúdo para usuários antes de fazer login. Cada usuário não autenticado tem uma identidade exclusiva no Amazon Cognito, mesmo que não tenha feito login e sido autenticado individualmente.

### Usuário não autenticado inicialmente
<a name="browser-initially-unauthenticated-user"></a>

Os usuários normalmente começam com a função não autenticada para a qual você define a propriedade de credenciais do objeto de configuração sem uma propriedade `logins`. Neste caso, suas credenciais padrão podem parecer com o seguinte:

```
// Import the required AWS SDK para JavaScript v3 modules.                   
import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers";
// Set the default credentials.
const creds = fromCognitoIdentityPool({
  identityPoolId: 'IDENTITY_POOL_ID',
  clientConfig: { region: REGION } // Configure the underlying CognitoIdentityClient.
});
```

### Mudar para usuário autenticado
<a name="switch-to-authenticated"></a>

Quando um usuário autenticado faz login em um provedor de identidade e você tem um token, é possível alternar o usuário de não autenticado para autenticado chamando uma função personalizada que atualiza o objeto de credenciais e adiciona o token `logins`.

```
// Called when an identity provider has a token for a logged in user
function userLoggedIn(providerName, token) {
  creds.params.Logins = creds.params.logins || {};
  creds.params.Logins[providerName] = token;
                    
  // Expire credentials to refresh them on the next request
  creds.expired = true;
}
```

# Considerações sobre Node.js
<a name="node-js-considerations"></a>

Embora o código Node.js seja JavaScript, o uso do AWS SDK para JavaScript em Node.js pode ser diferente do uso do SDK em scripts de navegador. Alguns métodos de API funcionam em Node.js, mas não em scripts de navegador e vice-versa. E o uso bem-sucedido de alguns APIs depende de sua familiaridade com os padrões comuns de codificação do Node.js, como importar e usar outros módulos do Node.js, como o módulo. `File System (fs)`

**nota**  
AWS recomenda usar a versão Active LTS do Node.js para desenvolvimento.

## Usar módulos integrados do Node.js
<a name="node-common-modules"></a>

Node.js oferece um conjunto de módulos integrados que é possível usar sem instalá-los. Para usar esses módulos, crie um objeto com o método `require` para especificar o nome do módulo. Por exemplo, para incluir o módulo HTTP integrado, use o seguinte.

```
import http from 'http';
```

Invoque métodos do módulo como se eles fossem métodos desse objeto. Por exemplo, aqui está o código que lê um arquivo HTML.

```
// include File System module
import fs from "fs"; 
// Invoke readFile method 
fs.readFile('index.html', function(err, data) {
  if (err) {
    throw err;
  } else {
    // Successful file read
  }
});
```

Para obter uma lista completa de todos os módulos integrados fornecidos por Node.js, consulte [Documentação do Node.js](https://nodejs.org/api/modules.html) no site do Node.js.

## Usar pacotes npm
<a name="node-npm-packages"></a>

Além dos módulos integrados, também é possível incluir e incorporar um código de terceiros de `npm`, o gerenciador de pacotes Node.js. Este é um repositório de pacotes de Node.js de código-aberto e uma interface de linha de comando para instalar esses pacotes. Para obter mais informações `npm` e uma lista dos pacotes atualmente disponíveis, consulte [ https://www.npmjs.com](https://www.npmjs.com). Você também pode aprender sobre pacotes adicionais do Node.js que você pode usar [aqui GitHub](https://github.com/sindresorhus/awesome-nodejs).

# Configurar maxSockets no Node.js
<a name="node-configuring-maxsockets"></a>

Em Node.js, defina o número máximo de conexões por origem. Se ` maxSockets` estiver definido, o cliente HTTP de baixo nível adicionará solicitações HTTP à fila e as atribuirá a soquetes à medida que forem disponibilizados.

Isso permite definir um limite máximo para o número de solicitações simultâneas para uma determinada origem por vez. Reduzir esse valor pode reduzir o número de erros de tempo limite ou de limitação recebidos. No entanto, isso também pode aumentar o uso da memória porque as solicitações serão enfileiradas até um soquete ser disponibilizado.

O exemplo a seguir mostra como definir `maxSockets` para um cliente do DynamoDB.

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import https from "https";    
let agent = new https.Agent({
  maxSockets: 25
});

let dynamodbClient = new DynamoDBClient({
  requestHandler: new NodeHttpHandler({
    requestTimeout: 3_000,
    httpsAgent: agent
  });
});
```

O SDK para JavaScript usa um `maxSockets` valor de 50 se você não fornecer um valor ou um `Agent` objeto. Se você fornecer um objeto de `Agent`, seu valor de `maxSockets` será usado. Para obter mais informações sobre como definir `maxSockets` no Node.js, consulte a [documentação do Node.js](https://nodejs.org/dist/latest/docs/api/http.html#http_agent_maxsockets).

A partir da v3.521.0 do AWS SDK para JavaScript, você pode usar a seguinte sintaxe [abreviada](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#new-in-v35210) para configurar. `requestHandler`

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({
  requestHandler: {
    requestTimeout: 3_000,
    httpsAgent: { maxSockets: 25 },
  },
});
```

# Reutilizar conexões com keep-alive no Node.js
<a name="node-reusing-connections"></a>

O HTTP/HTTPS agente Node.js padrão cria uma nova conexão TCP para cada nova solicitação. Para evitar o custo de estabelecer uma nova conexão, o AWS SDK para JavaScript reutiliza conexões TCP *por* padrão.

Para operações de curta duração, como consultas do Amazon DynamoDB, a sobrecarga de latência da configuração de uma conexão TCP pode ser maior do que a própria operação. Além disso, como a [criptografia do DynamoDB em repouso](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html) está integrada [AWS KMS](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html), você pode experimentar latências do banco de dados tendo que restabelecer AWS KMS novas entradas de cache para cada operação. 

Se não quiser reutilizar conexões TCP, você pode desabilitar com um `keepAlive` por cliente de serviço, conforme mostrado no exemplo a seguir para um cliente do DynamoDB.

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { Agent } from "https";

const dynamodbClient = new DynamoDBClient({
    requestHandler: new NodeHttpHandler({
        httpsAgent: new Agent({ keepAlive: false })
    })
});
```

Se `keepAlive` estiver habilitado, você também poderá definir o atraso inicial para pacotes TCP keep-alive com `keepAliveMsecs` que, por padrão, é 1000 ms. Consulte a [documentação do Node.js](https://nodejs.org/api/http.html#new-agentoptions) para obter detalhes.

# Configurar proxies para o Node.js
<a name="node-configuring-proxies"></a>

Se você não conseguir se conectar diretamente à Internet, o SDK para JavaScript suporta o uso de proxies HTTP ou HTTPS por meio de um agente HTTP terceirizado.

Para encontrar um agente HTTP de terceiros, pesquise por “proxy HTTP” em [npm](https://www.npmjs.com/).

Para instalar um proxy de agente HTTP de terceiros, digite o seguinte no prompt de comando, onde *PROXY* está o nome do `npm` pacote. 

```
npm install PROXY --save
```

Para usar um proxy em seu aplicativo, use as propriedades `httpAgent` e ` httpsAgent`, conforme mostrado no exemplo a seguir para um cliente do DynamoDB. 

```
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { HttpsProxyAgent } from "hpagent";
const agent = new HttpsProxyAgent({ proxy: "http://internal.proxy.com" });
const dynamodbClient = new DynamoDBClient({
    requestHandler: new NodeHttpHandler({
        httpAgent: agent,
        httpsAgent: agent
    }),
});
```

**nota**  
`httpAgent` não é o mesmo que`httpsAgent`, e como a maioria das chamadas do cliente será para `https`, ambas devem ser definidas.

# Registrar pacotes de certificados no Node.js
<a name="node-registering-certs"></a>

Os armazenamentos de confiança padrão de Node.js incluem os certificados necessários para acessar os serviços da AWS . Em alguns casos, pode ser preferível incluir apenas um conjunto específico de certificados.

Neste exemplo, um certificado específico em disco é usado para criar um ` https.Agent` que rejeita conexões, a menos que o certificado designado seja fornecido. O recém-criado `https.Agent` é então usado pelo cliente do DynamoDB.

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { Agent } from "https";
import { readFileSync } from "fs";
const certs = [readFileSync("/path/to/cert.pem")];
const agent = new Agent({
  rejectUnauthorized: true,
  ca: certs
});
const dynamodbClient = new DynamoDBClient({
  requestHandler: new NodeHttpHandler({
    httpAgent: agent,
    httpsAgent: agent
  })
});
```

# Considerações sobre o script de navegador
<a name="browser-js-considerations"></a>

Os tópicos a seguir descrevem considerações especiais sobre o uso dos scripts AWS SDK para JavaScript no navegador.

**Topics**
+ [Criar o SDK para navegadores](building-sdk-for-browsers.md)
+ [Compartilhamento de recursos de origem cruzada (CORS)](cors.md)
+ [Empacotar aplicativos com o webpack](webpack.md)

# Criar o SDK para navegadores
<a name="building-sdk-for-browsers"></a>

Ao contrário do SDK para a JavaScript versão 2 (V2), a V3 não é fornecida como um JavaScript arquivo com suporte incluído para um conjunto padrão de serviços. Em vez disso, a V3 permite agrupar e incluir no navegador somente o SDK dos JavaScript arquivos necessários, reduzindo a sobrecarga. Recomendamos usar o Webpack para agrupar o SDK necessário para JavaScript arquivos e quaisquer pacotes adicionais de terceiros necessários em um único `Javascript` arquivo e carregá-lo nos scripts do navegador usando uma tag. `<script>` Para obter mais informações sobre o Webpack, consulte [Empacotar aplicativos com o webpack](webpack.md). 

Se você trabalha com o SDK fora de um ambiente que aplica o CORS em seu navegador e deseja acessar todos os serviços fornecidos pelo SDK JavaScript, você pode criar uma cópia personalizada do SDK localmente clonando o repositório e executando as mesmas ferramentas de compilação que criam a versão hospedada padrão do SDK. As seções a seguir descrevem as etapas para compilar o SDK com serviços extras e versões da API.

## Use o SDK Builder para criar o SDK para JavaScript
<a name="using-the-sdk-builder"></a>

**nota**  
O Amazon Web Services versão 3 (V3) não é mais compatível com o Browser Builder. Para minimizar o uso da largura de banda dos aplicativos do navegador, recomendamos que você importe módulos nomeados e os empacote para reduzir o tamanho. Para obter mais informações sobre empacotamento, consulte [Empacotar aplicativos com o webpack](webpack.md).

# Compartilhamento de recursos de origem cruzada (CORS)
<a name="cors"></a>

O compartilhamento de recursos de origem cruzada, ou CORS, é um recurso de segurança de navegadores da web modernos. Isso permite que navegadores da web negociem quais domínios podem fazer solicitações de sites ou serviços externos. 

CORS é uma consideração importante durante o desenvolvimento de aplicativos de navegador com o AWS SDK para JavaScript porque a maioria das solicitações de recursos é enviada para um domínio externo, como o endpoint de um serviço da web. Se o ambiente do JavaScript impuser segurança CORS, você deverá configurar CORS com o serviço.

O CORS determina se é necessário permitir o compartilhamento de recursos em uma solicitação entre origens com base em:
+ O domínio específico que faz a solicitação 
+ O tipo de solicitação HTTP feita (GET, PUT, POST, DELETE etc.)

## Como funciona o CORS
<a name="how-cors-works"></a>

No caso mais simples, o script de navegador faz uma solicitação GET para um recurso de um servidor em outro domínio. Dependendo da configuração CORS desse servidor, se a solicitação for de um domínio autorizado para enviar solicitações GET, o servidor de origem cruzada responderá retornando o recurso solicitado.

Se o domínio solicitante ou o tipo de solicitação HTTP não estiver autorizado, a solicitação será negada. No entanto, CORS possibilita simular a solicitação antes de enviá-la efetivamente. Neste caso, uma solicitação de simulação é feita em que a operação de solicitação de acesso `OPTIONS` é enviada. Se o servidor de origem cruzada da configuração CORS conceder acesso ao domínio solicitante, o servidor reenviará uma resposta de simulação que lista todos os tipos de solicitação HTTP que o domínio solicitante pode fazer no recurso solicitado.

![\[Fluxo do processo de solicitações CORS\]](http://docs.aws.amazon.com/pt_br/sdk-for-javascript/v3/developer-guide/images/cors-overview.png)


## A configuração de CORS é obrigatória?
<a name="the-need-for-cors-configuration"></a>

Os buckets do Amazon S3 exigem a configuração de CORS para realizar operações neles. Em alguns ambientes JavaScript, o CORS talvez não seja imposto e, por isso, configurar o CORS é desnecessário. Por exemplo, se você hospedar o aplicativo de um bucket do Amazon S3 e acessar recursos de `*.s3.amazonaws.com` ou algum outro endpoint específico, as solicitações não acessarão um domínio externo. Por isso, essa configuração não exige CORS. Nesse caso, o CORS continua sendo usado em serviços que não sejam o Amazon S3.

## Configurar o CORS para um bucket do Amazon S3
<a name="configuring-cors-s3-bucket"></a>

Você pode configurar um bucket do Amazon S3 para usar o CORS no console do Amazon S3.

Se você estiver configurando o CORS no Console de Gerenciamento da AWS Web Services, use o JSON para criar uma configuração CORS. O novo Console de Gerenciamento da AWS Web Services oferece suporte somente a configurações JSON CORS. 

**Importante**  
No novo Console de Gerenciamento da AWS Web Services, a configuração CORS deve ser JSON.

1. No Console de Gerenciamento da AWS Web Services, abra o console do Amazon S3, encontre o bucket que você deseja configurar e marque sua caixa de seleção.

1. No painel que é aberto, escolha **Permissões**.

1. Na guia **Permissão**, escolha **Configuração de CORS**.

1. Digite a configuração de CORS no **Editor de configuração de CORS** e escolha **Salvar**.

A configuração do CORS é um arquivo XML que contém uma série de regras dentro de um `<CORSRule>`. Uma configuração pode ter até 100 regras. Uma regra é definida por uma das seguintes tags:
+ `<AllowedOrigin>`: especifica as origens de domínio permitidas para fazer solicitações entre domínios.
+ `<AllowedMethod>`: especifica um tipo de solicitação permitida (GET, PUT, POST, DELETE, HEAD) em solicitações entre domínios.
+ `<AllowedHeader>`: especifica os cabeçalhos permitidos em uma solicitação de comprovação.

Para exemplos de configuração, consulte [Como configurar CORS no meu bucket?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#how-do-i-enable-cors) no *Guia do usuário do Amazon Simple Storage Service*.

## Exemplo de configuração do CORS
<a name="cors-configuration-example"></a>

O exemplo de configuração do CORS a seguir permite que um usuário visualize, adicione, remova ou atualize objetos dentro de um bucket do domínio `example.org`. No entanto, recomendamos definir como escopo `<AllowedOrigin>` para o domínio do seu site. Especifique `"*"` para permitir qualquer origem.

**Importante**  
No novo console do S3, a configuração CORS deve ser JSON.

------
#### [ XML ]

```
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedOrigin>https://example.org</AllowedOrigin>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <ExposeHeader>x-amz-meta-custom-header</ExposeHeader>
  </CORSRule>
</CORSConfiguration>
```

------
#### [ JSON ]

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://www.example.org"
        ],
        "ExposeHeaders": [
             "ETag",
             "x-amz-meta-custom-header"]
    }
]
```

------

Essa configuração não autoriza o usuário para executar ações no bucket. Ela permite que o modelo de segurança do navegador faça uma solicitação ao Amazon S3. As permissões devem ser configuradas por meio de permissões do bucket ou permissões do perfil do IAM.

Use `ExposeHeader` para permitir que os cabeçalhos de resposta de leitura do SDK sejam retornados do Amazon S3. Por exemplo, para ler o cabeçalho `ETag` de um `PUT` ou de um upload de várias partes, você precisará incluir a tag `ExposeHeader` na configuração, conforme mostrado no exemplo anterior. O SDK só pode acessar cabeçalhos expostos por meio da configuração do CORS. Se você definir metadados no objeto, os valores serão retornados como cabeçalhos com o prefixo `x-amz-meta-`, como `x-amz-meta-my-custom-header`, e também deverão ser expostos da mesma maneira.

# Empacotar aplicativos com o webpack
<a name="webpack"></a>

O uso de módulos de código por aplicativos Web nos scripts do navegador ou no Node.js cria dependências. Esses módulos de código podem ter dependências próprias, o que resulta em uma coleção de módulos interligados que seu aplicativo exige para funcionar. Para gerenciar dependências, você pode usar um empacotador de módulos, como `webpack`.

O empacotador de módulos `webpack` analisa o código do seu aplicativo, procurando por instruções `import` ou `require`, para criar pacotes que contenham todos os ativos de que o seu aplicativo precisa. Isso é feito para que os ativos sejam facilmente apresentados em uma página da web. O SDK para JavaScript pode ser incluído no `webpack` como uma das dependências para incluir no pacote de saída.

Para obter mais informações sobre o `webpack`, consulte o [empacotador de módulos webpack](https://webpack.github.io/) no GitHub.

## Instalar o webpack
<a name="webpack-installing"></a>

Para instalar o empacotador de módulos `webpack`, primeiro você deve ter o npm, o gerenciador de pacotes do Node.js, instalado. Digite o comando a seguir para instalar a CLI do `webpack` e o módulo do JavaScript.

```
npm install --save-dev webpack
```

Para usar o módulo `path` para trabalhar com caminhos de arquivos e diretórios, que são instalados automaticamente com o webpack, talvez seja necessário instalar o pacote `path-browserify` do Node.js. 

```
npm install --save-dev path-browserify
```

## Configurar o webpack
<a name="webpack-configuring"></a>

Por padrão, o Webpack busca por um arquivo JavaScript chamado `webpack.config.js` no diretório raiz do projeto. Esse arquivo especifica as opções de configuração. Veja a seguir um exemplo de um arquivo de configuração `webpack.config.js` para o WebPack versão 5.0.0 e posterior.

**nota**  
Os requisitos de configuração do Webpack variam dependendo da versão do Webpack que você instala. Para obter mais informações, consulte a [documentação do Webpack](https://webpack.js.org/configuration/). 

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
  }
  /**
  * In Webpack version v2.0.0 and earlier, you must tell 
  * webpack how to use "json-loader" to load 'json' files.
  * To do this Enter 'npm --save-dev install json-loader' at the 
  * command line to install the "json-loader' package, and include the 
  * following entry in your webpack.config.js.
  * module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```

Neste exemplo, `browser.js` é especificado como *ponto de entrada*. O *ponto de entrada* é o arquivo que o `webpack` usa para iniciar a pesquisa por módulos importados. O nome do arquivo da saída é especificado como `bundle.js`. Esse arquivo de saída conterá tudo do JavaScript de que o aplicativo precisa para ser executado. Se o código especificado no ponto de entrada importar ou exigir outros módulos, como o SDK para JavaScript, esse código será incluído sem a necessidade de especificá-lo na configuração.

## Executar o webpack
<a name="webpack-running"></a>

Para criar um aplicativo para usar o `webpack`, adicione o seguinte ao objeto `scripts` no seu arquivo `package.json`.

```
"build": "webpack"
```

Veja a seguir um exemplo de arquivo `package.json` que demonstra a adição do `webpack`.

```
{
  "name": "aws-webpack",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "webpack"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@aws-sdk/client-iam": "^3.32.0",
    "@aws-sdk/client-s3": "^3.32.0"
  },
  "devDependencies": {
    "webpack": "^5.0.0"
  }
}
```

Para criar seu aplicativo, digite o comando a seguir.

```
npm run build
```

O empacotador de módulos `webpack` gera o arquivo JavaScript que você especificou no diretório raiz do projeto.

## Usar o pacote do webpack
<a name="webpack-using-bundle"></a>

Para usar o pacote no script de um navegador, você pode incorporar o pacote usando uma tag `<script>`, conforme mostrado no exemplo a seguir.

```
<!DOCTYPE html>
<html>
    <head>
        <title>Amazon SDK with webpack</title>
    </head> 
    <body>
        <div id="list"></div>
        <script src="bundle.js"></script>
    </body>
</html>
```

## Empacotar para o Node.js
<a name="webpack-nodejs-bundles"></a>

Você pode usar o `webpack` para gerar pacotes executados no Node.js especificando `node` como um destino na configuração.

```
target: "node"
```

Isso é útil ao executar um aplicativo do Node.js em um ambiente no qual o espaço em disco é limitado. Aqui está um exemplo de configuração do `webpack.config.js` com o Node.js especificado como o destino de saída.

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
  // Let webpack know to generate a Node.js bundle.
  target: "node",
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
   /**
   * In Webpack version v2.0.0 and earlier, you must tell 
   * webpack how to use "json-loader" to load 'json' files.
   * To do this Enter 'npm --save-dev install json-loader' at the 
   * command line to install the "json-loader' package, and include the 
   * following entry in your webpack.config.js.
   module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```