La Guía de referencia de la API de AWS SDK for JavaScript V3 describe en detalle todas las operaciones de la API para la versión 3 (V3) de AWS SDK for JavaScript.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Creación y llamada de objetos de servicio

La API de JavaScript admite la mayoría de los servicios de AWS disponibles. Cada servicio de la API de JavaScript proporciona una clase de cliente con un método de send que se utiliza para invocar todas las API que admite el servicio. Para obtener más información sobre clases de servicios, las operaciones y los parámetros en la API de JavaScript, consulte la Referencia de la API.

Cuando utiliza el SDK en Node.js, añade el paquete del SDK para cada servicio que necesita a su aplicación mediante import, que ofrece soporte para todos los servicios actuales. En el siguiente ejemplo se crea un objeto de servicio de Amazon S3 en la región de 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"
});

Especificación de parámetros de objetos de servicio

Al llamar a un método de un objeto de servicio, transfiera los parámetros en JSON según los requiera la API. Por ejemplo, en Amazon S3, para obtener un objeto para un bucket y una clave especificados, transfiera los siguientes parámetros al método GetObjectCommand desde el S3Client. Para obtener más información acerca de cómo transferir parámetros JSON, consulte Uso de JSON.

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

Para obtener más información acerca de parámetros de Amazon S3, consulte @aws-sdk/client-s3 en la referencia de la API.

Uso de @smithy /types para clientes generados en TypeScript

Si usa TypeScript, el paquete @smithy/types le permite manipular las formas de entrada y salida de un cliente.

Escenario: eliminación de undefined de las estructuras de entrada y salida

Los miembros de las formas generadas se agregan a undefined para las formas de entrada y son ? (opcional) para las formas de salida. En el caso de las entradas, esto aplaza la validación al servicio. En el caso de las salidas, esto sugiere encarecidamente que se comprueben los datos de salida en tiempo de ejecución.

Si desea omitir estos pasos, use los ayudantes de tipo AssertiveClient o UncheckedClient. El siguiente ejemplo utiliza los ayudantes de tipo con el servicio de 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();

Cuando se utiliza la transformación en un cliente no agregado con la sintaxis Command, la entrada no se puede validar porque pasa por otra clase, como se muestra en el ejemplo siguiente.

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();

Escenario: reducción de los tipos de blobs de carga útil de salida generados por Smithy-TypeScript para clientes

Este escenario es especialmente relevante para operaciones con cuerpos de streaming, como en el S3Client del AWS SDK para JavaScript v3.

Dado que los tipos de carga útil de blob dependen de la plataforma, es posible que desee indicar en su aplicación que un cliente se está ejecutando en un entorno específico. Esto reduce los tipos de carga útil de blob, como se muestra en el siguiente ejemplo.

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!;