已重組 AWS Marketplace API 參考。如需支援的 API 操作的詳細資訊，請參閱 AWS Marketplace API 參考。

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

以買方身分使用協議 API

協議是可約束雙方的文件，包括提案者和接受者 （通常為買方），並定義他們之間適用的條款和條件。

買方會建立產生引號的 AgreementRequest。此引號包含所有相關資訊，例如在協議生命週期內產生的預估費用，這對於買方的購買決策至關重要。如果買方對引號感到滿意，他們可以在過期之前接受 AgreementRequest。協議會在接受 AgreementRequest 時建立。在此過程中，買方管理員或買方角色可以將採購訂單與費用產生關聯。最後，根據作用中協議的條款與條件，會向買方開立發票，並授予使用產品的授權。

先決條件：探索 產品和優惠

建立協議之前，請使用 AWS Marketplace Discovery API 探索產品，並取得建構 所需的 agreementProposalId、 pricingModel和 詞彙詳細資訊CreateAgreementRequest。

如需探索產品和定價的詳細資訊，請參閱 探索產品和定價。

接受者可以使用此 API 執行下列任務：

產生引號

使用 CreateAgreementRequest產生引號。您必須提供：

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='NEW',
    requestedTerms=[
        {'id': 'term-legal-abc123'},
        {'id': 'term-validity-def456'},
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 50}
                    ]
                }
            }
        },
        {
            'id': 'term-renewal-012',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")
for charge in response['chargeSummary']['expectedCharges']:
    print(f"  Charge ID: {charge['id']}, Amount: ${charge['amount']}")

建構 requestedTerms

若要建構 requestedTerms，您需要判斷兩件事：

定價模式的必要條款

GetOffer 回應中的 pricingModel.PricingModel 欄位會決定哪些詞彙必須包含在您的 中CreateAgreementRequest。

當優惠中存在時，下列條款必須包含在每個協議中：LegalTerm、ValidityTerm、 SupportTerm和 RenewalTerm。

合約

GetOfferTerms 傳回的所有詞彙都需要在單一 中CreateAgreementRequest。

用量

協議建立取決於優惠中存在的條款：

BYOL

接受 ByolPricingTerm以及強制性條款。

術語組態

大多數術語只需要 id GetOfferTerms 中的 。除了 configuration之外，以下術語類型還需要買方提供的 id：

ConfigurableUpfrontPricingTermConfiguration

使用以下範例來尋找 所需的值ConfigurableUpfrontPricingTermConfiguration。

GetOfferTerms 回應範例：

{
  "offerTerms": [
    {
      "configurableUpfrontPricingTerm": {
        "id": "term-34dfb665ebd38eb2d0269a4af454c4f33cd90292ecc7b0f71058175594f67394",
        "currencyCode": "USD",
        "rateCards": [
          {
            "constraints": {
              "multipleDimensionSelection": "Allowed",
              "quantityConfiguration": "Allowed"
            },
            "selector": {
              "type": "Duration",
              "value": "P1M"
            },
            "rateCard": [
              {
                "dimensionKey": "BasicService",
                "displayName": "Basic Service",
                "price": "0",
                "unit": "Units"
              },
              {
                "dimensionKey": "PremiumService",
                "displayName": "Premium Service",
                "price": "0",
                "unit": "Units"
              }
            ]
          }
        ],
        "type": "ConfigurableUpfrontPricingTerm"
      }
    }
  ]
}

的範例RequestedTerm承載ConfigurableUpfrontPricingTerm：

{
  "id": "term-43ab7a2445f89dfcb7e1a6a81c92fe08c124125ffad126bea5e5b7915c065166",
  "configuration": {
    "configurableUpfrontPricingTermConfiguration": {
      "selectorValue": "P12M",
      "dimensions": [
        {
          "dimensionKey": "AdminUsers",
          "dimensionValue": 5
        },
        {
          "dimensionKey": "ReadOnlyUsers",
          "dimensionValue": 10
        }
      ]
    }
  }
}

RenewalTermConfiguration

的範例RequestedTerm承載RenewalTerm：

{
  "id": "term-ffcc0100ce0c5468426dc07d0b05cff09ab8447640108d9c95ce1591f0949738",
  "configuration": {
    "renewalTermConfiguration": {
      "enableAutoRenew": false
    }
  }
}

VariablePaymentTermConfiguration

的範例RequestedTerm承載VariablePaymentTerm：

{
  "id": "term-9ab34376c51cd5b4dc995aa0f410b657d58bd577b3f09b34d38afb6964aaaf12",
  "configuration": {
    "variablePaymentTermConfiguration": {
      "paymentRequestApprovalStrategy": "AUTO_APPROVE_ON_EXPIRATION",
      "expirationDuration": "P10D"
    }
  }
}

接受優惠

首先，產生引號，如 中所述產生引號。然後，使用 AcceptAgreementRequest接受引號並建立協議。您必須在協議請求過期AcceptAgreementRequest之前呼叫 。您可以在接受期間選擇性地建立採購訂單號碼的關聯。

# Use chargeId from CreateAgreementRequest response
response = client.accept_agreement_request(
    agreementRequestId='agrq-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',  # From chargeSummary.expectedCharges[].id
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

print(f"Agreement ID: {response['agreementId']}")

取代現有的協議

CreateAgreementRequest 如中所述建構 產生引號，但intent將 設定為 REPLACE，並提供替換sourceAgreementIdentifier協議。然後呼叫 AcceptAgreementRequest 以完成替換。

response = client.create_agreement_request(
    agreementProposalIdentifier='at-edhtjnbilupjv3xqbphtom77y',
    intent='REPLACE',
    sourceAgreementIdentifier='agmt-existing123'
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

修改現有協議

若要修改現有協議上的期限組態，intent請將 設定為 AMEND並提供 sourceAgreementIdentifier。與新協議不同，agreementProposalIdentifier不需要 。僅包含您要變更其組態的詞彙。然後呼叫 AcceptAgreementRequest以套用修訂。

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-configurable-pricing-789',
            'configuration': {
                'configurableUpfrontPricingTermConfiguration': {
                    'selectorValue': 'P12M',
                    'dimensions': [
                        {'dimensionKey': 'Users', 'dimensionValue': 100}
                    ]
                }
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

啟用或停用自動續約

使用 CreateAgreementRequest搭配 AMEND 意圖來切換自動續約。

response = client.create_agreement_request(
    intent='AMEND',
    sourceAgreementIdentifier='agmt-existing123',
    requestedTerms=[
        {
            'id': 'term-renewal-456',
            'configuration': {
                'renewalTermConfiguration': {'enableAutoRenew': True}
            }
        }
    ]
)

print(f"Agreement Request ID: {response['agreementRequestId']}")

取消協議

使用 CancelAgreement取消用量協議。對於其他協議類型，買方必須聯絡賣方以啟動取消。

client.cancel_agreement(
    agreementId='agmt-abc123'
)

搜尋協議

使用 SearchAgreements 搜尋您以接受者身分參與的所有協議。搜尋會傳回包含基本協議資訊的協議清單。

response = client.search_agreements(
    catalog='AWSMarketplace',
    filters=[
        {'name': 'PartyType', 'values': ['Acceptor']},
        {'name': 'AgreementType', 'values': ['PurchaseAgreement']},
        {'name': 'Status', 'values': ['ACTIVE']}
    ]
)

for agmt in response['agreementViewSummaries']:
    print(f"  {agmt['agreementId']}: {agmt['status']}")

描述協議

使用 DescribeAgreement 檢視協議的詳細資訊，例如提案者、接受者、開始日期和結束日期。

response = client.describe_agreement(
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Start: {response['startTime']}")
print(f"End: {response['endTime']}")

取得協議條款

使用 GetAgreementTerms 取得您以接受者身分參與協議中條款的詳細資訊。

response = client.get_agreement_terms(
    agreementId='agmt-abc123'
)

for term in response['acceptedTerms']:
    print(f"  Term: {term}")

取得協議權利

使用 GetAgreementEntitlements取得與您協議相關的權利狀態和詳細資訊的協議層級檢視。

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    print(f"  {ent['resource']}: {ent['status']}")

取得註冊字符

使用 GetAgreementEntitlements取得註冊字符。接受者需要此短期字符 （有效期為 30 分鐘） 才能設定提案者帳戶。目前僅適用於 SaaS 購買協議。

response = client.get_agreement_entitlements(
    agreementId='agmt-abc123'
)

for ent in response['agreementEntitlements']:
    if 'registrationToken' in ent:
        print(f"Registration Token: {ent['registrationToken']}")
        # Token is valid for 30 minutes

列出協議費用

使用 ListAgreementCharges 來檢視與您協議相關聯的費用和採購訂單詳細資訊。

response = client.list_agreement_charges(
    agreementId='agmt-abc123'
)

for charge in response['items']:
    print(f"  {charge['id']} (rev {charge['revision']}): ${charge['amount']}")
    print(f"  PO: {charge.get('purchaseOrderReference', 'N/A')}")

更新採購訂單

UpdatePurchaseOrders 用於在訂閱產品後新增採購訂單號碼。使用列出協議費用回應中的 chargeId和 chargeRevision 。一旦採購訂單與費用相關聯，針對該費用產生的發票就會包含採購訂單號碼。

client.update_purchase_orders(
    agreementId='agmt-abc123',
    purchaseOrders=[
        {
            'chargeId': 'charge-xyz',
            'chargeRevision': 1,
            'purchaseOrderReference': 'PO-2024-001'
        }
    ]
)

列出取消請求

使用 ListAgreementCancellationRequests 列出您參與協議的所有取消請求。您可以依協議、狀態和其他條件進行篩選。

response = client.list_agreement_cancellation_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementCancellationRequests']:
    print(f"  {req['agreementCancellationRequestId']}: {req['status']}")

取得取消請求詳細資訊

使用 GetAgreementCancellationRequest擷取特定取消請求的詳細資訊，包括狀態、時間戳記和原因代碼。

response = client.get_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

print(f"Status: {response['status']}")
print(f"Reason: {response['reasonCode']}")

接受取消請求

使用 AcceptAgreementCancellationRequest 核准賣方啟動的取消請求。核准後，協議取消工作流程會以非同步方式執行。您也需要CancelAgreement許可，因為核准取消請求會導致協議取消。

client.accept_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

拒絕取消請求

使用 RejectAgreementCancellationRequest 拒絕賣方啟動的取消請求。拒絕後，協議會保持作用中狀態，如有需要，賣方可以建立新的取消請求。

client.reject_agreement_cancellation_request(
    agreementId='agmt-abc123',
    agreementCancellationRequestId='acr-abc123'
)

列出付款請求

使用 ListAgreementPaymentRequests 列出您參與協議的所有付款請求。您可以依協議、狀態和其他條件進行篩選。

response = client.list_agreement_payment_requests(
    partyType='Acceptor',
    agreementId='agmt-abc123'
)

for req in response['agreementPaymentRequests']:
    print(f"  {req['agreementPaymentRequestId']}: {req['status']}")

取得付款請求詳細資訊

使用 GetAgreementPaymentRequest擷取特定付款請求的詳細資訊，包括狀態、時間戳記和相關費用。

response = client.get_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

print(f"Status: {response['status']}")
print(f"Amount: ${response['amount']}")

接受付款請求

使用 AcceptAgreementPaymentRequest 核准賣方針對作用中協議啟動的付款請求。

client.accept_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)

拒絕付款請求

使用 RejectAgreementPaymentRequest 拒絕賣方啟動的付款請求。拒絕後，賣方可以視需要建立新的付款請求。

client.reject_agreement_payment_request(
    paymentRequestId='apr-abc123',
    agreementId='agmt-abc123'
)