View a markdown version of this page

使用營收歸因 IDs - AWS Partner Central
什麼是營收歸因 ID？使用營收歸因 IDs

AWS 合作夥伴中心 API 參考已重組。如需支援的 API 操作的詳細資訊，請參閱 AWS 合作夥伴中心 API 參考。

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

使用營收歸因 IDs

收入歸因 ID 是交易層級識別符，可將您的AWS Marketplace 產品收入映射至特定的AWS Marketplace 優惠和/或AWS合作夥伴中心機會。它以產品層級的合作夥伴收入衡量 (PRM) 實作為基礎：PRMS 會擷取 Marketplace 產品的總歸屬收入，而收入歸屬 ID 會根據您指定的每月成本分配百分比，將收入映射到特定交易。

Revenue Attribution Service 公開 APIs 以建立、擷取、列出和更新營收屬性 IDs，並以非同步方式管理其每月成本分配項目。

什麼是營收歸因 ID？

營收歸因 ID 有兩個層級：

  • 由ra-字首 ID （例如，ra-aabbccddee001) 和 ARN 識別的合作夥伴命名、合作夥伴描述資源的屬性。每個屬性的範圍都限定為 Catalog(AWS 用於生產、Sandbox測試） 和合作夥伴的 帳戶。

  • 每個項目的一或多個每月成本分配項目會將單一 （優惠 ID 或機會 ID、帳單月） 組合映射至成本分配百分比。項目會透過配置任務模式以非同步方式批次管理。

營收歸因 ID 有兩種使用方式：

  • 作為現有產品層級 PRM 實作上的交易層級浮水印。建立營收歸因 ID、將適用的 Marketplace 優惠和/或 ACE 機會建立關聯，並將您已衡量的產品營收AWS對應至這些特定交易，無需變更現有的資源標籤或使用者代理程式字串。

  • 作為獨立識別符，直接用作資源標籤值 (aws-apn-id = <RA ID>) 或在使用者代理程式字串 (APN_1.1/pc_<RA ID>$) 中，從一開始就將AWS耗用量歸因於特定交易。

使用營收歸因 IDs

合作夥伴可以透過營收歸因服務管理營收歸因 IDs 及其每月成本分配項目。生命週期會進行兩個獨立的流程：屬性記錄流程 （建立、更新、擷取、列出） 和配置流程 （啟動批次任務、輪詢結果、擷取個別項目、列出屬性的項目）。

建立營收屬性 ID

第一步是使用 CreateRevenueAttribution API 動作建立營收歸因 ID。傳回的 Id和 Arn 可立即用作資源標籤值，或在使用者代理程式字串中使用屬性AWS。

建立營收歸因 ID 時，合作夥伴必須提供：

  • Catalog — AWS Sandbox用於生產或測試。

  • Name — 屬性的人類可讀取名稱。在目錄和合作夥伴的帳戶中必須是唯一的。最多 128 個字元。

合作夥伴可以選擇性地提供：

  • Description — 屬性的任意文字描述。最多 1024 個字元。

  • MarketplaceProduct —AWS要與此屬性建立關聯的 Marketplace 產品。提供 ProductIdentifier(25 個字元的 Marketplace 產品 ID) 和 TenancyModel(MULTI_TENANT 或 SINGLE_TENANT)。如果在建立時省略，則無論客戶購買的 Marketplace 產品為何，歸因適用於營收歸因 ID 下測量的所有消耗，當單一部署跨越多個 Marketplace 清單時很有用。

  • Tags — 資源組織最多 200 個鍵值對。標籤索引鍵在請求中必須是唯一的。

最佳實務：每當您的交易錨定至特定 Marketplace 清單MarketplaceProduct.ProductIdentifier時提供 。這可讓AWS驗證產品是否由呼叫的合作夥伴帳戶或透過合作夥伴帳戶連線 (PAC) 連線的分公司帳戶所擁有，並在回應中顯示已解決的 SaaSProductCode和 ProductType（例如，AMI、ML)。如果產品不是授權帳戶所擁有，API 會傳回ValidationException原因為 PRODUCT_NOT_FOUND_OR_NOT_OWNED。

回應會傳回新的 Id（格式 ra-[a-z0-9]{13})、Arn、已解析的MarketplaceProduct屬性和初始Version數字 （從 1 開始，每次後續更新時遞增）。

新增每月成本分配項目

建立營收歸因 ID 後，合作夥伴會透過 StartRevenueAttributionAllocationsTask API 動作提交一批每月成本分配項目，將AWS Marketplace 優惠和/或 ACE 機會與其建立關聯。這是一個非同步操作，每個任務最多可接受 250 個配置變更 (CREATE 和/或 UPDATE)。

每個配置項目指定：

  • 優惠 ID 或機會 ID — 與交易相關聯的唯一識別符。如果 Marketplace 優惠已連結至 ACE 機會，合作夥伴只需要提供優惠 ID；AWS自動將收入歸納至連結的機會。

  • 帳單月份 — 套用成本分配的行事曆月份 （例如 2026-04)。

  • 成本分配 % — 此計費月份中可歸因於此交易的產品總AWS耗用量部分。多租戶 SaaS 產品的必要項目，包括客戶共用基礎設施的混合部署合作夥伴託管元件。

  • 客戶AWS帳戶 ID — 取用產品的客戶AWS帳戶。多租用戶 SaaS 產品需要。

指定營收歸因 ID 和相同帳單月份之所有配置項目的總成本分配 % 不得超過 100%。如果總計超過 100%，違規項目會在非同步業務驗證期間，以每筆記錄錯誤碼拒絕。

同步驗證： 會同步StartRevenueAttributionAllocationsTask執行基本形狀驗證 （欄位類型、模式、批次大小）。如果基本驗證通過，API 會傳回狀態TaskId為 的 IN_PROGRESS。業務驗證 （上限檢查、不可變性規則、針對 Marketplace 和 ACE 的相依性查詢） 會以非同步方式執行，並透過 探索每個記錄的結果GetRevenueAttributionAllocationsTask。

若要監控提交的任務，合作夥伴GetRevenueAttributionAllocationsTask會使用營收歸因資源 ID 或 ARN 輪詢。回應會從 進展IN_PROGRESS至 COMPLETED（無論個別記錄成功或失敗） 並傳回：

  • TaskStatus — IN_PROGRESS、 COMPLETED或 FAILED（最上層任務失敗）。

  • RecordResults — 針對每個輸入記錄：指派的 AllocationId（如果成功）、每個記錄的狀態 (SUCCEEDED 或 FAILED)，以及記錄失敗時的結構化錯誤代碼和訊息。

合作夥伴應該立即擷取任務結果。任務完成後，每個記錄的結果可以進行對帳，並且可以在新任務中更正和重新提交任何失敗的項目。

編輯每月成本分配項目

成本分配項目會依計費月份管理，規則如下：

  • 合作夥伴可以隨時為目前或任何未來計費月份新增每月項目。

  • 合作夥伴可以隨時更新目前或未來任何計費月份的每月項目。

  • 合作夥伴可以更新上個月的項目，直到當月 7 日為止。此時段允許合作夥伴在AWS Cost Explorer 中檢閱實際用量，然後再完成上個月的配置。

在當月 7 日之後，無法再修改上一個計費月份的屬性。更新目前或未來月份的項目會從下一個每月帳單週期開始套用。前幾個月的歷史屬性不會追溯重新計算。

配置項目的更新會透過相同的 StartRevenueAttributionAllocationsTask API 動作提交，UPDATE並針對每個受影響的項目將 Operation 設定為 。非同步任務模式會統一處理更新和建立。

更新營收歸因 ID

合作夥伴可以使用 UpdateRevenueAttribution API 動作更新Description現有營收歸因 ID 的 。屬性記錄本身不可變 — Name、 MarketplaceProduct和tag-on-create值無法在建立後變更。若要重新標記資源，請在屬性的 ARN 上使用標準AWS標記操作。

更新營收歸因 ID 時，合作夥伴必須提供：

  • Catalog — AWS或 Sandbox。

  • Identifier — 要更新的屬性 ra- ID。

  • Version — 目前版本的屬性，用於樂觀鎖定。

合作夥伴可以選擇性地提供：

  • Description — 更新的任意文字描述。最多 1024 個字元。

  • ClientToken — 用於更新的等冪符記。

樂觀鎖定： Version 欄位可確保只有在屬性自上次擷取以來未變更時，才會套用更新。如果提交的 Version 不符合目前的資源版本，則會使用 拒絕更新，ConflictException並顯示包含提交和目前版本編號的訊息。最佳實務是在每次更新GetRevenueAttribution之前，使用 擷取最新版本。

檢視營收歸因 ID 詳細資訊

合作夥伴可以使用 GetRevenueAttribution API 動作擷取單一營收歸因 ID 的完整資訊。將傳回 。

資源中繼資料：

  • 唯一識別碼 (Id) 和 Amazon Resource Name (Arn)。

  • 屬性Catalog所在的 。

  • Name 與 Description。

  • 擷取的 Version和 LatestVersion（使用最新的 進行後續更新）。

Marketplace 產品屬性 （如果MarketplaceProduct在建立時設定）：

  • ProductId — 合作夥伴提供的 Marketplace 產品 ID。

  • ProductCode — 從 解析的AWS Marketplace 產品程式碼ProductId。

  • ProductType — SaaS、AMI、Container、Data、 ML或 Professional Services。

  • TenancyModel — MULTI_TENANT或 SINGLE_TENANT。

稽核資訊：

  • CreatedDate 與 LastModifiedDate。

合作夥伴可以選擇在請求Version中提供特定 ，以擷取屬性的歷史版本。省略 Version 以傳回最新的 。

若要擷取特定的每月成本分配項目，合作夥伴會使用 GetRevenueAttributionAllocation API 動作搭配項目的 AllocationId。這會傳回優惠 ID 或機會 ID、帳單月份、成本分配 %、客戶AWS帳戶 ID，以及項目的狀態和稽核資訊。

列出營收歸因 IDs

合作夥伴可以使用 ListRevenueAttributions API 動作檢視其帳戶中的所有營收歸因 IDs。這會傳回具有篩選和排序功能的屬性摘要分頁清單。

合作夥伴可以依下列條件篩選結果：

  • Catalog — AWS或 Sandbox（必要）。

  • Identifiers — 最多可擷取 100 個特定 ra- ID 的清單。 IDs

  • CreatedAfter / CreatedBefore — 依建立時間戳記範圍 （包含） 篩選。

合作夥伴可以使用 Sort 參數設定結果排序：

  • SortBy — CreatedDate或 LastModifiedDate。

  • SortOrder — ASCENDING或 DESCENDING。

回應包含每個屬性的摘要：Arn、Id、Catalog、Name、已解析MarketplaceProduct屬性、CreatedDate、LastModifiedDate、最新 Version和 TotalRevenueAttributionAssociationCount（連結至屬性的作用中每月成本分配項目數量）。

使用 MaxResults（預設值 25，上限為 100) 和 NextToken來分頁大型結果集。NextToken 如果有其他頁面可用，回應會包含 。

列出每月成本分配項目

合作夥伴可以使用 ListRevenueAttributionAllocations API 動作列出特定營收歸因 ID 的每月成本分配項目。這會傳回具有篩選功能的配置摘要分頁清單。

合作夥伴可以依下列條件篩選結果：

  • MarketplaceOfferId — 僅列出與特定 Marketplace 優惠相關聯的項目。

  • AwsPartnerCentralOpportunityId — 僅列出與特定 Partner Central Opportunity 相關聯的項目。

  • BillingMonth — 僅列出特定日曆月的項目。

回應包含每個項目的摘要資訊：AllocationId、相關聯的優惠 ID 或機會 ID、客戶AWS帳戶 ID、帳單月份、成本分配 %、項目的名稱和狀態，以及稽核時間戳記。

儀表板建置： ListRevenueAttributions和 的組合ListRevenueAttributionAllocations旨在支援合作夥伴儀表板的建立。合作夥伴可以建立檢視，例如：

  • 過去 30 天內建立的所有營收歸因 IDs，依建立日期排序。

  • 跨多個營收歸因 IDs 的特定 Marketplace 優惠的所有每月成本分配項目。

  • 目前計費月份的所有成本分配項目，以驗證每個屬性總計不超過 100%。

  • 至少有一個作用中配置項目 () 的所有營收歸因 IDsTotalRevenueAttributionAssociationCount > 0。