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

# 使用適用於 Node.js 的 X-Ray AWS 開發套件追蹤 SDK 呼叫
<a name="xray-sdk-nodejs-awssdkclients"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

當您的應用程式呼叫 AWS 服務 來存放資料、寫入佇列或傳送通知時，適用於 Node.js 的 X-Ray 開發套件會在[子區段](xray-sdk-nodejs-subsegments.md)中追蹤下游的呼叫。您在這些服務中存取的追蹤 AWS 服務和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。

您透過 [適用於 JavaScript 的 AWS SDK V2](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html) 或 [適用於 JavaScript 的 AWS SDK V3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) 建立的檢測 AWS SDK 用戶端。每個 AWS SDK 版本都提供用於檢測 AWS SDK 用戶端的不同方法。

**注意**  
目前，與檢測 V2 用戶端相比，適用於 Node.js 的 AWS X-Ray SDK 在檢測 適用於 JavaScript 的 AWS SDK V3 用戶端時傳回的區段資訊較少。例如，代表對 DynamoDB 呼叫的子區段不會傳回資料表名稱。如果您在追蹤中需要此區段資訊，請考慮使用 適用於 JavaScript 的 AWS SDK V2。

------
#### [ 適用於 JavaScript 的 AWS SDK V2 ]

您可以在對 的呼叫中包裝`aws-sdk`您的需求陳述式，以檢測所有 AWS SDK V2 用戶端`AWSXRay.captureAWS`。

**Example app.js - AWS SDK 檢測**  

```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```

若要檢測個別用戶端，請在呼叫 時包裝 AWS SDK 用戶端`AWSXRay.captureAWSClient`。例如，若要檢測 `AmazonDynamoDB` 用戶端：

**Example app.js - DynamoDB 用戶端檢測**  

```
    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```

**警告**  
請勿將 `captureAWS` 和 `captureAWSClient` 一起使用。這會導致重複的子區段。

如果您想要使用 [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) 搭配 [ECMAScript 模組](https://nodejs.org/api/esm.html) (ESM) 載入JavaScript程式碼，請使用下列範例來匯入程式庫：

**Example app.js - AWS SDK 檢測**  

```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```

若要使用 ESM 檢測所有 AWS 用戶端，請使用下列程式碼：

**Example app.js - AWS SDK 檢測**  

```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```

對於所有 服務，您可以在 X-Ray 主控台中查看名為 的 API 名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務映射中提供更精細的服務。

例如，當您使用經檢測的 DynamoDB 用戶端進行呼叫時，軟體開發套件會將資料表名稱新增至以資料表為目標的呼叫區段。在 主控台中，每個資料表會在服務映射中顯示為個別節點，並針對非資料表目標的呼叫使用一般 DynamoDB 節點。

**Example 呼叫 DynamoDB 以儲存項目的子區段**  

```
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}
```

您存取具名資源時，對以下服務的呼叫會在服務地圖中建立額外節點。未針對特定資源的呼叫，則會建立服務的一般節點。
+ **Amazon DynamoDB** – 資料表名稱
+ **Amazon Simple Storage Service** – 儲存貯體和金鑰名稱
+ **Amazon Simple Queue Service** – 佇列名稱

------
#### [ 適用於 JavaScript 的 AWS SDK V3 ]

 適用於 JavaScript 的 AWS SDK V3 是模組化的，因此您的程式碼只會載入所需的模組。因此，由於 V3 不支援 `captureAWS`方法，因此無法檢測所有 AWS SDK 用戶端。

如果您想要使用 TypeScript 搭配 ECMAScript 模組 (ESM) 載入 JavaScript 程式碼，您可以使用下列範例來匯入程式庫：

```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```

使用 `AWSXRay.captureAWSv3Client`方法檢測每個 AWS SDK 用戶端。例如，若要檢測 `AmazonDynamoDB` 用戶端：

**Example app.js - 使用適用於 Javascript V3 的 SDK 進行 DynamoDB 用戶端檢測**  

```
    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "{{region}}" }));
```

使用 適用於 JavaScript 的 AWS SDK V3 時，資料表名稱、儲存貯體和金鑰名稱或佇列名稱等中繼資料目前不會傳回，因此追蹤映射不會像使用 適用於 JavaScript 的 AWS SDK V2 檢測 AWS SDK 用戶端時一樣包含每個具名資源的離散節點。

**Example 使用 適用於 JavaScript 的 AWS SDK V3 時，呼叫 DynamoDB 以儲存項目的子區段**  

```
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}
```

------