サブスクリプション アドオンの取得数の取得Get subscription add-on acquisitions

Microsoft Store analytics API でこのメソッドを使用して、集計の取得データを特定の日付範囲とその他のオプションのフィルターの中に、アプリのアドオンのサブスクリプションを取得します。Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-on subscriptions for your app during a given date range and other optional filters.

前提条件Prerequisites

このメソッドを使うには、最初に次の作業を行う必要があります。To use this method, you need to first do the following:

  • Microsoft Store 分析 API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • このメソッドの要求ヘッダーで使う Azure AD アクセス トークンを取得します。Obtain an Azure AD access token to use in the request header for this method. アクセス トークンを取得した後、アクセス トークンを使用できるのは、その有効期限が切れるまでの 60 分間です。After you obtain an access token, you have 60 minutes to use it before it expires. トークンの有効期限が切れたら新しいトークンを取得できます。After the token expires, you can obtain a new one.

要求Request

要求の構文Request syntax

メソッドMethod 要求 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

要求ヘッダーRequest header

HeaderHeader 種類Type 説明Description
AuthorizationAuthorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.

要求パラメーターRequest parameters

パラメーターParameter 種類Type 説明Description 必須Required
applicationIdapplicationId stringstring Store IDのサブスクリプションのアドオン購入データを取得するアプリです。The Store ID of the app for which you want to retrieve subscription add-on acquisition data. Yes
subscriptionProductIdsubscriptionProductId stringstring Store ID取得データを取得するサブスクリプションのアドオンです。The Store ID of the subscription add-on for which you want to retrieve acquisition data. この値を指定しない場合、このメソッドは、指定したアプリのすべてのサブスクリプションのアドオンの購入データを返します。If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. いいえNo
startDatestartDate datedate 取得するアドオンのサブスクリプションの取得データの日付範囲の開始日。The start date in the date range of subscription add-on acquisition data to retrieve. 既定値は現在の日付です。The default is the current date. XNo
endDateendDate datedate 取得するアドオンのサブスクリプションの取得データの日付範囲の終了日。The end date in the date range of subscription add-on acquisition data to retrieve. 既定値は現在の日付です。The default is the current date. XNo
toptop intint 要求で返すデータの行数です。The number of rows of data to return in the request. 最大値および指定しない場合の既定値は 100 です。The maximum value and the default value if not specified is 100. クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. XNo
skipskip intint クエリでスキップする行数です。The number of rows to skip in the query. 大きなデータ セットを操作するには、このパラメーターを使用します。Use this parameter to page through large data sets. たとえば、top=100 と skip=0 を指定すると、データの最初の 100 行が取得され、top=100 と skip=100 を指定すると、データの次の 100 行が取得されます。For example, top=100 and skip=0 retrieves the first 100 rows of data, top=100 and skip=100 retrieves the next 100 rows of data, and so on. XNo
filterfilter stringstring 応答本文をフィルター処理する 1 つまたは複数のステートメントです。One or more statements that filter the response body. 各ステートメントでは eqne 演算子を使用できます。また、ステートメントを andor で結合することもできます。Each statement can use the eq or ne operators, and statements can be combined using and or or. フィルター ステートメントでは、次の文字列を指定できます (これらに対応して応答本文で値を)。You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • ApplicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

例を次に示しますフィルターパラメーター:フィルター = 日付 eq ' 2017-07-08'します。Here is an example filter parameter: filter=date eq '2017-07-08'.

XNo
aggregationLevelaggregationLevel stringstring 集計データを取得する時間範囲を指定します。Specifies the time range for which to retrieve aggregate data. 次のいずれかの文字列を指定できます。dayweek、または monthCan be one of the following strings: day, week, or month. 指定しない場合、既定値は day です。If unspecified, the default is day. XNo
orderbyorderby stringstring 各サブスクリプションのアドオン購入のデータ値の結果を注文するステートメント。A statement that orders the result data values for each subscription add-on acquisition. 構文は orderby=field [order],field [order],... です。field パラメーターには、次のいずれかの文字列を指定できます。The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • ApplicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. 既定値は asc です。The default is asc.

orderby 文字列の例: orderby=date,marketHere is an example orderby string: orderby=date,market

XNo
groupbygroupby stringstring 指定したフィールドのみにデータ集計を適用するステートメントです。A statement that applies data aggregation only to the specified fields. 次のフィールドを指定できます。You can specify the following fields:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • ApplicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。The groupby parameter can be used with the aggregationLevel parameter. 例: groupby = 市場&aggregationLevel = 週For example: groupby=market&aggregationLevel=week

XNo

要求の例Request example

次の例では、サブスクリプションのアドオン購入データを取得する方法を示します。The following examples demonstrates how to get subscription add-on acquisition data. 置換、 applicationIdアプリの適切な Store ID を持つ値。Replace the applicationId value with the appropriate Store ID for your app.

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>

応答Response

応答本文Response body

ValueValue 種類Type 説明Description
ValueValue arrayarray 集計のサブスクリプションのアドオン購入データを格納するオブジェクトの配列。An array of objects that contain aggregate subscription add-on acquisition data. 各オブジェクトのデータの詳細については、次を参照してください。、サブスクリプション購入値以下のセクション。For more information about the data in each object, see the subscription acquisition values section below.
@nextLink stringstring データの追加ページがある場合、この文字列には、データの次のページを要求するために使用できる URI が含まれます。If there are additional pages of data, this string contains a URI that you can use to request the next page of data. この値が返される場合など、上部要求のパラメーターは 100 に設定されますが、クエリのサブスクリプションのアドオン購入データの 100 を超える行があります。For example, this value is returned if the top parameter of the request is set to 100 but there are more than 100 rows of subscription add-on acquisition data for the query.
TotalCountTotalCount intint クエリの結果データ内の行の総数です。The total number of rows in the data result for the query.

サブスクリプションの取得の値Subscription acquisition values

Value 配列の要素には、次の値が含まれます。Elements in the Value array contain the following values.

ValueValue 種類Type 説明Description
datedate stringstring 入手データの日付範囲の最初の日付です。The first date in the date range for the acquisition data. 要求に日付を指定した場合、この値はその日付になります。If the request specified a single day, this value is that date. 要求に週、月、またはその他の日付範囲を指定した場合、この値はその日付範囲の最初の日付になります。If the request specified a week, month, or other date range, this value is the first date in that date range.
subscriptionProductIdsubscriptionProductId stringstring Store ID取得データを取得するサブスクリプションのアドオンです。The Store ID of the subscription add-on for which you are retrieving acquisition data.
subscriptionProductNamesubscriptionProductName stringstring サブスクリプションのアドオンの表示名。The display name of the subscription add-on.
applicationIdapplicationId stringstring Store IDのサブスクリプションのアドオン購入データを取得するアプリです。The Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName stringstring アプリの表示名です。The display name of the app.
skuIdskuId stringstring ID、 SKU取得データを取得するサブスクリプションのアドオンです。The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType stringstring 入手が完了したデバイスの種類を指定する、以下のいずれかの文字列です。One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • PhonePhone
  • ConsoleConsole
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
marketmarket stringstring 入手が発生した市場の ISO 3166 国コードです。The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode stringstring 税引き前に、の総売り上げの ISO 4217 形式で通貨コード。The currency code in ISO 4217 format for gross sales before taxes.
grossSalesBeforeTaxgrossSalesBeforeTax 整数integer 指定された現地通貨での総売り上げ、 currencyCode値。The gross sales in the local currency specified by the currencyCode value.
totalActiveCounttotalActiveCount 整数integer 指定した期間中にアクティブなサブスクリプションの合計数。The number of total active subscriptions during the specified time period. これは、合計に、 goodStandingActiveCountpendingGraceActiveCountgraceActiveCount、およびlockedActiveCount値。This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalChurnCounttotalChurnCount 整数integer 指定した期間中に非アクティブ化されたサブスクリプションの合計数。The total count of subscriptions that were deactivated during the specified time period. これは、合計に、 billingChurnCountnonRenewalChurnCountrefundChurnCountchargebackChurnCountearlyChurnCount、およびotherChurnCount値。This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newCountnewCount 整数integer 試用版を含む、指定した期間内に新しいサブスクリプションの買収の数。The number of new subscription acquisitions during the specified time period, including trials.
renewCountrenewCount 整数integer ユーザーが開始したの更新と自動更新を含む、指定した期間内にサブスクリプションの更新の数。The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodStandingActiveCountgoodStandingActiveCount 整数integer 指定した期間中にアクティブだったして、有効期限日があるサブスクリプションの数 > =、 endDateクエリの値。The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
pendingGraceActiveCountpendingGraceActiveCount 整数integer サブスクリプションの有効期限日があると、指定された期間中にアクティブだったが、課金の失敗したサブスクリプションの数 > =、 endDateクエリの値。The number of subscriptions that were active during the specified time period but had a billing failure, and where the subscription expiration date is >= the endDate value for the query.
graceActiveCountgraceActiveCount 整数integer 指定した期間中にアクティブだったが、課金の失敗したサブスクリプションの数と場所。The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • サブスクリプションの有効期限が <、 endDateクエリの値。The subscription expiration date is < the endDate value for the query.
  • 猶予期間の終了は > =、 endDate値。The end of the grace period is >= the endDate value.
lockedActiveCountlockedActiveCount 整数integer サブスクリプションに含まれていた数dunning (つまり、サブスクリプションの有効期限が近づいていると Microsoft は、自動的にサブスクリプションを更新するための資金を取得しようとしています) 中に、指定した期間と場所を時間します。The number of subscriptions that were in dunning (that is, the subscription is nearing expiration and Microsoft is trying to acquire funds to automatically renew the subscription) during the specified time period, and where:
  • サブスクリプションの有効期限が <、 endDateクエリの値。The subscription expiration date is < the endDate value for the query.
  • 猶予期間の終了は、< =、 endDate値。The end of the grace period is <= the endDate value.
billingChurnCountbillingChurnCount 整数integer 場所、サブスクリプションであった dunning するされた請求料金を処理できないのため、指定した期間中に非アクティブ化されたサブスクリプションの数。The number of subscriptions that were deactivated during the specified time period because of a failure to process a billing charge and where the subscriptions were previously in dunning.
nonRenewalChurnCountnonRenewalChurnCount 整数integer 指定された期間中に非アクティブ化が更新されたされないため、サブスクリプションの数。The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundChurnCountrefundChurnCount 整数integer 返金したために、指定した期間中に非アクティブ化されたサブスクリプションの数。The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebackChurnCountchargebackChurnCount 整数integer チャージ バックのために、指定した期間中に非アクティブ化されたサブスクリプションの数。The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlyChurnCountearlyChurnCount 整数integer 良好な状態であるときに、指定した期間中に非アクティブ化されたされたサブスクリプションの数。The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherChurnCountotherChurnCount 整数integer 他の理由から、指定した期間中に非アクティブ化されたサブスクリプションの数。The number of subscriptions that were deactivated during the specified time period for other reasons.

応答の例Response example

この要求の JSON 返信の本文の例を次に示します。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9KDLGHH6R365",
      "subscriptionProductName": "Contoso App Subscription with One Month Free Trial",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "Unknown",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    },
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9JJFDHG4R478",
      "subscriptionProductName": "Contoso App Monthly Subscription",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "US",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}