AWS Marketplace API 参考已重组。有关支持的 API 操作的更多信息，请参阅 AWS Marketplace API 参考。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

以买家身份使用协议 API

协议是一种约束双方的文件，包括提议人和接受者（通常是买方），并定义了双方之间适用的条款和条件。

买方创建 AgreementRequest，生成报价。此报价包括所有相关信息，例如在协议有效期内将产生的估计费用，这对于买方的购买决定至关重要。如果买家对报价感到满意，他们可以在报价到期 AgreementRequest 之前接受。本协议是在接受后生效的 AgreementRequest。在此过程中，买家管理员或买家角色可以将采购订单与费用相关联。最后，根据有效协议的条款和条件，向买方开具发票并获得使用该产品的许可。

先决条件：发现产品和优惠

在创建协议之前，请使用 AWS Marketplace Discovery API 来发现产品并获取构建协议所需的agreementProposalIdpricingModel、和条款的详细信息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，你需要确定两件事：

按定价模式划分的必填条款

GetOffer回复中的pricingModel.PricingModel字段决定了您必须包含哪些术语CreateAgreementRequest。

每份协议中都必须包含以下条款：LegalTerm、SupportTermValidityTerm、和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中所述构建 a生成报价，但设置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用于在订阅产品后添加采购订单号。使用列出协议费用响应chargeRevision中的chargeId和。一旦采购订单与费用关联，为该费用生成的发票就会包含采购订单编号。

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'
)