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

# 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"}]
  }
  **/
};
```