AWS 合作夥伴中心 API 參考已重組。如需支援的 API 操作的詳細資訊，請參閱 [AWS 合作夥伴中心 API 參考](https://docs.aws.amazon.com/partner-central/latest/APIReference/Welcome.html)。

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

# 使用 Marketplace 收入共享
<a name="working-with-marketplace-revenue-share"></a>

Marketplace 收入共享是AWS Marketplace 產品的輸入，它會宣告透過AWS Marketplace 收集的產品總收入部分。AWS使用此輸入將合作夥伴的 Marketplace 收集收入與其他收入訊號相互關聯。

Marketplace Revenue Share Service 公開 APIs 來建立、擷取和列出 Marketplace Revenue Share 資源，以及管理其配置 （合作夥伴宣告的收入共享百分比和生效日期時段）。Marketplace Revenue Share 資源支援標準AWS標記操作。

## 什麼是 Marketplace 收入共享？
<a name="what-is-a-marketplace-revenue-share"></a>

Marketplace 收入共享有兩個層級：
+ **共用** — 單一AWS Marketplace 產品的輸入，由 Marketplace 識別`ProductId`。每個產品只有一個 Marketplace 收入共享。
+ **一或多個配置** – 每個配置都會宣告 `RevenueSharePercent`和有效日期時段 (`EffectiveDate`，選擇性為 `ExpirationDate`)。共享可以隨著時間的推移有許多配置，但在任何時候都只能套用一個`ACTIVE`配置。

配置具有下列關鍵屬性：
+ **狀態** — `ACTIVE`或 `INACTIVE`。建立時，狀態預設為 `ACTIVE`。只有`ACTIVE`配置參與收入計算和重疊檢查。
+ **重疊不可變** - 在單一共享中，沒有兩個`ACTIVE`配置可能有重疊`[EffectiveDate, ExpirationDate]`的範圍。隨時允許每個共享最多一個開放式`ACTIVE`配置 （不允許 `ExpirationDate`)。

## 使用 Marketplace 收入共享
<a name="managing-marketplace-revenue-shares"></a>

合作夥伴會透過 Marketplace Revenue Share Service 管理 Marketplace Revenue Shares 及其配置。生命週期會進行兩個流程：共享流程 （建立、擷取、列出、標籤） 和配置流程 （建立、更新、軟刪除、擷取、列出）。

### 建立 Marketplace 收入共享
<a name="creating-a-marketplace-revenue-share"></a>

第一步是使用 `CreateMarketplaceRevenueShare` API 動作為 Marketplace 產品建立AWS Marketplace 收入共享。共享由 Marketplace 識別`ProductId`，並做為所有後續配置的容器。

建立 Marketplace Revenue Share 時，合作夥伴必須提供：
+ **`Catalog`** — `AWS` `Sandbox`用於生產或測試。
+ **`ProductId`** — 25 個字元的 Marketplace 產品 ID。模式：`[a-z0-9]{25}`。

合作夥伴可以選擇性地提供：
+ **`Tags`** — 建立時最多 50 個資源組織的鍵值對。使用 `TagResource` 在建立後新增標籤。
+ **`ClientToken`** — 等冪字符，可防止在重試時重複建立。最多 64 個字元。SDKs 會自動產生此字符。

產品驗證：建立時，服務會向AWS Marketplace 驗證產品是否由發起人帳戶或透過合作夥伴帳戶連線 (PAC) 連接到發起人的子公司帳戶所擁有。如果產品不存在或擁有的帳戶未獲授權給發起人，API 會傳回`ValidationException`原因為 `PRODUCT_NOT_FOUND_OR_NOT_OWNED`。

每個產品一個共用：相同 `ProductId`中相同 的第二個`CreateMarketplaceRevenueShare`呼叫會`Catalog`傳回 `ConflictException`。

回應會傳回共享的 `Arn`（格式 `arn:{partition}:partnercentral:{region}:{account-id}:catalog/{catalog}/marketplace-revenue-share/{productId}`)`Catalog`、`ProductId`、、初始`Version`數字 （從 1 開始，並在每個配置變動上遞增），以及在建立時套用的任何標籤。

### 新增配置
<a name="adding-marketplace-revenue-share-allocations"></a>

建立 Marketplace 收入共享後，合作夥伴會透過 `CreateMarketplaceRevenueShareAllocation` API 動作建立配置，宣告收入共享百分比和生效日期時段。

建立配置時，合作夥伴必須提供：
+ **`Catalog`** — `AWS`或 `Sandbox`。
+ **`MarketplaceRevenueShareIdentifier`** — 父共享的識別符。
+ **`RevenueSharePercent`** — 透過 Marketplace 以十進位形式 （例如 45%) `0.45` 提供的產品收入百分比。
+ **`EffectiveDate`** — 此配置生效的行事曆日期。格式：`YYYY-MM-DD`。

回應會傳回配置的 `Id`（格式 `mrsa-[A-Za-z0-9]{13}`)、配置狀態 (`ACTIVE` 建立時） 和父共享的凹凸 `Version`（每個配置變動都會凹凸，用於後續配置更新的樂觀鎖定）。

### 更新配置
<a name="updating-marketplace-revenue-share-allocations"></a>

合作夥伴可以使用 `UpdateMarketplaceRevenueShareAllocation` API 動作更新配置。可更新的欄位取決於配置是未來日期、目前有效還是過去日期。

更新配置時，合作夥伴必須提供：
+ **`Catalog`** — `AWS`或 `Sandbox`。
+ **`MarketplaceRevenueShareIdentifier`** — 父共享的識別符。
+ **`AllocationId`** — 要更新的配置 `mrsa-` ID。
+ **`MarketplaceRevenueShareVersion`** — 配置上樂觀鎖定的父共用的目前版本。碰撞衝突會傳回 `ConflictException`。

合作夥伴可以選擇性地提供：
+ **`RevenueSharePercent`** — 已更新的收入共享百分比。只能對未來日期的配置進行編輯。
+ **`EffectiveDate`** — 更新的生效日期。只能對未來日期的配置進行編輯。
+ **`ExpirationDate`** — 更新的過期日期。可在未來日期的配置 （任何值 `> EffectiveDate`) 和目前有效或開放式配置 （任何值 ) 上編輯`≥ today`。
+ **`Status`** — `ACTIVE`或 `INACTIVE`。設定為 `INACTIVE` 軟刪除配置。只能對未來日期的配置進行編輯。
+ **`ClientToken`** — 等冪符記。

### 檢視 Marketplace 收入共享詳細資訊
<a name="viewing-marketplace-revenue-share-details"></a>

合作夥伴可以使用 `GetMarketplaceRevenueShare` API 動作擷取單一 Marketplace Revenue Share 的完整資訊。這會傳回共用的 `Arn`、`Catalog`、`ProductId`、 `Version`（父共用的目前版本）`LastModifiedDate`、、 `CreatedDate`和套用至共用的任何標籤。

合作夥伴可以使用 `GetMarketplaceRevenueShareAllocation` API 動作搭配配置的 來擷取單一配置`Id`。將傳回 。
+ 配置的 `Id`和父共享的 `MarketplaceRevenueShareArn`。
+ `RevenueSharePercent`, `EffectiveDate`, `ExpirationDate`.
+ `Status` (`ACTIVE` 或 `INACTIVE`)。
+ 父共享在後續更新上`MarketplaceRevenueShareVersion`樂觀鎖定的 。
+ `CreatedDate` 與 `LastModifiedDate`。

### 列出 Marketplace 收入共享
<a name="listing-marketplace-revenue-shares"></a>

合作夥伴可以使用 `ListMarketplaceRevenueShares` API 動作檢視其帳戶擁有的所有 Marketplace 營收共享。這會傳回共享摘要的分頁清單。

合作夥伴可以依下列條件篩選結果：
+ **`Catalog`** — `AWS`或 `Sandbox`（必要）。
+ **`ProductIds`** — 要擷取的特定 Marketplace IDs 清單。

回應包含每個共享的摘要：`Arn`、`Catalog`、`ProductId`、最新 `Version`、 `CreatedDate`和 `LastModifiedDate`。

使用 `MaxResults`和 `NextToken`來分頁大型結果集。

### 列出配置
<a name="listing-marketplace-revenue-share-allocations"></a>

合作夥伴可以使用 `ListMarketplaceRevenueShareAllocations` API 動作列出特定 Marketplace Revenue Share 的配置。這會傳回具有篩選功能的配置摘要分頁清單。

合作夥伴可以依下列條件篩選結果：
+ **`Status`** — `ACTIVE`或 `INACTIVE`。
+ **有效日期範圍** — `EffectiveDateOnOrAfter` / `EffectiveDateOnOrBefore` 可擷取有效日期落在特定時段內的配置。

回應包含每個配置的摘要資訊：`Id`、`RevenueSharePercent`、`EffectiveDate`、`MarketplaceRevenueShareVersion`、、 `ExpirationDate` `Status`和稽核時間戳記。

## 標記 Marketplace 營收份額
<a name="tagging-marketplace-revenue-shares"></a>

Marketplace Revenue Share 資源支援標準AWS標記操作：
+ **`TagResource`** — 在 Marketplace Revenue Share 上新增或覆寫標籤。每個共用最多 50 個標籤。
+ **`UntagResource`** — 依金鑰移除特定標籤。
+ **`ListTagsForResource`** — 擷取目前套用至 Marketplace 收入共享的所有標籤。

配置不支援標籤。標記父共用以組織相關配置。

每個標記操作都會接受共享的 `Arn`（格式 `arn:{partition}:partnercentral:{region}:{account-id}:catalog/{catalog}/marketplace-revenue-share/{productId}`) 作為資源識別符。也支援透過 上的 `Tags` 欄位建立 Standard AWS tag-on-create`CreateMarketplaceRevenueShare`。