AWS Marketplace API 參考已重組。如需支援的 API 操作的詳細資訊，請參閱 [AWS Marketplace API 參考](https://docs.aws.amazon.com/marketplace/latest/APIReference/Welcome.html)。

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

# 使用 AWS Marketplace 協議 API
<a name="agreement-apis"></a>

AWS Marketplace 是精選的數位目錄，客戶可用來尋找、購買、部署和管理第三方軟體、資料和服務，以建置解決方案並執行其業務。 AWS Marketplace 協議服務提供 API 界面，可協助 AWS Marketplace 買方和賣方管理其協議，包括列出、搜尋和篩選協議。

## 重要概念
<a name="agreement-key-concepts"></a>

下表說明 AWS Marketplace 協議 API 中使用的重要概念。


| 概念 | 說明 | 
| --- | --- | 
| 接受者 | 接受提案者在協議中延伸之所有或部分條款的一方。對於最常見的使用案例，接受者是產品的買方。 | 
| 協議 | 繫結兩方的文件，包括提案者 （通常為賣方/ISV 或通路合作夥伴） 和接受者 （通常為買方），並定義他們之間適用的條款與條件。 | 
| 協議取消請求 | 賣方 （提案者） 啟動取消作用中協議的請求。買方 （接受者） 可以接受或拒絕取消請求。如果接受，協議取消工作流程會以非同步方式執行，且協議狀態會變更為已取消。如果拒絕，協議會保持作用中狀態，賣方可以提交新的取消請求。 | 
| 協議提案 | 參考賣方/提案者所提議之一組條款/優惠的實體。 | 
| 協議請求 | 是指因客戶動作而建立之資源的實體，概述協議建立/修改參數、請求生命週期，以及接受請求時的預估結果。 | 
| 計費維度 | 與產品定價方式相關的元素。例如，與軟體即服務 (SaaS) 產品的唯讀使用者相比，適用於 Amazon Machine Image (AMI) 產品的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體或 Premium。 | 
| 頻道合作夥伴 (CP) | 產品擁有者 (ISV) 授權代表其轉售產品的組織 AWS Marketplace。 | 
| 獨立軟體廠商 (ISVs) | 在其中列出和管理自己產品的賣方 AWS Marketplace。 | 
| 意圖 | 意圖代表買方在建立協議時的動機。目前支援的意圖是在協議建立流程中新增、修改和取代。 | 
| 付款請求 | 賣方 （提案者） 針對與協議相關聯的付款提出的請求。買方 （接受者） 可以接受或拒絕付款請求。 | 
| 提案者 | 擴展協議中初始條款集的一方，最常使用 優惠。 | 
| 採購單 | 組織要求買方使用採購訂單向核准的供應商購買、追蹤他們購買的內容，並確保支出被預測、編列預算、核准，以及指派給負責的成本中心 （們）。 | 
| 資源 | 賣方打算銷售的單位或資源 AWS Marketplace，通常稱為基本產品。在新增產品資訊、部署屬性和帳單資訊之前，基本產品尚未完成供買方使用。產品說明賣方打算銷售之清單的產品資訊、軟體部署屬性和計費機制。產品必須與 優惠配對，才能成為可供買方銷售和使用的可交易單位 AWS Marketplace。 | 
| 術語 | 協議中的單位，可控管協議的強制執行方式 （例如定價）。 | 

## Endpoint
<a name="agreement-endpoint"></a>

您可以使用下列端點存取 AWS Marketplace Agreement Service：


| Endpoint | 區域 | 支援的 IP 通訊協定 | 
| --- | --- | --- | 
| agreement-marketplace.us-east-1.api.aws | 美國東部 (維吉尼亞北部) | IPv4、IPv6 | 

## 許可
<a name="agreement-permissions"></a>

協議 API 使用標準 AWS Signature 第 4 版 (SigV4) 身分驗證。您必須擁有有效的 AWS 登入資料和適當的 IAM 許可，才能呼叫 API。如需詳細資訊，請參閱[AWS Marketplace 協議 API 的存取控制](agreement-api-access-control.md)。

### 錯誤代碼
<a name="agreement-error-codes"></a>

下列錯誤代碼適用於 [AWS Marketplace Agreement Service 動作](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_Operations_AWS_Marketplace_Agreement_Service.html)。多個使用案例可能會傳回單一錯誤代碼。請參閱以下描述，以識別發生每個錯誤碼的特定案例。此清單並不詳盡，可能會隨著新功能發佈而更新。

#### ValidationException
<a name="agreement-error-codes-validation"></a>


| 錯誤碼 | 說明 | 
| --- | --- | 
| INVALID\_SOURCE\_AGREEMENT\_IDENTIFIER | 當來源協議識別符不符合預期的格式，或當來源協議識別符提供給不需要的意圖 （例如 NEW) 時傳回。 | 
| MISSING\_SOURCE\_AGREEMENT\_IDENTIFIER | 當來源協議識別符未針對需要的意圖 （例如 REPLACE 或 AMEND) 提供時傳回。 | 
| INVALID\_REQUESTED\_TERM\_CONFIGURATION | 當請求的詞彙組態無效時傳回。可能的情況：+  系統會為不接受組態的詞彙提供組態。 <br />+  缺少必要的組態。 <br />+  選擇器值不屬於協議提案。 <br />+  不允許多個維度選擇時，維度只能包含一個維度。 <br />+  無法在協議提案或接受的條款中辨識維度索引鍵。 <br />+  維度值只能在未針對維度啟用數量組態時為 1。 <br />+  組態包含重複的維度索引鍵。 <br />+  組態與來源協議不同。  | 
| INVALID\_AGREEMENT\_PROPOSAL\_IDENTIFIER | 當協議提案識別符與預期的格式不符，或為不需要的意圖 （例如 AMEND) 提供協議提案識別符時傳回。 | 
| MISSING\_AGREEMENT\_PROPOSAL\_IDENTIFIER | 當協議提案識別符未針對需要的意圖 （例如 NEW 或 REPLACE) 提供時傳回。 | 
| INVALID\_FILTER\_NAME | 當提供的篩選條件名稱不是可辨識的篩選條件，或請求中包含重複的篩選條件名稱時傳回。 | 
| INVALID\_FILTER\_VALUES | 當篩選條件值無效、重複、空白、超過允許的計數上限，或日期範圍篩選條件指定AfterEndTime值前面BeforeEndTime的值時傳回。 | 
| INVALID\_NEXT\_TOKEN | 當分頁字符格式錯誤、過期、無法解密，或在分頁呼叫之間變更請求參數時傳回。 | 
| DUPLICATE\_CHARGES | 當請求包含重複的費用識別符，或為相同的費用識別符提供不同的採購訂單值時傳回。 | 
| UNSUPPORTED\_FILTERS | 不支援提供的篩選條件組合時傳回。支援的篩選條件組合會根據方類型而有所不同。檢查公有文件中支援的組合。 | 
| INVALID\_PURCHASE\_ORDER\_REFERENCE | 當採購訂單參考不符合格式要求，或未依帳戶管理員設定提供必要的採購訂單時傳回。 | 
| INVALID\_CHARGE\_AMOUNT | 當費用金額無效時傳回。可能的情況：+  費用金額超過期限的總費用金額上限。 <br />+  費用金額格式不符合貨幣需求 （例如，太多小數位數）。 <br />+  由於協議已達到最高總費用金額，因此沒有剩餘金額可用。  | 
| UNSUPPORTED\_ACTION | 當資源的目前狀態不支援請求的操作時傳回。特定案例因 API 而異：+  `UpdatePurchaseOrders` – 收費日期是過去的，且自動續約已停用、收費日期在 3 小時內、收費是退款費用、收費修訂不是最新的、採購訂單都不屬於相同的協議，或協議未處於作用中狀態。 <br />+  `CreateAgreementRequest` – 不支援修改未來日期的協議、資源類型和期限類型組合不支援請求的意圖、不允許使用未來日期的協議取代作用中的協議、修改期間無法變更協議持續時間、目前無法更新協議 （例如，存在待定權利）、協議提案必須參考與來源協議相同的資源、協議提案必須與來源協議不同，或協議類型不支援此動作。 <br />+  `AcceptAgreementRequest` – 資源類型和術語類型組合不支援此動作、協議類型不支援此動作、同一資源上已存在作用中的協議，或目前無法更新協議。 <br />+  `CancelAgreement` – 協議具有待定權利、協議類型不支援取消、當與 的協議在相同資源上仍`PaymentScheduleTerm`處於作用中`ConfigurableUpfrontPricingTerm`狀態時`UsageBasedPricingTerm`，或資源類型和期限類型組合不支援取消時，無法取消與 的協議。 <br />+  `GetBillingAdjustmentRequest` – 協議是非購買協議類型，或發起人是協議的接受者。 <br />+  `SendAgreementCancellationRequest` – 協議類型不支援此動作。 <br />+  `AcceptAgreementCancellationRequest` – 協議類型不支援此動作。 <br />+  `RejectAgreementCancellationRequest` – 協議類型不支援此動作。 <br />+  `CancelAgreementCancellationRequest` – 協議類型不支援此動作。 <br />+  `GetAgreementCancellationRequest` – 協議是一種非購買協議類型。  | 

#### ResourceNotFoundException
<a name="agreement-error-codes-resource-not-found"></a>

`ResourceNotFoundException` 包含 `resourceType`和 `resourceId` 欄位，可識別找不到的資源。下表說明可能導致每個資源類型發生此例外狀況的案例。

**注意**  
基於安全考量，無論資源不存在或發起人無法存取，都會傳回相同的錯誤。這可防止列舉有效的資源識別符。


| Resource Type (資源類型) | 可能的情況 | 
| --- | --- | 
| AgreementProposal |  +  找不到指定識別符的協議提案。 <br />+  優惠並非以接受者為目標。 <br />+  該優惠不適用於接受者的國家/地區。   | 
| Agreement |  +  找不到指定識別符的協議。 <br />+  發起人既不是協議的接受者也不是提案者。   | 
| AgreementRequest |  +  找不到指定識別符的協議請求。 <br />+  協議請求屬於另一個發起人。 <br />+  協議請求已過期。 <br />+  協議請求已被相同產品或優惠的後續接受請求取代。 <br />+  由於提供重新發佈或提供過期，協議提案在 `CreateAgreementRequest`和 `AcceptAgreementRequest`呼叫之間變成非作用中。   | 
| Charge |  +  找不到指定識別符的費用。 <br />+  費用不屬於指定的協議。   | 
| BillingAdjustmentRequest |  +  找不到指定識別符的帳單調整請求。 <br />+  發起人既不是接受者，也不是與調整相關聯的協議提案者。   | 
| AgreementCancellationRequest |  +  找不到指定識別符的協議取消請求。 <br />+  發起人既不是接受者，也不是與取消請求相關聯協議的提議者。   | 
| PaymentRequest |  +  找不到指定識別符的付款請求。 <br />+  發起人既不是接受者，也不是與付款請求相關聯協議的提議者。   |