O Guia de referência da API do AWS SDK para JavaScript V3 descreve em detalhes todas as operações da API para o AWS SDK para JavaScript versão 3 (V3).

Criar e chamar objetos de serviço

A API JavaScript oferece suporte para a maioria dos serviços da AWS disponíveis. Cada serviço na API JavaScript fornece uma classe de cliente com um método send que você usa para invocar todas as APIs suportadas pelo 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.

Ao usar o SDK no Node.js, você adiciona o pacote do SDK para cada serviço de que precisa para seu aplicativo usando import, que fornece suporte a todos os serviços atuais. O exemplo a seguir cria um objeto de recurso do Amazon S3 na Região us-west-1.

// Import the Amazon S3 service client
import { S3Client } from "@aws-sdk/client-s3"; 
// Create an S3 client in the us-west-1 Region
const s3Client = new S3Client({
    region: "us-west-1"
});

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 o bucket e a chave especificados, passe os parâmetros a seguir para o método GetObjectCommand do S3Client. Para obter mais informações sobre como passar os parâmetros JSON, consulte Trabalhar com JSON.

s3Client.send(new GetObjectCommand({Bucket: 'bucketName', Key: 'keyName'}));

Para obter mais informações sobre parâmetros do Amazon S3, consulte @aws-sdk/client-s3 na Referência da API.

Use @smithy/types para clientes gerados no TypeScript

Se você estiver usando o TypeScript, o pacote @smithy/types permite manipular as formas de entrada e saída de um cliente.

Cenário: remover undefined das estruturas de entrada e saída

Os membros das formas geradas são unidos às formas undefined de entrada e são ? (opcional) às formas de saída. Para entradas, isso adia a validação para o serviço. Para saídas, isso sugere fortemente que você deve verificar os dados de saída em runtime.

Se você quiser pular essas etapas, use os auxiliares de tipo AssertiveClient ou UncheckedClient. O exemplo a seguir usa os auxiliares de tipo com o serviço Amazon S3.

import { S3 } from "@aws-sdk/client-s3";
import type { AssertiveClient, UncheckedClient } from "@smithy/types";

const s3a = new S3({}) as AssertiveClient<S3>;
const s3b = new S3({}) as UncheckedClient<S3>;

// AssertiveClient enforces required inputs are not undefined
// and required outputs are not undefined.
const get = await s3a.getObject({
  Bucket: "",
  // @ts-expect-error (undefined not assignable to string)
  Key: undefined,
});

// UncheckedClient makes output fields non-nullable.
// You should still perform type checks as you deem
// necessary, but the SDK will no longer prompt you
// with nullability errors.
const body = await (
  await s3b.getObject({
    Bucket: "",
    Key: "",
  })
).Body.transformToString();

Ao usar a transformação em um cliente não agregado com a sintaxe Command, a entrada não pode ser validada porque passa por outra classe, conforme mostrado no exemplo abaixo.

import { S3Client, ListBucketsCommand, GetObjectCommand, GetObjectCommandInput } from "@aws-sdk/client-s3";
import type { AssertiveClient, UncheckedClient, NoUndefined } from "@smithy/types";

const s3 = new S3Client({}) as UncheckedClient<S3Client>;

const list = await s3.send(
  new ListBucketsCommand({
    // command inputs are not validated by the type transform.
    // because this is a separate class.
  })
);

/**
 * Although less ergonomic, you can use the NoUndefined<T>
 * transform on the input type.
 */
const getObjectInput: NoUndefined<GetObjectCommandInput> = {
  Bucket: "undefined",
  // @ts-expect-error (undefined not assignable to string)
  Key: undefined,
  // optional params can still be undefined.
  SSECustomerAlgorithm: undefined,
};

const get = s3.send(new GetObjectCommand(getObjectInput));

// outputs are still transformed.
await get.Body.TransformToString();

Cenário: restringir os tipos de blob de carga útil de saída de um cliente gerado pelo Smithy-TypeScript

Esse cenário é relevante principalmente para operações com corpos de streaming, como S3Client no AWS SDK para JavaScript v3.

Como os tipos de blob de carga útil dependem da plataforma, indique em seu aplicativo que um cliente está sendo executado em um ambiente específico. Isso restringe os tipos de blob de carga útil conforme mostrado no exemplo a seguir.

import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
import type { NodeJsClient, SdkStream, StreamingBlobPayloadOutputTypes } from "@smithy/types";
import type { IncomingMessage } from "node:http";

// default client init.
const s3Default = new S3Client({});

// client init with type narrowing.
const s3NarrowType = new S3Client({}) as NodeJsClient<S3Client>;

// The default type of blob payloads is a wide union type including multiple possible
// request handlers.
const body1: StreamingBlobPayloadOutputTypes = (await s3Default.send(new GetObjectCommand({ Key: "", Bucket: "" })))
  .Body!;

// This is of the narrower type SdkStream<IncomingMessage> representing
// blob payload responses using specifically the node:http request handler.
const body2: SdkStream<IncomingMessage> = (await s3NarrowType.send(new GetObjectCommand({ Key: "", Bucket: "" })))
  .Body!;