O AWS SDK para JavaScript v2 chegou ao fim do suporte. Recomendamos migrar para o [AWS SDK para JavaScript v3](https://docs.aws.amazon.com//sdk-for-javascript/v3/developer-guide/). Para ver detalhes e informações sobre como migrar, consulte este [anúncio](https://aws.amazon.com/blogs//developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/).
# Usar serviços no SDK da para JavaScript
O AWS SDK para JavaScript dá acesso aos serviços a que oferece suporte por meio de uma série de classes de clientes. Com base nessas classes de clientes, você cria objetos de interface de serviço, comumente chamados de *objetos de serviço*. Cada serviço compatível da AWS tem uma ou mais classes de clientes que oferecem APIs de baixo nível para uso dos recursos de serviço. Por exemplo: as APIs do Amazon DynamoDB estão disponíveis por meio da classe `AWS.DynamoDB`.
Os serviços expostos por meio do SDK para JavaScript seguem o padrão solicitação-resposta para trocar mensagens com aplicativos de chamada. Neste padrão, o código que invoca um serviço envia uma solicitação HTTP/HTTPS a um endpoint para o serviço. A solicitação contém os parâmetros necessários para invocar com sucesso o recurso específico que está sendo chamado. O serviço que é invocado gera uma resposta, que é enviada de volta ao solicitante. A resposta contém dados, caso a operação tenha tido sucesso, ou informações de erro, caso a operação não tenha tido sucesso.
![\[O padrão do serviço de resposta a solicitações da AWS.\]](http://docs.aws.amazon.com/pt_br/sdk-for-javascript/v2/developer-guide/images/request-response.png)
Invocar um serviço da AWS inclui todo o ciclo de vida de solicitação e resposta de uma operação em um objeto de serviço, incluindo quaisquer novas tentativas. A solicitação é encapsulada no SDK pelo objeto `AWS.Request`. A resposta está encapsulada no SDK pelo objeto `AWS.Response`, que é fornecido ao solicitante por meio de uma das várias técnicas, como uma função de retorno de chamada ou uma promessa do JavaScript.
**Topics**
+ [Criar e chamar objetos de serviço](creating-and-calling-service-objects.md)
+ [Registrar em log as chamadas a AWS SDK para JavaScript](logging-sdk-calls.md)
+ [Chamar serviços assincronamente](calling-services-asynchronously.md)
+ [Usar o objeto de resposta](the-response-object.md)
+ [Trabalhar com o JSON](working-with-json.md)
+ [Estratégia de repetição no AWS SDK para JavaScript v2](retry-strategy.md)
# Criar e chamar objetos de serviço
A API JavaScript oferece suporte para a maioria dos serviços da AWS disponíveis. Cada classe de serviço na API JavaScript fornece acesso a cada chamada de API em seu serviço. Para obter mais informações sobre classes de serviço, operações e parâmetros na API JavaScript, consulte a [referência da API](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html).
Ao usar o SDK em Node.js, você adiciona o pacote do SDK para seu aplicativo usando `require`, que fornece suporte a todos os serviços atuais.
```
var AWS = require('aws-sdk');
```
Ao usar o SDK com o JavaScript do navegador, você carrega o pacote do SDK para os scripts do navegador usando o pacote do SDK hospedado pela AWS. Para carregar o pacote do SDK, adicione o seguinte elemento `
```
[Para encontrar o SDK\$1VERSION\$1NUMBER atual, consulte a Referência da API para o SDK para JavaScript no Guia de referência da API. AWS SDK para JavaScript](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/)
O pacote do SDK hospedado padrão oferece suporte a um subconjunto dos serviços da AWS disponíveis. Para obter uma lista dos serviços padrão no pacote do SDK hospedado para o navegador, consulte [Serviços compatíveis](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/#Supported_Services) na Referência de API. Você poderá usar o SDK com outros serviços se a verificação de segurança do CORS estiver desabilitada. Nesse caso, você pode criar uma versão personalizada do SDK para incluir os serviços adicionais de que precisa. Para obter mais informações sobre a criação de uma versão personalizada do SDK, consulte [Criar o SDK para navegadores](building-sdk-for-browsers.md).
## Exigir serviços individuais
Exigir o SDK para JavaScript, como mostrado anteriormente, inclui todo o SDK no seu código. Como alternativa, você pode optar por solicitar apenas os serviços individuais usados pelo seu código. Considere o código a seguir usado para criar um objeto de serviço do Amazon S3.
```
// Import the AWS SDK
var AWS = require('aws-sdk');
// Set credentials and Region
// This can also be done directly on the service client
AWS.config.update({region: 'us-west-1', credentials: {YOUR_CREDENTIALS}});
var s3 = new AWS.S3({apiVersion: '2006-03-01'});
```
No exemplo anterior, a função `require` especifica todo o SDK. A quantidade de código para transporte pela rede, bem como a sobrecarga de memória do seu código, seriam substancialmente menores se for incluída apenas a parte do SDK de que você precisa para o serviço do Amazon S3. Para exigir um serviço individual, chame a função `require`, conforme mostrado, incluindo o construtor do serviço, com todas as letras minúsculas.
```
require('aws-sdk/clients/SERVICE');
```
Veja como é o código para criar o objeto de serviço do Amazon S3 quando inclui apenas a parte do SDK referente ao Amazon S3.
```
// Import the Amazon S3 service client
var S3 = require('aws-sdk/clients/s3');
// Set credentials and Region
var s3 = new S3({
apiVersion: '2006-03-01',
region: 'us-west-1',
credentials: {YOUR_CREDENTIALS}
});
```
Você ainda pode acessar o namespace global da AWS sem todos os serviços anexados a ele.
```
require('aws-sdk/global');
```
Essa é uma técnica útil ao aplicar a mesma configuração em vários serviços individuais para, por exemplo, fornecer as mesmas credenciais a todos os serviços. Exigir serviços individuais deve reduzir o tempo de carregamento e o consumo de memória em Node.js. Quando feito juntamente com uma ferramenta de empacotamento, como Browserify ou webpack, exigir serviços individuais faz com que o SDK tenha uma fração do tamanho total. Isso ajuda com ambientes com restrição de memória ou espaço em disco, como um dispositivo com IoT ou uma função do Lambda.
## Criar objetos de serviço
Para acessar recursos de serviços por meio da API JavaScript, primeiro você deve criar um *objeto de serviço* e, por meio dele, acessar uma série de recursos fornecidos pela classe de cliente subjacente. Em geral, há uma classe de cliente para cada serviço. No entanto, alguns serviços dividem o acesso a seus recursos entre várias classes de cliente.
Para usar um recurso, você deve criar uma instância da classe que fornece acesso a ele. O exemplo a seguir mostra como criar um objeto de serviço para o DynamoDB a partir da classe de cliente do `AWS.DynamoDB`.
```
var dynamodb = new AWS.DynamoDB({apiVersion: '2012-08-10'});
```
Por padrão, o objeto de serviço vem configurado com as configurações globais também usadas para configurar o SDK. No entanto, você pode configurar o objeto de serviço com dados de configuração do tempo de execução específicos desse objeto de serviço. Dados de configuração específicos do serviço são aplicados após a aplicação das configurações globais.
No exemplo a seguir, um objeto de serviço do Amazon EC2 é criado com a configuração de uma região específica, mas usando a configuração global.
```
var ec2 = new AWS.EC2({region: 'us-west-2', apiVersion: '2014-10-01'});
```
Além de oferecer suporte a configurações específicas do serviço aplicadas a um objeto de serviço individual, você também pode aplicar configurações específicas do serviço a todos os objetos de serviço recém-criados de uma determinada classe. Por exemplo, para configurar todos os objetos de serviço criados com base na classe Amazon EC2 para usar a região (`us-west-2`) Oeste dos EUA (Oregon), adicione o seguinte ao objeto de configuração global `AWS.config`.
```
AWS.config.ec2 = {region: 'us-west-2', apiVersion: '2016-04-01'};
```
## Bloquear a versão da API de um objeto de serviço
Você pode bloquear um objeto de serviço para usar uma determinada versão da API de um serviço ao especificar a opção `apiVersion` quando for criar o objeto. No exemplo a seguir, é criado um objeto de serviço do DynamoDB e ele está bloqueado para uma determinada versão da API.
```
var dynamodb = new AWS.DynamoDB({apiVersion: '2011-12-05'});
```
Para obter mais informações sobre como bloquear a versão da API de um objeto de serviço, consulte [Bloquear versões de API](locking-api-versions.md).
## Especificar os parâmetros do objeto de serviço
Ao chamar um método de um objeto de serviço, passe os parâmetros em JSON, conforme exigido pela API. Por exemplo, no Amazon S3, para obter um objeto para bucket e chave especificados, passe os seguintes parâmetros para o método . Para obter mais informações sobre como passar os parâmetros JSON, consulte [Trabalhar com o JSON](working-with-json.md).
```
s3.getObject({Bucket: 'bucketName', Key: 'keyName'});
```
Para obter mais informações sobre parâmetros do Amazon S3, consulte [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html) na Referência a APIs.
Além disso, você pode vincular valores a parâmetros individuais ao criar um objeto de serviço usando o parâmetro `params`. O valor do parâmetro `params` de objetos de serviço é um mapa que especifica um ou mais dos valores de parâmetro definidos pelo objeto de serviço. O exemplo a seguir mostra o parâmetro `Bucket` de um objeto de serviço do que está sendo vinculado a um bucket chamado `amzn-s3-demo-bucket`.
```
var s3bucket = new AWS.S3({params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });
```
Ao vincular o objeto de serviço a um bucket, o objeto de serviço `s3bucket` trata o valor do parâmetro `amzn-s3-demo-bucket` como padrão, que não precisa mais ser especificado para operações subsequentes. Quaisquer valores de parâmetro vinculados são ignorados ao usar o objeto para operações em que o valor do parâmetro não é aplicável. Você pode substituir esse parâmetro vinculado ao fazer chamadas no objeto de serviço, para tanto especificando um novo valor.
```
var s3bucket = new AWS.S3({ params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });
s3bucket.getObject({Key: 'keyName'});
// ...
s3bucket.getObject({Bucket: 'amzn-s3-demo-bucket3', Key: 'keyOtherName'});
```
Detalhes sobre os parâmetros disponíveis para cada método são encontrados na referência da API.
# Registrar em log as chamadas a AWS SDK para JavaScript
O AWS SDK para JavaScript é instrumentado com um registrador integrado para que você possa registrar chamadas de API feitas com o SDK para JavaScript.
Para ativar o registrador e imprimir entradas de log no console, adicione a instrução a seguir ao seu código.
```
AWS.config.logger = console;
```
Aqui está um exemplo da saída do log.
```
[AWS s3 200 0.185s 0 retries] createMultipartUpload({ Bucket: 'amzn-s3-demo-logging-bucket', Key: 'issues_1704' })
```
## Usar um registrador de terceiros
Você também pode usar um registrador de terceiros, desde que tenha as operações `log()` ou `write()` para gravar em um arquivo de log ou servidor. Você deve instalar e configurar o registrador personalizado de acordo com as instruções, para que possa usá-lo com o JavaScript.
Um registrador que você pode usar em scripts do navegador ou em Node.js é o logplease. No Node.js, você pode configurar o logplease para gravar entradas em um arquivo de log. Você também pode usá-lo com o webpack.
Ao usar um registrador de terceiros, defina todas as opções antes de atribuir o logger ao `AWS.Config.logger`. Por exemplo, a seguir está especificado um arquivo de log externo e definido o nível de log para logplease
```
// Require AWS Node.js SDK
const AWS = require('aws-sdk')
// Require logplease
const logplease = require('logplease');
// Set external log file option
logplease.setLogfile('debug.log');
// Set log level
logplease.setLogLevel('DEBUG');
// Create logger
const logger = logplease.create('logger name');
// Assign logger to SDK
AWS.config.logger = logger;
```
Para obter mais informações sobre o logplease, consulte [registrador logplease simples do logplease](https://github.com/haadcode/logplease) no GitHub.
# Chamar serviços assincronamente
Todas as solicitações feitas por meio do SDK são assíncronas. É importante ter isso em mente ao gravar scripts do navegador. O JavaScript executado em um navegador normalmente tem apenas um único thread de execução. Depois de fazer uma chamada assíncrona para um serviço da AWS, o script do navegador continua em execução e, nesse processo, pode tentar executar um código que depende do resultado assíncrono antes que tenha retorno.
Fazer chamadas assíncronas para gerenciar um serviço da AWS inclui gerenciar essas chamadas para que seu código não tente usar dados antes de serem disponibilizados. Os tópicos desta seção explicam a necessidade de gerenciar chamadas assíncronas e detalha diferentes técnicas que você pode usar para gerenciá-las.
**Topics**
+ [Gerenciar chamadas assíncronas](making-asynchronous-calls.md)
+ [Usar uma função de retorno de chamada anônimo](using-a-callback-function.md)
+ [Usar um listener de evento do objeto de solicitação](using-a-response-event-handler.md)
+ [Usar async/await](using-async-await.md)
+ [Usar as promessas do JavaScript](using-promises.md)
# Gerenciar chamadas assíncronas
Por exemplo, a página inicial de um site de comércio eletrônico permite que os clientes que retornam façam login. Parte do benefício para os clientes que fazem login é que, depois de fazerem-no, o site se personaliza de acordo com suas preferências específicas. Para fazer isso acontecer:
1. O cliente deve fazer login e ser validado com suas credenciais de login.
1. As preferências do cliente são solicitadas a banco de dados de clientes.
1. O banco de dados fornece as preferências do cliente, que são usadas para personalizar o site antes que a página carregue.
Se essas tarefas forem executadas de forma síncrona, cada uma delas deverá terminar antes de a seguinte começar. A página da web não terminaria de carregar até que as preferências do cliente fossem apresentadas pelo banco de dados. No entanto, após a consulta de banco de dados ser enviada ao servidor, o recebimento dos dados do cliente pode ser atrasado ou até mesmo falhar devido a gargalos da rede, tráfego excepcionalmente alto no banco de dados ou conexão ruim nos dispositivos móveis.
Para evitar que o site congele sob essas condições, chame o banco de dados de forma assíncrona. Depois de a chamada do banco de dados ser executada, enviando sua solicitação assíncrona, o código continuará a ser executado conforme o esperado. Se você não gerir adequadamente a resposta de uma chamada assíncrona, o código poderá tentar usar informações que espera de volta do banco de dados quando esses dados ainda não estiverem disponíveis.
![\[Mostrando a diferença entre a execução síncrona e a execução assíncrona.\]](http://docs.aws.amazon.com/pt_br/sdk-for-javascript/v2/developer-guide/images/async-vs-sync.png)
# Usar uma função de retorno de chamada anônimo
Cada método de objeto de serviço que cria um objeto `AWS.Request` pode aceitar uma função de retorno de chamada anônimo como último parâmetro. A assinatura dessa função de retorno de chamada é:
```
function(error, data) {
// callback handling code
}
```
Essa função de retorno de chamada é executada ao se retornar uma resposta bem-sucedida ou dados de erro. Se a chamada do método for bem-sucedida, o conteúdo da resposta estará disponível para a função de retorno de chamada no parâmetro `data`. Se a chamada não for bem-sucedida, os detalhes sobre a falha são fornecidos no parâmetro `error`.
Normalmente o código dentro da função de retorno de chamada testa um erro, que ele processa, caso seja retornado um erro. Se o erro não for retornado, o código recuperará os dados na resposta pelo parâmetro `data`. O formato básico da função de retorno de chamada é semelhante a este exemplo.
```
function(error, data) {
if (error) {
// error handling code
console.log(error);
} else {
// data handling code
console.log(data);
}
}
```
No exemplo anterior, os detalhes do erro ou dos dados retornados são registrados no console. Veja a seguir um exemplo que mostra uma função de retorno de chamada passada como parte da chamada de um método em um objeto de serviço.
```
new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) {
if (error) {
console.log(error); // an error occurred
} else {
console.log(data); // request succeeded
}
});
```
## Acessar os objetos de solicitação e resposta
Dentro da função de retorno de chamada, a palavra-chave `this` do JavaScript refere-se ao objeto `AWS.Response` subjacente à maioria dos serviços. No exemplo a seguir, a propriedade `httpResponse` de um objeto `AWS.Response` é usada dentro de uma função de retorno de chamada para registrar os dados de resposta brutos e os cabeçalhos para ajudar com a depuração.
```
new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) {
if (error) {
console.log(error); // an error occurred
// Using this keyword to access AWS.Response object and properties
console.log("Response data and headers: " + JSON.stringify(this.httpResponse));
} else {
console.log(data); // request succeeded
}
});
```
Além disso, como o objeto `AWS.Response` tem uma propriedade `Request` que contém o `AWS.Request` enviado pela chamada do método original, você também pode acessar os detalhes da solicitação que foi feita.
# Usar um listener de evento do objeto de solicitação
Se você não criar e passar uma função de retorno de chamada anônimo como parâmetro quando chamar o método de objeto de um serviço, a chamada do método gera um objeto `AWS.Request`, que deve ser enviado manualmente usando o método `send`.
Para processar a resposta, você deve criar um listener de evento para o objeto `AWS.Request` para registrar uma função de retorno de chamada para a chamada do método. O exemplo a seguir mostra como criar o objeto `AWS.Request` para chamar um método de objeto de serviço e o listener do evento para uma devolução bem-sucedida.
```
// create the AWS.Request object
var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances();
// register a callback event handler
request.on('success', function(response) {
// log the successful data response
console.log(response.data);
});
// send the request
request.send();
```
Depois de chamado o método `send` no objeto `AWS.Request`, o manipulador de eventos é executado quando o objeto de serviço recebe um objeto `AWS.Response`.
Para obter mais informações sobre o objeto `AWS.Request`, consulte [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) na Referência de API. Para obter mais informações sobre o objeto `AWS.Response`, consulte [Usar o objeto de resposta](the-response-object.md) ou [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html) na Referência de API.
## Encadear vários retornos de chamada
Você pode registrar vários retornos de chamada em qualquer objeto de solicitação. É possível registrar vários retornos de chamada para diferentes eventos ou para o mesmo evento. Além disso, você pode encadear retornos de chamada conforme exibido no exemplo a seguir.
```
request.
on('success', function(response) {
console.log("Success!");
}).
on('error', function(response) {
console.log("Error!");
}).
on('complete', function() {
console.log("Always!");
}).
send();
```
## Eventos de conclusão do objeto de solicitação
O objeto `AWS.Request` gera esses eventos de conclusão com base na resposta de cada método de operação de serviço:
+ `success`
+ `error`
+ `complete`
Você pode registrar uma função de retorno de chamada em resposta a qualquer um desses eventos. Para obter uma lista completa de todos os eventos de objeto da solicitação, consulte [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) na Referência da API.
### O evento "success"
O evento `success` é gerado após uma resposta bem-sucedida recebida do objeto de serviço. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('success', function(response) {
// event handler code
});
```
A resposta fornece uma propriedade `data`, que contém os dados de resposta serializada do serviço. Por exemplo, a chamada a seguir para o método `listBuckets` do objeto de serviço do Amazon S3.
```
s3.listBuckets.on('success', function(response) {
console.log(response.data);
}).send();
```
retorna a resposta e imprime os conteúdos da propriedade `data` a seguir no console.
```
{ Owner: { ID: '...', DisplayName: '...' },
Buckets:
[ { Name: 'someBucketName', CreationDate: someCreationDate },
{ Name: 'otherBucketName', CreationDate: otherCreationDate } ],
RequestId: '...' }
```
### O evento "error"
O evento `error` é gerado após uma resposta de erro recebida do objeto de serviço. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('error', function(error, response) {
// event handling code
});
```
Quando o evento `error` é gerado, o valor da propriedade `data` da resposta é `null` e a propriedade `error` contém os dados do erro. O objeto `error` associado é passado como o primeiro parâmetro para a função de retorno de chamada registrada. Por exemplo, o seguinte código:
```
s3.config.credentials.accessKeyId = 'invalid';
s3.listBuckets().on('error', function(error, response) {
console.log(error);
}).send();
```
retorna o erro e imprime os seguintes dados de erro no console.
```
{ code: 'Forbidden', message: null }
```
### O evento "complete"
O evento `complete` é gerado quando uma chamada de objeto de serviço tiver sido concluída, independentemente de ela resultar em sucesso ou erro. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('complete', function(response) {
// event handler code
});
```
Use o retorno de chamada do evento `complete` para lidar com qualquer limpeza de solicitação que precise executar, independentemente de sucesso ou erro. Se você usar dados de resposta dentro de um retorno de chamada para o evento `complete`, primeiro verifique as propriedades `response.data` ou `response.error` para depois tentar acessar qualquer uma delas, conforme mostrado no exemplo a seguir.
```
request.on('complete', function(response) {
if (response.error) {
// an error occurred, handle it
} else {
// we can use response.data here
}
}).send();
```
## Eventos HTTP do objeto da solicitação
O objeto `AWS.Request` gera esses eventos HTTP com base na resposta de cada método de operação de serviço:
+ `httpHeaders`
+ `httpData`
+ `httpUploadProgress`
+ `httpDownloadProgress`
+ `httpError`
+ `httpDone`
Você pode registrar uma função de retorno de chamada em resposta a qualquer um desses eventos. Para obter uma lista completa de todos os eventos de objeto da solicitação, consulte [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) na Referência da API.
### O evento "httpHeaders"
O evento `httpHeaders` é gerado quando cabeçalhos são enviados pelo servidor remoto. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('httpHeaders', function(statusCode, headers, response) {
// event handling code
});
```
O parâmetro `statusCode` para a função de retorno de chamada é o código de status HTTP. O parâmetro `headers` contém os cabeçalhos de resposta.
### O evento "httpData"
O evento `httpData` é gerado para transmitir pacotes de dados de resposta do serviço. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('httpData', function(chunk, response) {
// event handling code
});
```
Esse evento é normalmente usado para receber grandes respostas em blocos quando não for prático carregar toda a resposta na memória. Esse evento tem um parâmetro `chunk` adicional que contém uma parte dos dados reais do servidor.
Se você registrar um retorno de chamada para o evento `httpData`, a propriedade `data` da resposta contém toda a saída serializada para a solicitação. Você deve remover o listener `httpData` padrão se você não tiver custos indiretos de memória e análise sintática adicional para os handlers incorporados.
### Os eventos "httpUploadProgress" e "httpDownloadProgress"
O evento `httpUploadProgress` é gerado quando a solicitação HTTP tiver carregado mais dados. Da mesma forma, o evento `httpDownloadProgress` é gerado quando a solicitação HTTP tiver baixado mais dados. Veja aqui como registrar uma função de retorno de chamada para esses eventos.
```
request.on('httpUploadProgress', function(progress, response) {
// event handling code
})
.on('httpDownloadProgress', function(progress, response) {
// event handling code
});
```
O parâmetro `progress` para a função de retorno de chamada contém um objeto com os bytes carregados e totais da solicitação.
### O evento "httpError"
O evento `httpError` é gerado quando a solicitação HTTP falhar. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('httpError', function(error, response) {
// event handling code
});
```
O parâmetro `error` para a função de retorno de chamada contém o erro que foi lançado.
### O evento "httpDone"
O evento `httpDone` é gerado quando o servidor terminar de enviar dados. Veja aqui como registrar uma função de retorno de chamada para esse evento.
```
request.on('httpDone', function(response) {
// event handling code
});
```
# Usar async/await
Você pode usar o `async/await` padrão em suas chamadas para o AWS SDK para JavaScript. A maioria das funções que recebem um retorno de chamada não retorna uma promessa. Como você usa apenas funções do `await` que retornam uma promessa, para usar o padrão de `async/await`, você precisa encadear o método de `.promise()` até o final da chamada e remover o retorno de chamada.
O exemplo a seguir usa async/await para listar todas as tabelas do Amazon DynamoDB em `us-west-2`
```
var AWS = require("aws-sdk");
//Create an Amazon DynamoDB client service object.
dbClient = new AWS.DynamoDB({ region: "us-west-2" });
// Call DynamoDB to list existing tables
const run = async () => {
try {
const results = await dbClient.listTables({}).promise();
console.log(results.TableNames.join("\n"));
} catch (err) {
console.error(err);
}
};
run();
```
**nota**
Nem todos os navegadores oferecem suporte para async/await. Consulte [Funções assíncronas](https://caniuse.com/#feat=async-functions) para obter uma lista de navegadores com suporte para async/await.
# Usar as promessas do JavaScript
O método `AWS.Request.promise` fornece uma maneira de chamar uma operação de serviço assíncrona e gerenciar o fluxo em vez de usar retornos de chamada. No Node.js e nos scripts do navegador, um objeto `AWS.Request` é retornado quando a operação de serviço é chamada sem uma função de retorno de chamada. Você pode chamar o método `send` da solicitação para fazer a chamada de serviço.
No entanto, o `AWS.Request.promise` imediatamente começa a chamada de serviço e retorna uma promessa que é cumprida com a propriedade `data` da resposta ou rejeitada com a propriedade `error` da resposta.
```
var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances();
// create the promise object
var promise = request.promise();
// handle promise's fulfilled/rejected states
promise.then(
function(data) {
/* process the data */
},
function(error) {
/* handle the error */
}
);
```
O exemplo a seguir retorna uma promessa que é atendida com um objeto `data` ou rejeitada com um objeto `error`. Usando promessas, um único retorno de chamada não é responsável por detectar erros. Em vez disso, o retorno de chamada correto é chamado com base no sucesso ou na falha de uma solicitação.
```
var s3 = new AWS.S3({apiVersion: '2006-03-01', region: 'us-west-2'});
var params = {
Bucket: 'bucket',
Key: 'example2.txt',
Body: 'Uploaded text using the promise-based method!'
};
var putObjectPromise = s3.putObject(params).promise();
putObjectPromise.then(function(data) {
console.log('Success');
}).catch(function(err) {
console.log(err);
});
```
## Coordenar várias promessas
Em algumas situações, seu código deve fazer várias chamadas assíncronas que exigem ação somente quando todos tiverem sido retornados com êxito. Se você gerenciar as chamadas individuais do método assíncrono com promessas, pode criar uma promessa adicional que usa o método `all`. Esse método cumpre essa promessa generalista se, e quando, a série de promessas que você passar para o método forem cumpridas. A função de retorno de chamada é transmitida a um array dos valores das promessas passadas para o método `all`.
No exemplo a seguir, uma função do AWS Lambda deve fazer três chamadas assíncronas para Amazon DynamoDB, mas só pode ser concluída após as promessas para cada chamada serem cumpridas.
```
Promise.all([firstPromise, secondPromise, thirdPromise]).then(function(values) {
console.log("Value 0 is " + values[0].toString);
console.log("Value 1 is " + values[1].toString);
console.log("Value 2 is " + values[2].toString);
// return the result to the caller of the Lambda function
callback(null, values);
});
```
## Suporte de navegador e Node.js para promessas
O suporte para promessas de JavaScript nativo (ECMAScript 2015) depende do mecanismo JavaScript e da versão em que seu código é executado. Para ajudar a determinar o suporte para promessas de JavaScript em cada ambiente onde seu código precisa rodar, consulte a [Tabela Compatibilidade de ECMAScript](https://compat-table.github.io/compat-table/es6/) no GitHub.
## Usando outras implementações de promessa
Além da implementação de promessa nativa no ECMAScript 2015, você também pode usar bibliotecas de promessa de terceiros, incluindo:
+ [bluebird](http://bluebirdjs.com)
+ [RSVP](https://github.com/tildeio/rsvp.js/)
+ [P](https://github.com/kriskowal/q)
Essas bibliotecas de promessa opcionais podem ser úteis se você precisar que seu código rode em ambientes que não são compatíveis com a implementação de promessa nativa no ECMAScript 5 e no ECMAScript 2015.
Para usar uma biblioteca de promessa de terceiros, defina uma dependência de promessas no SDK chamando o método `setPromisesDependency` do objeto de configuração global. No navegador de scripts, carregue a biblioteca de promessas de terceiros antes de carregar o SDK. No exemplo a seguir, o SDK é configurado para usar a implementação na biblioteca de promessas do bluebird.
```
AWS.config.setPromisesDependency(require('bluebird'));
```
Para voltar a usar a implementação de promessa nativa do mecanismo JavaScript, chame `setPromisesDependency` novamente, passando um `null` em vez do nome de uma biblioteca.
# Usar o objeto de resposta
Depois de um método de objeto de serviço ser chamado, ele retornará um objeto `AWS.Response` passando para sua função de retorno de chamada. Você pode acessar o conteúdo da resposta usando as propriedades do objeto `AWS.Response`. Existem duas propriedades do objeto `AWS.Response` que você usa para acessar o conteúdo da resposta:
+ `data`Propriedade da
+ `error`Propriedade da
Ao usar o mecanismo de retorno de chamada padrão, essas duas propriedades serão fornecidas como parâmetros na função de retorno de chamada anônimo, conforme mostrado no exemplo a seguir.
```
function(error, data) {
if (error) {
// error handling code
console.log(error);
} else {
// data handling code
console.log(data);
}
}
```
## Acessar dados retornados no objeto de resposta
A propriedade `data` do objeto `AWS.Response` contém os dados serializados retornados pela solicitação de serviço. Quando a solicitação for bem-sucedida, a propriedade `data` conterá um objeto com um mapa para os dados retornados. A propriedade `data` pode ser nula, caso ocorra um erro.
Aqui está um exemplo de como chamar o método `getItem` de uma tabela do DynamoDB para recuperar o nome do arquivo de um arquivo de imagem para usar como parte de um jogo.
```
// Initialize parameters needed to call DynamoDB
var slotParams = {
Key : {'slotPosition' : {N: '0'}},
TableName : 'slotWheels',
ProjectionExpression: 'imageFile'
};
// prepare request object for call to DynamoDB
var request = new AWS.DynamoDB({region: 'us-west-2', apiVersion: '2012-08-10'}).getItem(slotParams);
// log the name of the image file to load in the slot machine
request.on('success', function(response) {
// logs a value like "cherries.jpg" returned from DynamoDB
console.log(response.data.Item.imageFile.S);
});
// submit DynamoDB request
request.send();
```
Para este exemplo, a tabela do DynamoDB é uma pesquisa de imagens que mostram os resultados de uma máquina caça-níqueis conforme especificado pelos parâmetros em `slotParams`.
Após uma chamada bem-sucedida do método `getItem`, a propriedade `data` do objeto `AWS.Response` conterá um objeto `Item` retornado por DynamoDB. Os dados retornados são acessados de acordo com o parâmetro `ProjectionExpression` da solicitação, que neste caso significa o membro `imageFile` do objeto `Item`. Como o membro `imageFile` contém um valor de string, você acessa o nome do arquivo da imagem em si por meio do valor do membro-filho de `S` de `imageFile`.
## Paginar pelos dados retornados
Às vezes, o conteúdo da propriedade `data` retornada por uma solicitação de serviço abrange várias páginas. Você pode acessar a próxima página de dados chamando o método `response.nextPage`. Esse método envia uma nova solicitação. A resposta da solicitação pode ser capturada com um retorno de chamada ou com listeners de sucesso e erro.
Você pode verificar se os dados retornados por uma solicitação de serviço têm páginas adicionais de dados chamando o método `response.hasNextPage`. Esse método retorna um valor booleano para indicar se a chamada `response.nextPage` retorna dados adicionais.
```
s3.listObjects({Bucket: 'bucket'}).on('success', function handlePage(response) {
// do something with response.data
if (response.hasNextPage()) {
response.nextPage().on('success', handlePage).send();
}
}).send();
```
## Acessar informações de erro de um objeto de resposta
A propriedade `error` do objeto `AWS.Response` contém os dados de erro disponíveis no caso de um erro de serviço ou de transferência. O erro retornado assume a forma a seguir.
```
{ code: 'SHORT_UNIQUE_ERROR_CODE', message: 'a descriptive error message' }
```
No caso de um erro, o valor da propriedade `data` é `null`. Se você lidar com eventos que estejam em estado de falha, verifique sempre se a propriedade `error` foi definida antes de tentar acessar o valor da propriedade `data`.
## Acessar o objeto de solicitação de origem
A propriedade `request` fornece acesso ao objeto `AWS.Request` de origem. Ela pode ser útil para fazer referência ao objeto `AWS.Request` original para acessar os parâmetros originais que enviou. No exemplo a seguir, a propriedade `request` é usada para acessar o parâmetro `Key` da solicitação de serviço original.
```
s3.getObject({Bucket: 'bucket', Key: 'key'}).on('success', function(response) {
console.log("Key was", response.request.params.Key);
}).send();
```
# Trabalhar com o JSON
JSON é um formato de intercâmbio de dados capaz de ser lido por humanos e por máquina. Embora o nome JSON seja acrônimo de *JavaScript Object Notation*, o formato do JSON independe de qualquer linguagem de programação.
O SDK usa JSON para enviar dados para objetos de serviço ao fazer solicitações e recebe dados de objetos de serviço como JSON. Para mais informações sobre JSON, consulte [json.org](https://json.org).
![\[Como mostrar o formato geral e partes do JSON.\]](http://docs.aws.amazon.com/pt_br/sdk-for-javascript/v2/developer-guide/images/json-format.png)
JSON representa dados de duas formas:
+ Um *objeto*, que é uma coleção não ordenada de pares de nome/valor. Um objeto é definido dentro das chaves esquerda (`{`) e direita (`}`). Cada par de nome e valor começa com o nome seguido por uma vírgula seguido pelo valor. O pares de nome/valor são separados por vírgulas.
+ Uma *matriz*, que é uma coleção ordenada de valores. Um array é definido dentro dos colchetes esquerdo (`[`) e direito (`]`). Os itens no array são separados por vírgulas.
Aqui está um exemplo de um objeto JSON que contém um array de objetos em que os objetos representam as cartas de um baralho. Cada carta é definida por dois pares de nome/valor: um que especifica um valor exclusivo para identificar que essa carta e outro que especifica um URL que aponta para a imagem da carta correspondente.
```
var cards = [{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"}];
```
## JSON como parâmetros do objeto de serviço
Veja a seguir um exemplo de JSON simples usado para definir os parâmetros de uma chamada para um objeto de serviço do Lambda.
```
var pullParams = {
FunctionName : 'slotPull',
InvocationType : 'RequestResponse',
LogType : 'None'
};
```
O objeto `pullParams` é definido por três pares de nome/valor, separados por vírgulas, dentro das chaves esquerda e direita. Ao fornecer parâmetros para uma chamada do método do objeto de serviço, os nomes são determinados pelos nomes de parâmetro do método do objeto de serviço que você pretende chamar. Ao invocar uma função do Lambda, `FunctionName`, `InvocationType` e `LogType` são os parâmetros usados para chamar o método `invoke` em um objeto de serviço do Lambda.
Ao passar os parâmetros para uma chamada do método do objeto de serviço, forneça o objeto JSON para a chamada de método, conforme mostrado no exemplo a seguir de como invocar uma função do Lambda.
```
lambda = new AWS.Lambda({region: 'us-west-2', apiVersion: '2015-03-31'});
// create JSON object for service call parameters
var pullParams = {
FunctionName : 'slotPull',
InvocationType : 'RequestResponse',
LogType : 'None'
};
// invoke Lambda function, passing JSON object
lambda.invoke(pullParams, function(err, data) {
if (err) {
console.log(err);
} else {
console.log(data);
}
});
```
## Retornar dados como JSON
O JSON fornece uma maneira padrão para passar dados entre partes de um aplicativo que precisa enviar vários valores ao mesmo tempo. Os métodos das classes de clientes na API comumente retornam JSON no parâmetro `data` passado para suas funções de retorno de chamada. Por exemplo, aqui está uma chamada para o método `getBucketCors` da classe de cliente Amazon S3.
```
// call S3 to retrieve CORS configuration for selected bucket
s3.getBucketCors(bucketParams, function(err, data) {
if (err) {
console.log(err);
} else if (data) {
console.log(JSON.stringify(data));
}
});
```
O valor de `data` é um objeto JSON. Neste exemplo, JSON que descreve a configuração atual de CORS para um bucket especificado do Amazon S3.
```
{
"CORSRules": [
{
"AllowedHeaders":["*"],
"AllowedMethods":["POST","GET","PUT","DELETE","HEAD"],
"AllowedOrigins":["*"],
"ExposeHeaders":[],
"MaxAgeSeconds":3000
}
]
}
```
# Estratégia de repetição no AWS SDK para JavaScript v2
Vários componentes em uma rede, como servidores DNS, switches, balanceadores de carga e outros, podem gerar erros em qualquer lugar do ciclo de vida de determinada solicitação. A técnica usual para lidar com essas respostas de erro em um ambiente de rede é implementar novas tentativas no aplicativo cliente. Essa técnica aumenta a confiabilidade da aplicação e reduz os custos operacionais para o desenvolvedor. Os AWS SDKs implementam uma lógica de repetição automática para as solicitações da AWS.
## Comportamento de repetição baseado em recuo exponencial
O AWS SDK para JavaScript v2 implementa a lógica de repetição usando [recuo exponencial com instabilidade total](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/#Jitter) para melhor controle de fluxo. A ideia por trás do recuo exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. A instabilidade (atraso aleatório) é usada para evitar colisões sucessivas.
### Testar o atraso de repetição na v2
Para testar o atraso de repetição na v2, o código em [node\$1modules/aws-sdk/lib/event\$1listeners.js](https://github.com/aws/aws-sdk-js/blob/master/lib/event_listeners.js#L588) foi atualizado em `console.log` para exibir o valor presente na variável de atraso da seguinte forma:
```
// delay < 0 is a signal from customBackoff to skip retries
if (willRetry && delay >= 0) {
resp.error = null;
console.log('retry delay: ' + delay);
setTimeout(done, delay);
} else {
done();
}
```
#### Atrasos de repetição com a configuração padrão
É possível testar o atraso para qualquer operação em clientes do AWS SDK. Chamamos a operação `listTables` em um cliente do DynamoDB usando o seguinte código:
```
import AWS from "aws-sdk";
const region = "us-east-1";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise();
```
Para testar as repetições, simulamos `NetworkingError` desconectando a internet do dispositivo que executa o código de teste. Também é possível configurar o proxy para retornar um erro personalizado.
Ao executar o código, você pode ver esse atraso na repetição usando o recuo exponencial com instabilidade da seguinte forma:
```
retry delay: 7.39361151766359
retry delay: 9.0672860785882
retry delay: 134.89340825668168
retry delay: 398.53559817403965
retry delay: 523.8076165896343
retry delay: 1323.8789643058465
```
Como a repetição usa instabilidade, você obterá valores diferentes na execução do código de exemplo.
#### Repetir atrasos com uma base personalizada
O AWS SDK para JavaScript v2 permite passar um número base personalizado de milissegundos para usar no recuo exponencial para repetições de operação. O padrão é 100 ms para todos os serviços, exceto para o DynamoDB, onde o padrão é 50 ms.
Testamos repetições com uma base personalizada de 1.000 ms da seguinte forma:
```
...
const client = new AWS.DynamoDB({ region, retryDelayOptions: { base: 1000 } });
...
```
Simulamos `NetworkingError` desconectando a internet do dispositivo que executa o código de teste. É possível ver que os valores de atraso de repetição são maiores em comparação com a execução anterior, em que o padrão era 50 ms ou 100 ms.
```
retry delay: 356.2841549924913
retry delay: 1183.5216495444615
retry delay: 2266.997988094194
retry delay: 1244.6948354966453
retry delay: 4200.323030066383
```
Como a repetição usa instabilidade, você obterá valores diferentes na execução do código de exemplo.
#### Atrasos de repetição com algoritmo de recuo personalizado
O AWS SDK para JavaScript v2 também permite passar uma função de recuo personalizada que aceita uma contagem de repetições e erro, e retorna a quantidade de tempo de atraso em milissegundos. Se o resultado for um valor negativo diferente de zero, nenhuma outra tentativa de repetição será feita.
Testamos a função de recuo personalizada que usa recuo linear com valor base de 200 ms da seguinte forma:
```
...
const client = new AWS.DynamoDB({
region,
retryDelayOptions: { customBackoff: (count, error) => (count + 1) * 200 },
});
...
```
Simulamos `NetworkingError` desconectando a internet do dispositivo que executa o código de teste. É possível ver que os valores do atraso de repetição são múltiplos de 200.
```
retry delay: 200
retry delay: 400
retry delay: 600
retry delay: 800
retry delay: 1000
```