AWS Marketplace API リファレンスが再構築されました。サポートされている API オペレーションの詳細については、AWS Marketplace API リファレンスを参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

購入者として契約 API を使用する

契約は、提案者とアクセプタ (通常は購入者) を含む 2 つの当事者を拘束し、両者間で適用される条件を定義するドキュメントです。

購入者は、見積りを生成する 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、次の 2 つの要素を決定する必要があります。

料金モデル別の必須条件

GetOffer レスポンスの pricingModel.PricingModelフィールドは、 に含める必要がある用語を決定しますCreateAgreementRequest。

オファーに含まれるすべての契約には、、LegalTerm、SupportTerm、ValidityTermおよび の条件を含める必要がありますRenewalTerm。

契約

GetOfferTerms によって返されるすべての用語は、単一の で必要ですCreateAgreementRequest。

の使用

契約の作成は、オファーに含まれる条件によって異なります。

BYOL

必須条件ByolPricingTermとともに承諾します。

用語設定

ほとんどの用語では、GetOfferTerms idの のみが必要です。以下の用語タイプには、 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']}")

自動更新を有効または無効にする

自動更新を切り替えるには、 インAMENDテントCreateAgreementRequestで を使用します。

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