purchase.mp.microsoft.com/v8.0/b2b/orders/query

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

注意

この API は、払い戻された製品を検出するための Clawback フローの一部としては必要なくなり、使用されなくなりました。最新の Clawback サービスについては、「サービスからの返金とチャージバックの管理」を参照してください。

purchase.mp.microsoft.com/v8.0/b2b/orders/query API は、過去 90 日間にユーザーが行った消耗品の購入をクエリする機能をゲームサービスに提供します。この API を使用すると、ゲームサービスは、カスタマーサポートシナリオに役立つ ShortOrderID フィールドなど、コレクションクエリの結果で使用できない情報を収集できます。

前提条件

この API を使用するには、以下が必要になります。

対象ユーザーの URI 値 https://onestore.microsoft.com を持つ Microsoft Entra ID アクセストークン
付与する無料製品のユーザーの ID を表すユーザー購入 ID キー

詳細については、「サーバー間認証にユーザー Store ID を要求する」を参照してください。

さらに、サービスに表示できるようにする製品には、パートナーセンターでの追加の構成が必要です。

製品を適切に構成する方法については、「ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成」を参照してください。

注意

製品の構成がまだ行われておらず、パートナーセンター経由で発行された場合、購入サービスの呼び出しは成功しますが、応答に結果は入りません。

要求

要求の構文

メソッド	要求 URI
`POST`	`https://purchase.mp.microsoft.com/v8.0/b2b/orders/query`

要求ヘッダー

ヘッダー	型	説明
`Authorization`	`string`	必須。 `Bearer` < トークン> という形式の Microsoft Entra ID サービスアクセストークン。
`Host`	`string`	値 `purchase.mp.microsoft.com` を設定する必要があります。
`Content-Length`	`number`	要求本文の長さ。
`Content-Type`	`string`	要求と応答の種類を指定します。現在唯一サポートされている値は `application/json` です。

リクエストの本文

パラメーター	型	説明	必須
`b2bKey`	`string`	要求しているユーザーの ID を表すユーザー購入 ID。ユーザーストア ID キーを参照してください。	はい
`lineItemStateFilter`	`list<string>`	クエリ結果で返すアイテムの状態を指定します。有効な値のリストについては、ラインアイテムの状態を参照してください。	いいえ
`sbx`	`string`	結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。この値のない既定値は RETAIL サンドボックスです。サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。	いいえ

ラインアイテムの状態

値	説明
`Purchased`	アクティブな (良好な) 状態にある消耗品の購入。この状態には、履行されていない消耗品と履行された消耗品が含まれます。
`Revoked`	ゲームサービスによって履行/消費されたが、後でユーザーによって払い戻された消耗品の購入。
`Refunded`	払い戻されたが、ゲームサービスによってまだ履行/消費されていない消耗品の購入。

要求の例

POST https://purchase.mp.microsoft.com/v8.0/b2b/orders/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseID]",
  "lineItemStateFilter": [
    "Purchased",
    "Revoked",
    "Refunded"],
  "sbx": "XDKS.1"
}

応答

応答の本文

パラメーター	型	説明	必須かどうか
`items`	`list<PurchasedItem>`	指定したユーザーの製品の配列。詳細については、後の表を参照してください。	はい

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

パラメーター	型	説明	必須
`orderId`	`GUID`	購入の注文番号の長い形式の ID。これは、コレクションやその他のサービスで使用される orderID です。	はい
`shortOrderId`	`GUID`	購入の注文番号の短い形式の ID。これは、エンドユーザーが購入履歴と確認メールに表示する注文番号です。カスタマーサポートを提供する場合、ユーザーはこの ID をサポートスタッフに提供して購入を表します。	いいえ
`orderLineItems`	`list<OrderLineItem>`	ユーザーからの購入 OrderId 内の消耗品に関連する一連の追加情報。詳細については、次の表を参照してください。	はい
`orderPurchasedDate`	`datetime`	消耗品アイテムを購入した UTC 日時。	はい
`orderRefundedDate`	`datetime`	消耗品アイテムを払い戻しした UTC 日時。この値は、払い戻されたアイテムに表示されるまでに数時間かかります。	いいえ

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

パラメーター	型	説明	必須
`lineItemId`	`GUID`	消耗品の発注書内の lineItem を識別します (注文には、ショッピングカートのシナリオで複数の lineItemId を含めることができます)	はい
`lineItemState`	`string`	この特定の消耗品購入の状態。ラインアイテムの状態を参照してください。	はい
`productId`	`string`	Microsoft Store カタログ内の製品の場合、Store ID とも呼ばれます。製品の Store ID の例は、9NBLGGH42CFD です。	はい
`quantity`	`number`	注文で購入したときのアイテムの数量。	はい
`skuId`	`string`	Microsoft Store カタログに製品の提供が複数ある場合は、特定の SKU 識別子。 SKU の Store ID の例は、0010 です。	はい
`wasConsumableQuantityRevoked`	`bool`	払い戻しが発生したときに、購入した数量をユーザーのストアアカウントから削除できたかどうかを示します。	いいえ

応答の例

HTTP/1.1 200 OK
Content-Length: 1042
Content-Type: application/json
MS-CorrelationId: b5157f23-7f26-4e0b-8f06-07733bd09355
MS-RequestId: 2b0933bc-19f7-4f96-bb47-2602491fed1f
MS-CV: OAIoYIzDJkO2Knp.7
MS-ServerId: 1
Date: Tue, 30 Jun 2020 18:29:22 GMT
 
{
    "items": [
        {
            "orderId": "3c1ad7bc-b0c2-442c-aad4-46d8d0e0184e",
            "shortOrderId": "8483143756",
            "orderLineItems": [
                {
                    "lineItemId": "febdd51b-97aa-45fc-bf46-0120eacbf8aa",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-12T23:57:51.1415104+00:00"
        },
        {
            "orderId": "75bf81ec-7c31-46f9-9828-6ac61464e553",
            "shortOrderId": "3145294485",
            "orderLineItems": [
                {
                    "lineItemId": "ad7adfc5-be76-4548-aede-155084490044",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-13T23:57:51.1415104+00:00"
        },
        {
            "orderId": "b9d6d1fd-3e68-423b-85fa-feea1ee125b3",
            "shortOrderId": "7620137155",
            "orderLineItems": [
                {
                    "lineItemId": "eb565041-6e1f-4210-97a3-54a2ab80f49e",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-142T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "cda65a53-30b0-4e19-8ec1-c08219174e45",
            "shortOrderId": "5993204763",
            "orderLineItems": [
                {
                    "lineItemId": "a30b4285-c456-4486-8048-a9f5b5231b76",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-152T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "f1da6d12-8b0d-4dc1-8aca-c52fcece582a",
            "shortOrderId": "8768763421",
            "orderLineItems": [
                {
                    "lineItemId": "7da73274-b4bc-4a4f-bb93-e49618f7a7d7",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-16T23:57:51.1415104+00:00"
        }
    ]
}

応答例の説明

上記の例 (すべての状態を要求した場合) から、ユーザーのアカウントが消耗品 9MT5TGW893HV を 5 回購入したことがわかります。ただし、これらの購入のうち 2 つは、Revoked のラインアイテムの状態になっています。これは、サンプルのゲームサービスで消費された後に払い戻されたことを意味します。払い戻しイベントが発生した場合の追跡には、purchase.mp.microsoft.com/v8.0/b2b/orders/query を使用しないでください。代わりに、サービスでは、「サービスからの払い戻しとチャージバックの管理」で説明されている Clawback イベントサービスを使用する必要があります。

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

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

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

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

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

次の方法で共有

purchase.mp.microsoft.com/v8.0/b2b/orders/query

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

ラインアイテムの状態

要求の例

応答

応答の本文

応答の例

応答例の説明

その他のリソース

次の方法で共有

purchase.mp.microsoft.com/v8.0/b2b/orders/query

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

ライン アイテムの状態

要求の例

応答

応答の本文

応答の例

応答例の説明

関連トピック

その他のリソース

ラインアイテムの状態