サブスクリプション アドオンの取得数の取得
特定の日付範囲やその他のオプション フィルター中にアプリのアドオン サブスクリプションの集計取得データを取得するには、Microsoft Store 分析 API の次のメソッドを使用します。
前提条件
このメソッドを使うには、最初に次の作業を行う必要があります。
- Microsoft Store 分析 API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。
- このメソッドの要求ヘッダーで使う Azure AD アクセス トークンを取得します。 アクセス トークンを取得した後、アクセス トークンを使用できるのは、その有効期限が切れるまでの 60 分間です。 トークンの有効期限が切れたら新しいトークンを取得できます。
要求
要求の構文
| 認証方法 | 要求 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions |
要求ヘッダー
| Header | 型 | 説明 |
|---|---|---|
| 承認 | string | 必須。 Bearer<トークン> という形式の Azure AD アクセス トークン。 |
要求パラメーター
| パラメーター | 型 | 内容 | 必須 |
|---|---|---|---|
| applicationId | string | サブスクリプション アドオン取得データを取得するアプリの Store ID。 | はい |
| subscriptionProductId | string | 取得データを取得するサブスクリプション アドオンの Store ID。 この値を指定しない場合、このメソッドは、指定されたアプリのすべてのサブスクリプション アドオンの取得データを返します。 | いいえ |
| startDate | 日付 | 取得するサブスクリプション アドオン取得データの日付範囲の開始日。 既定値は現在の日付です。 | いいえ |
| endDate | 日付 | 取得するサブスクリプション アドオン取得データの日付範囲の終了日。 既定値は現在の日付です。 | いいえ |
| top | int | 要求で返すデータの行数です。 最大値および指定しない場合の既定値は 100 です。 クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。 | いいえ |
| skip | int | クエリでスキップする行数です。 大きなデータ セットを操作するには、このパラメーターを使用します。 たとえば、top=100 と skip=0 を指定すると、データの最初の 100 行が取得され、top=100 と skip=100 を指定すると、次の 100 行のデータが取得されます。 | いいえ |
| filter | string | 応答本文をフィルター処理する 1 つまたは複数のステートメントです。 各ステートメントでは eq や ne 演算子を使用できます。また、ステートメントを and や or で結合することもできます。 フィルター ステートメントでは、次の文字列を指定できます (これらは、応答本文の値に対応します)。
filter パラメーターの例: filter=date eq '2017-07-08'。 |
いいえ |
| aggregationLevel | string | 集計データを取得する時間範囲を指定します。 次のいずれかの文字列を指定できます。day、week、または month。 指定しない場合、既定値は day です。 | No |
| orderby | string | 各サブスクリプション アドオン取得の結果データ値の順序を指定するステートメント。 構文は orderby=field [order],field [order],... です。field パラメーターは次のいずれかの文字列になります。
order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。 既定値は asc です。 orderby 文字列の例: orderby=date,market |
No |
| groupby | string | 指定したフィールドのみにデータ集計を適用するステートメントです。 次のフィールドを指定できます。
groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。 例: groupby=market&aggregationLevel=week |
いいえ |
要求の例
次の例は、サブスクリプション アドオン取得データを取得する方法を示しています。 applicationId 値をアプリの適切な Store ID に置き換えてください。
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>
回答
応答本文
| 値 | 種類 | 説明 |
|---|---|---|
| 値 | 配列 | 集計サブスクリプション アドオン取得データが含まれているオブジェクトの配列。 各オブジェクト内のデータの詳細については、後の「サブスクリプション取得の値」セクションを参照してください。 |
| @nextLink | string | データの追加ページがある場合、この文字列には、データの次のページを要求するために使用できる URI が含まれます。 たとえば、要求の top パラメーターは 100 に設定されているが、クエリのサブスクリプション アドオン取得データが 100 行を超える場合は、この値が返されます。 |
| TotalCount | int | クエリの結果データ内の行の総数です。 |
サブスクリプション取得の値
Value 配列の要素には、次の値が含まれます。
| 値 | 種類 | 説明 |
|---|---|---|
| date | string | 入手データの期間の最初の日付。 要求に日付を指定した場合、この値はその日付になります。 要求に週、月、またはその他の日付範囲を指定した場合、この値はその日付範囲の最初の日付になります。 |
| subscriptionProductId | string | 取得データを取得するサブスクリプション アドオンの Store ID。 |
| subscriptionProductName | string | サブスクリプション アドオンの表示名。 |
| applicationId | string | サブスクリプション アドオン取得データを取得するアプリの Store ID。 |
| applicationName | string | アプリの表示名です。 |
| skuId | string | 取得データを取得するサブスクリプション アドオンの SKU の ID。 |
| deviceType | string | 入手を完了したデバイスの種類を指定する、次のいずれかの文字列。
|
| market | string | 入手が行われた市場の ISO 3166 国コード。 |
| currencyCode | string | 税引き前の総売上の ISO 4217 形式の通貨コード。 |
| grossSalesBeforeTax | integer | currencyCode 値で指定された現地通貨での総売上。 |
| totalActiveCount | integer | 指定された期間中のアクティブなサブスクリプションの合計数。 これは、goodStandingActiveCount、pendingGraceActiveCount、graceActiveCount、lockedActiveCount の各値の合計に相当します。 |
| totalChurnCount | integer | 指定された期間中に非アクティブ化されたサブスクリプションの合計数。 これは、billingChurnCount、nonRenewalChurnCount、refundChurnCount、chargebackChurnCount、earlyChurnCount、otherChurnCount の各値の合計に相当します。 |
| newCount | integer | 指定された期間中の新しいサブスクリプション取得の数 (試用版を含む)。 |
| renewCount | integer | 指定された期間中のサブスクリプション更新の数 (ユーザーが開始した更新と自動更新を含む)。 |
| goodStandingActiveCount | integer | 指定された期間中にアクティブであり、かつ有効期限 >= クエリの endDate 値であるサブスクリプションの数。 |
| pendingGraceActiveCount | integer | 指定された期間中にアクティブであったが、課金エラーが発生し、かつサブスクリプションの有効期限 >= クエリの endDate 値であるサブスクリプションの数。 |
| graceActiveCount | integer | 指定された期間中にアクティブであったが、課金エラーが発生し、かつ次の条件を満たすサブスクリプションの数。
|
| lockedActiveCount | integer | 指定された期間中に "催促中" の状態 (つまり、サブスクリプションの有効期限が近づいており、Microsoft がサブスクリプションを自動更新するための資金を得ようとしている) にあり、かつ次の条件を満たすサブスクリプションの数。
|
| billingChurnCount | integer | 請求料金を処理できなかったために指定された期間中に非アクティブ化され、かつサブスクリプションが以前に催促中の状態にあったサブスクリプションの数。 |
| nonRenewalChurnCount | integer | 更新されなかったために指定された期間中に非アクティブ化されたサブスクリプションの数。 |
| refundChurnCount | integer | 返金されたために指定された期間中に非アクティブ化されたサブスクリプションの数。 |
| chargebackChurnCount | integer | チャージバックのために指定された期間中に非アクティブ化されたサブスクリプションの数。 |
| earlyChurnCount | integer | 健全な状態にあったときに、指定された期間中に非アクティブ化されたサブスクリプションの数。 |
| otherChurnCount | integer | その他の理由で指定された期間中に非アクティブ化されたサブスクリプションの数。 |
要求と応答の例
次のコード スニペットは、これらの要求についての要求と JSON 応答本文の例を示しています。
サンプル要求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
サンプル応答
{
"Value": [
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"grossSalesBeforeTax": 3460656.260391250,
"totalActiveCount": 20211321,
"totalChurnCount": 5605,
"newCount": 3810366,
"renewCount": 12102044,
"goodStandingActiveCount": 17893664,
"pendingGraceActiveCount": 2255792,
"graceActiveCount": 61833,
"lockedActiveCount": 32,
"billingChurnCount": 4,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 2717,
"otherChurnCount": 2884
},
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Unknown",
"grossSalesBeforeTax": 2342.580615228,
"totalActiveCount": 50550,
"totalChurnCount": 7,
"newCount": 8312,
"renewCount": 31446,
"goodStandingActiveCount": 44047,
"pendingGraceActiveCount": 6503,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 5,
"otherChurnCount": 2
}
],
"TotalCount": 2
}
サンプル要求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>
サンプル応答
{
"Value": [
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "IT",
"deviceType": "Console-Xbox One",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 2,
"renewCount": 0,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "NO",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 13,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.02",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "CA",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 152,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 270,
"goodStandingActiveCount": 133,
"pendingGraceActiveCount": 19,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
}
],
"TotalCount": 3
}
関連トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示