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

Consume API を使用すると、次の Microsoft Store の消費型タイプを管理できます。

ストア管理の消費型: 消費された数量を報告し、指定したユーザーの現在の残高から削除します。ユーザーは、サービスが消費または消化済みとして報告することなく、ストア管理の消費型アイテムを繰り返し再購入できます。詳細については、「ストア管理の消費要求」を参照してください。
デベロッパー管理の消費型: 指定したユーザーの消費型製品を消化済みとして報告します。ユーザーがデベロッパー管理の消費型製品を再購入するには、アプリまたはサービスがそのユーザーに対して当該消費型製品を消化済みとして報告する必要があります。詳細については、「デベロッパー管理の消費要求」を参照してください。

`trackingId` を使用して消化完了を検証する

trackingId を使うと、再試行に安全な消化検証が行えます。サービスが確認応答を受信しない場合は、同じ要求本文を再送信してください。サービスは以前の要求を認識し、再試行を確認チェックとして扱います。 API への各要求には一意の trackingId を含める必要があります。元の要求が成功しなかった、または応答が受信されなかった場合、要求を再試行すると、サービスは要求されたトランザクションを完了します。消化が以前の要求で完了していた場合、API はその要求を認識し、確認応答を送信します。この場合、API はユーザーの残高から 2 回目の消化や差し引きを行いません。代わりに、API はアイテムが消費されたかのように、ユーザーの残余残高で成功応答を返します。したがって、要求が消化されたという確認応答を受け取るまで、各要求の値と trackingId をサーバー上またはログにキャッシュしてください。例については、「Game Service サンプル」を参照してください。要求に includeOrderIds パラメーターが含まれている場合、消費型製品タイプに応じて次の動作が想定されます。

消費型タイプ	初回の消費要求の動作	再試行の消費要求の動作
ストア管理	要求を消化するために使用された OrderIds が返されます	要求を消化するために使用された同じ OrderIds が返されます
デベロッパー管理	要求を消化するために使用された OrderIds が返されます	この製品タイプではこのデータが追跡されないため、OrderIDs は返されません

デベロッパー管理の消費型を使用する場合、再試行要求から注文 ID を取得することはできません。

前提条件

「サービス間 API の前提条件」を確認してください。この API は、Microsoft Entra ID と委任認証の X-token の両方の認証タイプをサポートします。

デベロッパー管理の消費型のサンドボックス制限: 開発サンドボックス (非 RETAIL) でデベロッパー管理の消費型製品を消費する場合、User Store ID や Microsoft Entra ID を使用した認証はサポートされていません。サンドボックス環境では、デベロッパー管理の消費型製品を正常に消費するために、委任認証の XSTS トークンを使用する必要があります。この制限は、ストア管理の消費型または RETAIL サンドボックスには適用されません。

パートナーセンターで製品構成を公開しない場合、呼び出しは成功する可能性がありますが、結果は返されません。

User Store ID 認証のエラーコード

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

X-token 認証を使用する場合のエラーコード

コード	エラー	内部エラーコード	説明
401	Unauthorized	Expired Token	X-token の有効期限が切れており、呼び出しを完了するために新しい X-token が必要です。
403	Unauthorized	Invalid Token	使用されているトークンは、このエンドポイントで認証する権限がありません。トークンが誤ったサンドボックスまたは証明書利用者向けの可能性があります。
429	Throttled	Too frequent calls	指定された呼び出し制限内で、そのユーザーに対してサービスが呼び出された回数が多すぎます。このユーザーに対してサービスを再度呼び出せる時期については応答を参照してください。

要求

要求の構文

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

要求ヘッダー

ヘッダー	型	説明
`Authorization`	`string`	必須。使用する認証タイプに基づき、委任認証の X-token または Microsoft Entra ID アクセストークンのいずれかです。
`Signature`	`string`	X-token で認証する場合に必須です。User Store ID 認証では不要です。
`User-Agent`	`string`	任意ですが推奨されます。ロギングや調査のためにサービスを識別するのに役立ちます。
`Host`	`string`	値 `collections.mp.microsoft.com` を設定する必要があります。
`Content-Length`	`number`	要求本文の長さ。
`Content-Type`	`string`	要求と応答の種類を指定します。現在サポートされているのは `application/json` のみです。

要求本文

パラメーター	型	説明	必須
`beneficiary`	`UserIdentity`	このアイテムが消費されるユーザー。詳細については、「Microsoft Entra ID と User Store ID による認証」を参照してください。X-token 認証では不要です。	User Store ID 認証の場合のみ
`trackingId`	`guid`	冗長性チェックのために開発者が提供する一意の `trackingId`。GUID は要求ごとに一意である必要があります。詳細については、「trackingId を使用して消化完了を検証する」を参照してください。	はい
`productId`	`string`	要求対象の消費型の `productId`。パートナーセンターから取得するか、「サービスからユーザーの製品と使用権を照会する」から取得できます。	はい
`removeQuantity`	`int`	ユーザーの現在の残高から消費する数量。	ストア管理の消費型にのみ適用されます。
`includeOrderIds`	`bool`	消費要求を消化するために使用された注文の OrderIds と LineItemIds を含めます。これらの値は、Clawback イベントサービスの結果と共に使用して、ゲームサービスで返金された消費トランザクションを識別できます。	いいえ
`sbx`	`string`	UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが X-Token 内で指定されるため、この値は不要です。注: デベロッパー管理の消費型では、開発サンドボックスを対象とする `sbx` パラメーター付きの User Store ID 認証はサポートされていません。デベロッパー管理の消費型のサンドボックステストには XSTS トークン認証を使用してください。	いいえ

消費要求の例

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

ストア管理の消費要求

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
}

デベロッパー管理の消費要求

次の例では User Store ID 認証を使用しています。ただし、この認証方法は開発サンドボックスのデベロッパー管理の消費型では機能しません。サンドボックス環境でテストしている場合は、代わりに XSTS トークン認証を使用してください。詳細については、「委任認証の XSTS トークンでの認証」を参照してください。

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`	消費要求のために呼び出し元によって提供された一意の `trackingId`。	はい
`newQuantity`	`int`	この消費型製品に対するユーザーの残余残高。デベロッパー管理の消費型では値は 0 です。	はい
`orderTransactions`	`List<ConsumeOrderTransaction>`	要求を消化するために使用された注文を示す ConsumeOrderTransaction オブジェクトの配列。要求で `includeOrderIds` パラメーターが true に設定されている場合にのみ返されます。詳細については、次の表を参照してください。	いいえ

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

パラメーター	型	説明	必須
`orderId`	`GUID`	消費要求の全部または一部を消化するために使用されたユーザーの購入注文の ID。	はい
`orderLineItemId`	`GUID`	ユーザーが行った購入注文内の消費型アイテムの明細アイテムの ID。OrderID あたり複数の LineItemIds が存在する可能性があるため、この ID は OrderId よりも消費型購入に一意です。	はい
`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 (Collections v9) を使用してユーザーの製品と使用権を照会するサービスから消費型製品を管理するサービスからの返金とチャージバックの管理

Microsoft Store APIs

`trackingId` を使用して消化完了を検証する

前提条件

User Store ID 認証のエラーコード

X-token 認証を使用する場合のエラーコード

要求

要求の構文

要求ヘッダー

要求本文

消費要求の例

ストア管理の消費要求

デベロッパー管理の消費要求

応答

応答本文

消費応答の例

関連記事

​trackingId を使用して消化完了を検証する

​前提条件

​User Store ID 認証のエラー コード

​X-token 認証を使用する場合のエラー コード

​要求

​要求の構文

​要求ヘッダー

​要求本文

​消費要求の例

​ストア管理の消費要求

​デベロッパー管理の消費要求

​応答

​応答本文

​消費応答の例

​関連記事

`trackingId` を使用して消化完了を検証する

前提条件

User Store ID 認証のエラーコード

X-token 認証を使用する場合のエラーコード

要求

要求の構文

要求ヘッダー

要求本文

消費要求の例

ストア管理の消費要求

デベロッパー管理の消費要求

応答

応答本文

消費応答の例

関連記事