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

# 使用 SageMaker API 或 擴展訓練計畫 AWS CLI
<a name="training-plan-extension-using-api-cli-sdk"></a>

SageMaker 訓練計畫支援透過 API 以程式設計方式擴展訓練計畫。您可以使用 AWS CLI 或 SageMaker SDKs與訓練計畫 API 互動。

訓練計畫延伸包含下列 API 動作：
+ **`SearchTrainingPlanOfferings`：**指定您的訓練計畫 ARN 和所需的延伸期間，以搜尋可用的延伸產品。API 會在 `TrainingPlanExtensionOfferings` 欄位中傳回延伸項目。
+ **`ExtendTrainingPlan`：**購買特定的延伸產品，藉由提供 來擴展您的訓練計畫`TrainingPlanExtensionOfferingId`。這會保留額外的運算容量，並更新訓練計畫的結束日期。
+ **`DescribeTrainingPlanExtensionHistory`：**檢視訓練計劃的完整擴充功能歷史記錄，包括所有過去的擴充功能及其狀態、日期和付款資訊。

**Topics**
+ [搜尋延伸產品](search-extension-offerings-api-cli-sdk.md)
+ [購買 擴充功能](extend-training-plan-api-cli-sdk.md)
+ [檢視擴充功能歷史記錄](describe-extension-history-api-cli-sdk.md)

# 搜尋延伸產品
<a name="search-extension-offerings-api-cli-sdk"></a>

使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API 搭配 `TrainingPlanArn` 參數，為您的訓練計劃尋找可用的延伸產品。

下列範例使用 AWS CLI 命令來搜尋現有訓練計畫的延伸產品。

```
aws sagemaker search-training-plan-offerings \
--training-plan-arn "arn:aws:sagemaker:us-east-2:123456789012:training-plan/my-training-plan" \
--duration-hours 48
```

此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應包含指定訓練計畫`TrainingPlanExtensionOfferings`可用的延伸產品。

```
{
    "TrainingPlanOfferings": [],
    "TrainingPlanExtensionOfferings": [
        {
            "TrainingPlanExtensionOfferingId": "tpeo-SHA-256-hash-value",
            "AvailabilityZone": "us-east-2a",
            "StartDate": "2025-09-23T12:00:00Z",
            "EndDate": "2025-09-25T12:00:00Z",
            "DurationHours": 48,
            "UpfrontFee": "xxxx.xx",
            "CurrencyCode": "USD"
        }
    ]
}
```

下列各節定義 API `SearchTrainingPlanOfferings`操作在搜尋延伸項目時的必要和選用輸入請求參數。

## 必要參數
<a name="search-extension-offerings-required-params"></a>

呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API 來搜尋延伸產品時，您必須提供下列值：
+ `TrainingPlanArn`：您要延伸的訓練計畫的 。必須`TrainingPlanArn`參考狀態為 `Active`或 的現有訓練計畫`Scheduled`。

## 選用的參數
<a name="search-extension-offerings-optional-params"></a>

下列各節提供一些選用參數的詳細資訊，您可以在搜尋延伸產品時傳遞給 `SearchTrainingPlanOfferings` API 請求。
+ `DurationHours`：擴充功能的所需持續時間，以小時為單位。`DurationHours` 會四捨五入至最接近的 24 倍數。

# 購買 擴充功能
<a name="extend-training-plan-api-cli-sdk"></a>

選取擴充功能方案後，請使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ExtendTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ExtendTrainingPlan.html) API 購買擴充功能。

下列範例使用 AWS CLI 命令來擴展訓練計劃。

```
aws sagemaker extend-training-plan \
--training-plan-extension-offering-id "tpeo-SHA-256-hash-value"
```

此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應包含訓練計畫的延伸項目清單。

```
{
    "TrainingPlanExtensions": [
        {
            "TrainingPlanExtensionOfferingId": "tpeo-SHA-256-hash-value",
            "ExtendedAt": "2025-09-17T10:00:00Z",
            "StartDate": "2025-09-23T12:00:00Z",
            "EndDate": "2025-09-25T12:00:00Z",
            "Status": "Pending",
            "PaymentStatus": "Pending",
            "AvailabilityZone": "us-east-2a",
            "DurationHours": 48,
            "UpfrontFee": "xxxx.xx",
            "CurrencyCode": "USD"
        }
    ]
}
```

下一節定義 `ExtendTrainingPlan` API 操作的強制輸入請求參數。

## 必要參數
<a name="extend-training-plan-required-params"></a>

呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ExtendTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ExtendTrainingPlan.html) API 擴展訓練計畫時，您必須提供下列值：
+ `TrainingPlanExtensionOfferingId`：您正在購買的延伸產品 ID。您可以在 `SearchTrainingPlanOfferings` API 呼叫的回應`TrainingPlanExtensionOfferings`中，從 擷取此 ID。其格式應以 `tpeo-*` 開頭。

# 檢視擴充功能歷史記錄
<a name="describe-extension-history-api-cli-sdk"></a>

使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlanExtensionHistory.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlanExtensionHistory.html) API 來檢視訓練計畫的完整延伸歷史記錄。

下列範例使用 AWS CLI 命令來擷取延伸歷史記錄。

```
aws sagemaker describe-training-plan-extension-history \
--training-plan-arn "arn:aws:sagemaker:us-east-2:123456789012:training-plan/my-training-plan"
```

此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應包含訓練計畫所有延伸項目的分頁清單。

```
{
    "TrainingPlanExtensions": [
        {
            "TrainingPlanExtensionOfferingId": "tpeo-SHA-256-hash-value",
            "ExtendedAt": "2025-09-17T10:00:00Z",
            "StartDate": "2025-09-23T12:00:00Z",
            "EndDate": "2025-09-25T12:00:00Z",
            "Status": "Active",
            "PaymentStatus": "Completed",
            "AvailabilityZone": "us-east-2a",
            "DurationHours": 48,
            "UpfrontFee": "xxxx.xx",
            "CurrencyCode": "USD"
        }
    ],
    "NextToken": null
}
```

下列各節會針對 `DescribeTrainingPlanExtensionHistory` API 操作定義必要和選用的輸入請求參數。

## 必要參數
<a name="describe-extension-history-required-params"></a>

呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlanExtensionHistory.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlanExtensionHistory.html) API 時，您必須提供下列值：
+ `TrainingPlanArn`：要擷取其延伸歷史記錄的訓練計劃的 。

## 選用的參數
<a name="describe-extension-history-optional-params"></a>

下列各節提供一些選用參數的詳細資訊，您可以將這些參數傳給 `DescribeTrainingPlanExtensionHistory` API 請求。
+ `NextToken`：如果先前的回應遭到截斷，您會收到此字符。在下一次請求中使用它來接收下一組結果。
+ `MaxResults`：回應中傳回的延伸項目數目上限。

## 延伸模組狀態值
<a name="extension-status-values-api"></a>

延伸項目可以有下列狀態值：
+ `Pending`：已請求擴充功能，正在等待付款處理。
+ `Active`：已成功購買延伸模組並處於作用中狀態。
+ `Scheduled`：延伸項目排定在未來的時間開始。
+ `Failed`：擴充功能購買失敗 （例如，由於付款問題）。
+ `Expired`：延長期間已結束。