アドオンの入手数の取得Get add-on acquisitions

日付範囲やその他のオプション フィルターを指定して、アプリのアドオンに関する集計入手データを JSON 形式で取得するには、Microsoft Store 分析 API の以下のメソッドを使います。Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-ons for your app in JSON format during a given date range and other optional filters. この情報も記載されて、アドオン買収レポートパートナー センターでします。This information is also available in the Add-on acquisitions report in Partner Center.

前提条件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/inappacquisitions

要求ヘッダーRequest header

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

要求パラメーターRequest parameters

applicationId または inAppProductId パラメーターが必要です。The applicationId or inAppProductId parameter is required. アプリに登録されたすべてのアドオンの入手データを取得するには、applicationId パラメーターを指定します。To retrieve acquisition data for all add-ons registered to the app, specify the applicationId parameter. 単一のアドオンの入手データを取得するには、inAppProductId パラメーターを指定します。To retrieve acquisition data for a single add-on, specify the inAppProductId parameter. 両方を指定した場合、applicationId パラメーターは無視されます。If you specify both, the applicationId parameter is ignored.

パラメーターParameter 種類Type 説明Description 必須Required
applicationIdapplicationId stringstring アドオン入手データを取得するアプリの Store ID です。The Store ID of the app for which you want to retrieve add-on acquisition data. Yes
inAppProductIdinAppProductId stringstring 入手データを取得するアドオンの Store ID です。The Store ID of the add-on for which you want to retrieve acquisition data. Yes
startDatestartDate datedate 取得するアドオン入手データの日付範囲の開始日です。The start date in the date range of add-on acquisition data to retrieve. 既定値は現在の日付です。The default is the current date. XNo
endDateendDate datedate 取得するアドオン入手データの日付範囲終了日です。The end date in the date range of 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. 最大値および指定しない場合の既定値は 10000 です。The maximum value and the default value if not specified is 10000. クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。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=10000 と skip=0 を指定すると、データの最初の 10,000 行が取得され、top=10000 と skip=10000 を指定すると、データの次の 10,000 行が取得されます。For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. XNo
filterfilter stringstring 応答内の行をフィルター処理する 1 つまたは複数のステートメントです。One or more statements that filter the rows in the response. 詳しくは、次の「フィルター フィールド」セクションをご覧ください。For more information, see the filter fields section below. いいえNo
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 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
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • ストア クライアントstoreClient
  • 性別gender
  • marketmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName

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
  • ApplicationNameapplicationName
  • inAppProductNameinAppProductName
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • ストア クライアントstoreClient
  • 性別gender
  • marketmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName

返されるデータ行には、groupby パラメーターに指定したフィールドと次の値が含まれます。The returned data rows will contain the fields specified in the groupby parameter as well as the following:

  • datedate
  • applicationIdapplicationId
  • inAppProductIdinAppProductId
  • 取得数acquisitionQuantity

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

XNo

フィルター フィールドFilter fields

要求の filter パラメーターには、応答内の行をフィルター処理する 1 つまたは複数のステートメントが含まれます。The filter parameter of the request contains one or more statements that filter the rows in the response. 各ステートメントには eq 演算子または ne 演算子と関連付けられるフィールドと値が含まれ、and または or を使ってステートメントを組み合わせることができます。Each statement contains a field and value that are associated with the eq or ne operators, and statements can be combined using and or or. filter パラメーターの例を次に示します。Here are some example filter parameters:

  • フィルター = 市場 eq '米国'] と [性別の eq います 'filter=market eq 'US' and gender eq 'm'
  • フィルター (米国' 市場 ne) = し、(性別 ne '不明') と (性別 ne います ') と (市場 ne 'NO') と (ageGroup ne '55 より大きい' または ageGroup ne 'より小さい 13')filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)

サポートされているフィールドの一覧については、次の表をご覧ください。For a list of the supported fields, see the following table. filter パラメーターでは、文字列値を単一引用符で囲む必要があります。String values must be surrounded by single quotes in the filter parameter.

フィールドFields 説明Description
acquisitionTypeacquisitionType 次のいずれかの文字列です。One of the following strings:
  • 無料free
  • 試用版trial
  • 有料paid
  • プロモーション コードpromotional code
  • Iapiap
ageGroupageGroup 次のいずれかの文字列です。One of the following strings:
  • 小さい 13less than 13
  • 13 ~ 17 日13-17
  • 18 ~ 2418-24
  • 25 3425-34
  • 35 4435-44
  • 44 5544-55
  • 55 より大きいgreater than 55
  • UnknownUnknown
storeClientstoreClient 次のいずれかの文字列です。One of the following strings:
  • Windows Phone ストア (クライアント)Windows Phone Store (client)
  • Microsoft Store (クライアント)Microsoft Store (client)
  • Microsoft Store (web)Microsoft Store (web)
  • 組織でボリューム購入Volume purchase by organizations
  • その他Other
gendergender 次のいずれかの文字列です。One of the following strings:
  • mm
  • ff
  • UnknownUnknown
marketmarket 入手が発生した市場の ISO 3166 国コードを含む文字列です。A string that contains the ISO 3166 country code of the market where the acquisition occurred.
osVersionosVersion 次のいずれかの文字列です。One of the following strings:
  • Windows Phone 7.5Windows Phone 7.5
  • Windows Phone 8Windows Phone 8
  • Windows Phone 8.1Windows Phone 8.1
  • Windows Phone 10Windows Phone 10
  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • UnknownUnknown
deviceTypedeviceType 次のいずれかの文字列です。One of the following strings:
  • PCPC
  • PhonePhone
  • ConsoleConsole
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
orderNameorderName アドオンを入手するために使用されたプロモーション コードの注文の名前を指定する文字列です (このフィールドは、ユーザーがプロモーション コードを利用してアドオンを入手した場合のみに適用されます)。A string that specifies the name of the order for the promotional code that was used to acquire the add-on (this only applies if the user acquired the add-on by redeeming a promotional code).

要求の例Request example

アドオン入手データを取得するためのいくつかの要求の例を次に示します。The following examples demonstrates several requests for getting add-on acquisition data. inAppProductId および applicationId の値を、アドオンまたはアプリの適切なストア ID に置き換えてください。Replace the inAppProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' HTTP/1.1
Authorization: Bearer <your access token>

応答Response

応答本文Response body

ValueValue 種類Type 説明Description
ValueValue arrayarray 集計アドオン入手データが含まれるオブジェクトの配列です。An array of objects that contain aggregate add-on acquisition data. 各オブジェクトのデータについて詳しくは、次の「アドオン入手値」セクションをご覧ください。For more information about the data in each object, see the add-on 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. たとえば、要求の top パラメーターが 10000 に設定されたが、クエリのアドオン入手データに 10,000 を超える行が含まれている場合に、この値が返されます。For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of add-on acquisition data for the query.
TotalCountTotalCount intint クエリの結果データ内の行の総数です。The total number of rows in the data result for the query.

アドオン入手値Add-on 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.
inAppProductIdinAppProductId stringstring 入手データを取得するアドオンのストア ID です。The Store ID of the add-on for which you are retrieving acquisition data.
inAppProductNameinAppProductName stringstring アドオンの表示名です。The display name of the add-on. この値は、aggregationLevel パラメーターが day に設定されている場合にのみ応答データに表示されます (ただし、groupby パラメーターに inAppProductName フィールドを指定していない場合)。This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the inAppProductName field in the groupby parameter.
applicationIdapplicationId stringstring アドオン入手データを取得するアプリのストア ID です。The Store ID of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring アプリの表示名です。The display name of the app.
deviceTypedeviceType stringstring 入手を完了したデバイスの種類です。The type of device that completed the acquisition. サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
orderNameorderName stringstring 注文の名前。The name of the order.
storeClientstoreClient stringstring 入手が発生したストアのバージョンです。The version of the Store where the acquisition occurred. サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
osVersionosVersion stringstring 入手が発生した OS のバージョンです。The OS version on which the acquisition occurred. サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
marketmarket stringstring 入手が発生した市場の ISO 3166 国コードです。The ISO 3166 country code of the market where the acquisition occurred.
gendergender stringstring 入手を行ったユーザーの性別です。The gender of the user who made the acquisition. サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
ageGroupageGroup stringstring 入手を行ったユーザーの年齢グループです。The age group of the user who made the acquisition. サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
acquisitionTypeacquisitionType stringstring 入手の種類です (無料、有料など)。The type of acquisition (free, paid, and so on). サポートされる文字列の一覧については、前の「フィルター フィールド」セクションをご覧ください。For a list of the supported strings, see the filter fields section above.
acquisitionQuantityacquisitionQuantity 整数integer 発生した入手の数です。The number of acquisitions that occurred.

応答の例Response example

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

{
  "Value": [
    {
      "date": "2015-01-02",
      "inAppProductId": "9NBLGGH3LHKL",
      "inAppProductName": "Contoso add-on 7",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Demo",
      "deviceType": "Phone",
      "orderName": "",
      "storeClient": "Windows Phone Store (client)",
      "osVersion": "Windows Phone 8.1",
      "market": "GB",
      "gender": "m",
      "ageGroup": "50orover",
      "acquisitionType": "iap",
      "acquisitionQuantity": 1
    }
  ],
  "@nextLink": "inappacquisitions?applicationId=9NBLGGGZ5QDR&inAppProductId=&aggregationLevel=day&startDate=2015/01/01&endDate=2016/02/01&top=1&skip=1",
  "TotalCount": 33677
}