collections.mp.microsoft.com/v8.0/collections/consume

[アーティクル]
06/20/2024

この消費 API は、Microsoft Store 内の次の種類の消費型製品の管理に使用できます。

Microsoft Store によって管理される消費型アイテム: 数量を消費済みとして報告し、特定のユーザーの現在の残量から削除します。ユーザーは、Microsoft Store によって管理される消費型アイテムを、サービスで消費済みまたはフルフィルメント完了として報告することなく、繰り返し再購入することができます。詳細については、「Store 管理の消費要求」を参照してください。
開発者によって管理される消耗品アイテム: 特定のユーザーについて消費型製品をフルフィルメント完了として報告します。開発者によって管理される消耗品アイテム製品を再購入するには、アプリまたはサービスが、そのユーザーについて消費型製品をフルフィルメント完了と報告している必要があります。詳細については、「開発者管理の消費要求」を参照してください。

trackingId を使用してフルフィルメントの完了を検証する

サービスで確認を受け取れない場合、フルフィルメント要求が成功したことを検証するための冗長性チェックとして trackingId が使用されます。サービスで、確認応答を取得できない状態が発生した場合は、同じ要求本文 (追跡 ID を含む) で要求を再送信して、その消費型のゲーム内アイテムを許可する前にフルフィルメントが成功したことの確認を受け取ることができます。

消費要求ごとに、一意の追跡 ID が必要です。これは常にそれが生成された消費要求に関連付けられており、検証のために無限に再送信できます。消費が要求を取得しなかった場合、またはフルフィルメントが完了しなかった場合、サービスは要求されたトランザクションを通常どおりに完了します。前の要求でフルフィルメントが完了した場合、同じ値と trackingId が使用されるため、消費はこれを確認要求として認識します。この場合、消費は、ユーザーの残高から数量を再びフルフィルメントまたは差し引きすることはありません。代わりに、消費サービスは、消費が発生した場合と同じ形式で成功応答を送信し、現在の残高を送り返します。

したがって、要求が完了したことを示す確認応答を受信するまで、サーバーまたはログにキャッシュされた各要求の値と trackingId を保持しておくことが推奨されます。例については、「ゲームサービスのサンプル」を参照してください。

再試行リクエストで includeOrderIds パラメータを使用すると、製品の消費可能なタイプに基づいて次のことが発生します

消費型アイテムタイプ	最初の消費要求の動作	消費要求の動作を再試行
ストアの管理対象	返された消費要求を満たすために使用された注文の ID	返された消費要求を満たすために使用された注文の同じ ID
開発者管理	返された消費要求を満たすために使用される注文の ID	この製品タイプの消費後にこのデータは追跡されないため、ID は返されません

したがって、開発者が管理する消費型アイテムを使用している場合、呼び出しが消費されたことを確認するための再試行チェックである場合、フルフィルメントの注文 ID 情報を取得できないことに注意してください。

前提条件

この API を使用するには、次のいずれかの認証の種類を使用する必要があります。

証明書利用者用の代理認証 XSTS トークン http://licensing.xboxlive.com
対象ユーザーの URI 値 https://onestore.microsoft.com を持つ Microsoft Entra ID アクセストークンを含む Microsoft Store ID キー

詳細については、「Microsoft Store API によるサービスの認証」をご覧ください。

さらに、サービスに表示する製品には、サービスがコレクションサービスの呼び出しに使用している認証の種類に基づいて、パートナーセンターで追加の構成が必要です。パートナーセンターで製品を適切に構成する方法については、次を参照してください:

ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成
 代理認証XSTS トークンを使用して製品を表示および管理するために必要な追加構成

注意

製品構成がパートナーセンター経由で実行および公開されていない場合、コレクションの呼び出しは成功しますが、応答に結果はありません。

ユーザー Store ID 認証エラーコード

コード	エラー	内部エラーコード	説明
401	未承認	AuthenticationTokenInvalid	Microsoft Entra ID アクセストークンが無効です。場合によっては、`ServiceError` の詳細に追加情報が含まれていることがあります (トークンの有効期限切れや `appid` 要求の欠落など)。
401	未承認	PartnerAadTicketRequired	Microsoft Entra ID アクセストークンが承認ヘッダーでサービスに渡されませんでした。
401	未承認	InconsistentClientId	要求本文の Microsoft Store ID の `clientId` 要求と Authorization ヘッダーの Microsoft Entra ID アクセストークンの `appid` 要求が一致しません。

XSTS トークン認証を使用したエラーコード

コード	エラー	内部エラーコード	説明
401	未承認	期限切れのトークン	XSTS トークンの有効期限が切れ、呼び出しを完了するために新しいトークンが必要になります。
403	未承認	無効なトークン	使用済みトークンには、このエンドポイントで認証する権限がありません。トークンのサンドボックスまたは証明書利用者が間違っている可能性があります。
429	Throttled	頻繁な呼び出し	指定された呼び出しの制限内で、サービスがユーザーに対して呼び出された回数が多すぎます。サービスがこのユーザーに対して別の呼び出しを行うことができるタイミングの詳細については、応答を参照してください。

要求

要求の構文

メソッド	要求 URI
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/consume`

要求ヘッダー

ヘッダー	型	説明
`Authorization`	`string`	必須。使用されている認証の種類に基づく代理承認 XSTS トークンまたは Microsoft Entra ID アクセストークン。
`Signature`	`string`	XSTS トークンを使用して認証する場合に必要です。ユーザー Store ID 認証には必要ありません。
`User-Agent`	`string`	省略可能ですが、推奨されます。ログと調査のためにサービスを識別するのに役立ちます。
`Host`	`string`	値 `collections.mp.microsoft.com` を設定する必要があります。
`Content-Length`	`number`	要求本文の長さ。
`Content-Type`	`string`	要求と応答の種類を指定します。現在唯一サポートされている値は `application/json` です。

リクエストの本文

パラメーター	型	説明	必須
`beneficiary`	`UserIdentity`	このアイテムが消費されているユーザー。詳細については、「PC タイトルのユーザー Store ID による認証」を参照してください。 XSTS トークン認証には不要です。	ユーザー Store ID 認証に対してのみ
`trackingId`	`guid`	冗長性チェックのために開発者により指定される一意の追跡 ID。 GUID は、要求ごとに一意である必要があります。詳細については、「trackingId を使用してフルフィルメントの完了を検証する」を参照してください。	はい
`productId`	`string`	要求の対象となる消費型の `productId`。パートナーセンターから、またはサービスによりユーザーの製品と権利を照会することで取得できます。	はい
`removeQuantity`	`int`	消費型のユーザーの数量/残高から消費する数量。	Microsoft Store によって管理される消費型アイテムのみ
`includeOrderIds`	`bool`	この消費要求を満たすために使用される注文の OrderIds と LineItemIds を含めます。これらの値は、Clawback イベントサービスの結果と共に使用して、ゲームサービスで払い戻された消費トランザクションを識別できます。	いいえ
`sbx`	`string`	結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。この値のない既定値は RETAIL サンドボックスです。サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。	いいえ

消費要求の例

次の例では、認証のためにユーザー Store ID を使用しており、要求の JSON 本文に beneficiary オブジェクトが必要です。

Store によって管理される消費型アイテム要求

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identitytype": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}

開発者によって管理される消費型アイテム要求

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identitytype": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}

応答

応答の本文

パラメーター	型	説明	必須
`itemId`	string	ユーザーが所有する他の項目からこのコレクション項目を識別する ID。この ID は製品ごとに一意です。	はい
`productId`	`string`	Microsoft Store カタログ内の製品の場合、Store ID とも呼ばれます。製品の Store ID の例は、9NBLGGH42CFD です。	はい
`trackingId`	`GUID`	この消費要求に対して発信者によって提供された一意の追跡 ID。	はい
`newQuantity`	`int`	この消費型アイテムのユーザーの残高の残りの数量。開発者が管理する消費型アイテムの場合、これは常に 0 になります。	はい
`orderTransactions`	`List<ConsumeOrderTransaction>`	消費要求の処理に使用される注文を示す ConsumeOrderTransaction オブジェクトの配列。これは、リクエストで includeOrderIds パラメーターが true に設定されている場合にのみ返されます。詳細については、後の表を参照してください。	いいえ

ConsumeOrderTransaction オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	説明	必須
`orderId`	`GUID`	この消費要求の全部または一部を満たすために使用されるユーザーの発注書の ID。	はい
`orderLineItemId`	`GUID`	消費型アイテムの広告申込情報は、ユーザーが作成した発注書の範囲内でした。この IDは、注文 ID ごとに複数のラインアイテム ID が存在する可能性があるため、Order ID よりも消費型アイテムの購入に固有のものです。	はい
`quantityConsumed`	`int`	この特定の OrderId / LineItemId によって実行された消費要求の量	はい

消費応答の例

HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}

サービスから製品を管理する

Microsoft Store API によるサービスの認証

PublisherQuery (コレクション v9) を使用してユーザーの製品と資格を照会する

サービスから消費型アイテムの製品を管理する

サービスからの払い戻しとチャージバックの管理

次の方法で共有

collections.mp.microsoft.com/v8.0/collections/consume

trackingId を使用してフルフィルメントの完了を検証する

前提条件

ユーザー Store ID 認証エラーコード

XSTS トークン認証を使用したエラーコード

要求

要求の構文

要求ヘッダー

リクエストの本文

消費要求の例

Store によって管理される消費型アイテム要求

開発者によって管理される消費型アイテム要求

応答

応答の本文

消費応答の例

その他のリソース

次の方法で共有

collections.mp.microsoft.com/v8.0/collections/consume

trackingId を使用してフルフィルメントの完了を検証する

前提条件

ユーザー Store ID 認証エラー コード

XSTS トークン認証を使用したエラー コード

要求

要求の構文

要求ヘッダー

リクエストの本文

消費要求の例

Store によって管理される消費型アイテム要求

開発者によって管理される消費型アイテム要求

応答

応答の本文

消費応答の例

関連トピック

その他のリソース

ユーザー Store ID 認証エラーコード

XSTS トークン認証を使用したエラーコード