[適用於 JavaScript 的 AWS SDK V3 API 參考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)詳細說明 第 3 版 適用於 JavaScript 的 AWS SDK (V3) 的所有 API 操作。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立和呼叫服務物件
<a name="creating-and-calling-service-objects"></a>

JavaScript API 支援大多數可用的 AWS 服務。JavaScript API 中的每個服務都會提供用戶端類別，`send`讓您用來叫用服務支援的每個 API。如需 JavaScript API 中服務類別、操作和參數的詳細資訊，請參閱 [API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-transcribe/)。

在 Node.js 中使用 SDK 時，您可以使用 將每個所需服務的 SDK 套件新增至應用程式`import`，這可提供所有目前服務的支援。下列範例會在 `us-west-1`區域中建立 Amazon S3 服務物件。

```
// 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"
});
```

## 指定服務物件參數
<a name="specifying-service-object-parameters"></a>

在呼叫服務物件的方法時，請依照 API 所需來傳遞 JSON 格式的參數。例如，在 Amazon S3 中，若要取得指定儲存貯體和金鑰的物件，請從 將下列參數傳遞至 `GetObjectCommand`方法`S3Client`。如需傳遞 JSON 參數的詳細資訊，請參閱[使用 JSON](working-with-json.md)。

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

如需 Amazon S3 參數的詳細資訊，請參閱 API 參考中的 [@aws-sdk/client-s3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-s3/)。

## 針對 TypeScript 中產生的用戶端使用 @smithy/types
<a name="smithy-types"></a>

如果您使用的是 TypeScript，`@smithy/types`套件可讓您操作用戶端的輸入和輸出形狀。

### 案例：`undefined`從輸入和輸出結構中移除
<a name="remove-undefined-from-input"></a>

產生的形狀成員與 聯集`undefined`用於輸入形狀，而 `?`（選用） 用於輸出形狀。對於輸入，這會將驗證延遲到 服務。對於輸出，這強烈建議您應該執行時間檢查輸出資料。

如果您想要略過這些步驟，請使用 `AssertiveClient`或`UncheckedClient`輸入協助程式。下列範例使用類型協助程式搭配 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();
```

在非彙總用戶端上使用 轉換搭配 `Command`語法時，無法驗證輸入，因為它會通過另一個類別，如以下範例所示。

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

### 案例：縮小 Smithy-TypeScript 產生的用戶端輸出承載 Blob 類型
<a name="remove-undefined-from-input"></a>

此案例主要與 適用於 JavaScript 的 AWS SDK v3 `S3Client`中串流主體的操作相關，例如 內的 。

由於 Blob 承載類型取決於平台，建議您在應用程式中指出用戶端正在特定環境中執行。這會縮小 Blob 承載類型，如下列範例所示。

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