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

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

このエンドポイントは、ユーザーが Microsoft Store を通じて所有しているサブスクリプション製品タイプのステータスを照会するために使用されます。自動更新料金が失敗した場合の製品の猶予期間など、これらのサブスクリプションのコレクションサービスよりも多くの情報を提供します。

前提条件

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

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

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

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

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

注意

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

要求

要求の構文

メソッド	要求 URI
`POST`	`purchase.mp.microsoft.com/v8.0/b2b/recurrences/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 キーを参照してください。	はい
`sbx`	`string`	結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。この値のない既定値は RETAIL サンドボックスです。サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。	いいえ
`continuationToken`	`string`	`maxPageSize` に収まらない製品のセットが複数ある場合、ページ制限に達すると、応答本文で継続トークンが返されます。前の要求のクエリから残りの製品を取得するための後続の呼び出しで、その継続トークンを指定します。	いいえ

要求の例

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

{
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

応答

応答の本文

パラメーター	型	説明	必須
`continuationToken`	`string`	ページ制限に達すると、このトークンが返されます。残りの製品を取得するための後続の呼び出しで、この継続トークンを指定できます。	いいえ
`items`	`list<RecurrenceItem>`	指定したユーザーの製品の配列。詳細については、後の表を参照してください。	はい

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

パラメーター	型	説明	必須
`autoRenew`	`bool`	次の請求サイクルの終了時にサブスクリプションを自動更新するようにユーザーが登録されているかどうかを示します。	はい
`beneficiary`	`string`	ユーザー購入 ID 内の受益者の発行者 ID。	はい
`expirationTime`	`DateTime`	サブスクリプションの有効期限が切れる、または期限切れになる日時 (UTC)	はい
`expirationTimeWithGrace`	`DateTime`	ExpirationTime で自動更新が失敗した場合に、ユーザーの猶予期間が終了する日時 (UTC)。 Grace の間、ユーザーは引き続きアクセスでき、有効なサブスクライバーと見なされますが、自動更新の支払いを修正する必要があることを通知されます。	はい
`id`	`string`	ユーザーが所有する他の項目からこのコレクション項目を識別する ID。この ID は製品ごとに一意です。	はい
`isTrial`	`bool`	製品がサブスクリプションなどの試用期間内であるかどうかを示します。	はい
`lastModified`	`DateTime`	この項目が最後に更新された日付 (UTC)。	はい
`market`	`string`	製品が購入された国/地域は、2 文字の ISO 3166 国/地域コードに従っています。例: US。	はい
`productId`	`string`	Microsoft Store カタログ内の製品の場合、Store ID とも呼ばれます。製品の Store ID の例は、9NBLGGH42CFD です。	はい
`recurrenceState`	`string`	再発の現在の状態です。「再発の状態」を参照してください。	はい
`skuId`	`string`	Microsoft Store カタログに製品の提供が複数ある場合は、特定の SKU 識別子。 SKU の Store ID の例は、0010 です。	はい
`startTime`	`DateTime`	サブスクリプションが有効になった、または有効になる予定の日付 (UTC)。	はい
`cancellationDate`	`DateTime`	サブスクリプションがキャンセルされた日付 (UTC)。	いいえ

再発の状態

値	説明
`None`	これは永続的なサブスクリプションを示します。
`Active`	サブスクリプションは有効であり、ユーザーにはサブスクリプション特典を受け取る資格があります。
`Inactive`	サブスクリプションは有効期限を過ぎており、ユーザーはこのサブスクリプションの自動更新オプションをオフにしました。
`Canceled`	サブスクリプションは有効期限の前に意図的に終了され、払戻は行われた場合と行われていない場合があります。
`InDunning`	サブスクリプションは督促状態にあります (つまり、サブスクリプションの有効期限が近づいているので、Microsoft はサブスクリプションを自動的に更新するための資金を取得しようとしています)。現在の日付が expirationTimeWithGrace 値より前の場合、ユーザーにはまだサブスクリプション特典を受け取る資格があります。現在の日付が expirationTimeWithGrace 値より後の場合、ユーザーにはサブスクリプション特典を受け取る資格がありません。
`Failed`	督促期間が終了し、数回試行しましたがサブスクリプションを更新できませんでした。

非アクティブ/キャンセル済み/失敗は、最終状態です。サブスクリプションがこれらのいずれかの状態になった場合、ユーザーがサブスクリプションを再度アクティブ化するには、再購入する必要があります。ユーザーは、これらの状態にあるサービスを使用する資格はありません。
サブスクリプションがキャンセルされると、expirationTime はキャンセルの日時で更新されます。
サブスクリプションの ID は、有効期間全体にわたって同じまま保持されます。これは、自動更新オプションがオンでもオフでも、変更されません。最終状態に達した後にユーザーがサブスクリプションを再購入すると、新しいサブスクリプション ID が作成されます。
個々のサブスクリプションに対して何かの操作を実行するには、サブスクリプションの ID を使用する必要があります。
ユーザーがサブスクリプションをキャンセルまたは中止した後にサブスクリプションを再購入した場合、そのユーザーの結果に対してクエリを実行すると、2 つの項目が取得されます。1 つは最終状態の古いサブスクリプション ID を持つ項目、もう 1 つはアクティブ状態の新しいサブスクリプション ID を持つ項目です。
recurrenceState の更新は数分 (または場合によっては数時間) 遅れる可能性があるため、常に recurrenceState と expirationTime の両方を確認することをお勧めします。

応答の例

HTTP/1.1 200 OK
date: Tue, 17 Aug 2021 21:22:28 GMT
content-type: application/json; charset=utf-8
content-length: 2382
ms-cv: aft4s000mwNmYF.0
x-content-type-options: nosniff
x-envoy-upstream-service-time: 2099

{
    "items": [
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-08-25T23:59:59.00+00:00",
            "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00",
            "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92",
            "isTrial": false,
            "lastModified": "2021-07-26T22:59:55.99+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Active"
        },
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T21:08:30.52+00:00",
            "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00",
            "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5",
            "isTrial": false,
            "lastModified": "2021-07-26T21:08:34.61+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-15T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T21:08:31.52+00:00"
        },
        {
            "autoRenew": false,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T22:35:29.54+00:00",
            "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00",
            "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde",
            "isTrial": false,
            "lastModified": "2021-07-26T22:35:33.96+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T22:35:30.54+00:00"
        },
    ]
}

応答例の説明

上記の例から、このユーザーには、以前にキャンセルされた 2 つのサブスクリプション期間と、2021 年 7 月 26 日に開始された現在アクティブなサブスクリプション期間があります。サブスクリプション期間の終了日は 2021 年 8 月 26 日です。ユーザーは自動更新に登録されているため、Microsoft Store は 2021 年 8 月 26 日頃に処理された支払いでサブスクリプションの更新を試みます。ユーザーのアカウントでサブスクリプションの更新を完了できない場合、サブスクリプションの状態は 'InDunning' (督促中) に変わりますが、猶予期間が終了するまで、ユーザーは引き続きサブスクリプション特典へのアクセス権を受け取ることができます。猶予期間の終了 (2021 年 9 月 8 日) の時点でストアが更新の購入を完了できなかった場合は、状態がまだ 'InDunning' (督促中) であっても、サービスはサブスクリプション特典をユーザーに付与しなくなります。猶予期間の後、ユーザーはサブスクリプションの再購入または再登録をブロックされるようになり、アクティブなサブスクリプションを再度取得するには支払い方法を修正する必要があります。これは、猶予期間中に 2 週間分の特典を受け取っており、支払いが不足しているためです。アカウントの支払い方法を解決すると、以前に使用した猶予期間分を調整するために、次のサブスクリプション期間から 2 週間が削除されます。

継続トークンを使用して残りの結果を要求する

クエリの結果が 1 回の応答で返される結果よりも多い場合、最初のクエリ応答には continuationToken が含まれます。その後、前の要求本文のコピーに継続トークンを追加することにより、フォローアップ要求でこの continuationToken を使用できます。

継続要求の例:

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

{
  "continuationToken":"[Continuation Token]",
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

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

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

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

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

次の方法で共有

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

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

要求の例

応答

応答の本文

再発の状態

応答の例

応答例の説明

継続トークンを使用して残りの結果を要求する

その他のリソース

次の方法で共有

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

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

要求の例

応答

応答の本文

再発の状態

応答の例

応答例の説明

継続トークンを使用して残りの結果を要求する

関連トピック

その他のリソース