ゲームとアプリのアドオン入手データを取得するGet add-on acquisitions data for your games and apps

Microsoft Store analytics API でこのメソッドを使用して、XDP Analytics パートナーセンターのダッシュボードで使用できる UWP アプリおよび Xbox One ゲーム用の JSON 形式で、集計されたアドオン取得データを取得します。Use this method in the Microsoft Store analytics API to get aggregate add-on acquisition data in JSON format for UWP apps and Xbox One games that were ingested through the Xbox Developer Portal (XDP) and available in the XDP Analytics Partner Center dashboard.

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

注意

この API では、2016年10月1日より前に日単位の集計データは提供されません。This API does not provide daily aggregate data before Oct 1st 2016.

RequestRequest

要求の構文Request syntax

認証方法Method 要求 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

要求ヘッダーRequest header

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

要求パラメーターRequest parameters

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

パラメーターParameter 種類Type 説明Description 必須Required
applicationIdapplicationId stringstring 取得データを取得する Xbox One ゲームのproductIdThe productId of the Xbox One game for which you are retrieving acquisition data. ゲームのproductidを取得するには、XDP Analytics プログラムでゲームに移動し、URL からproductidを取得します。To get the productId of your game, navigate to your game in the XDP Analytics Program and retrieve the productId from the URL. または、パートナーセンター分析レポートから取得データをダウンロードする場合は、 productIdが .tsv ファイルに含まれています。Alternatively, if you download your acquisitions data from the Partner Center analytics report, the productId is included in the .tsv file. はいYes
addonProductIdaddonProductId stringstring 取得データを取得する対象となるアドオンのproductIdThe productId 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. いいえNo
endDateendDate 日付date 取得するアドオン入手データの日付範囲終了日です。The end date in the date range of add-on acquisition data to retrieve. 既定値は現在の日付です。The default is the current date. いいえNo
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. いいえNo
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. いいえNo
filterfilter stringstring 応答内の行をフィルター処理する 1 つまたは複数のステートメントです。One or more statements that filter the rows in the response. 各ステートメントには、応答本文からのフィールド名、および eq 演算子または ne 演算子と関連付けられる値が含まれており、and や or を使用してステートメントを組み合わせることができます。Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. filter パラメーターでは、文字列値を単一引用符で囲む必要があります。String values must be surrounded by single quotes in the filter parameter. たとえば、「filter=market eq 'US' and gender eq 'm'」のように指定します。For example, filter=market eq 'US' and gender eq 'm'.
応答本文から次のフィールドを指定することができます。You can specify the following fields from the response body:
  • acquisitionTypeacquisitionType
  • 変更age
  • storeClientstoreClient
  • gendergender
  • マーケティングmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • sandboxIdsandboxId
いいえ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. いいえNo
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
  • 変更age
  • storeClientstoreClient
  • gendergender
  • マーケティングmarket
  • 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
いいえNo
groupbygroupby stringstring 指定したフィールドのみにデータ集計を適用するステートメントです。A statement that applies data aggregation only to the specified fields. 次のフィールドを指定できます。You can specify the following fields:
  • datedate
  • applicationNameapplicationName
  • addonProductNameaddonProductName
  • acquisitionTypeacquisitionType
  • 変更age
  • storeClientstoreClient
  • gendergender
  • マーケティングmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
返されるデータ行には、groupby パラメーターに指定したフィールドと次の値が含まれます。The returned data rows will contain the fields specified in the groupby parameter as well as the following:
  • datedate
  • applicationIdapplicationId
  • addonProductIdaddonProductId
  • acquisitionQuantityacquisitionQuantity
groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。The groupby parameter can be used with the aggregationLevel parameter. 例: &groupby = age、market&aggregationLevel = weekFor example: &groupby=age,market&aggregationLevel=week
いいえNo

要求の例Request example

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

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0 HTTP/1.1 

Authorization: Bearer <your access token> 

 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

[応答]Response

応答本文Response body

Value 種類Type 説明Description
Value 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.

Value 種類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.
addonProductIdaddonProductId stringstring 取得データを取得しているアドオンのproductIdThe productId of the add-on for which you are retrieving acquisition data.
addonProductNameaddonProductName stringstring アドオンの表示名です。The display name of the add-on. GroupbyパラメーターでaddonProductNameフィールドを指定しない限り、この値は、 aggregationLevelパラメーターがdayに設定されている場合にのみ、応答データに表示されます。This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the addonProductName field in the groupby parameter.
applicationIdapplicationId stringstring アドオン取得データを取得する対象のアプリのproductIdThe productId of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring ゲームの表示名です。The display name of the game.
deviceTypedeviceType stringstring 入手が完了したデバイスの種類を指定する、以下のいずれかの文字列です。One of the following strings that specifies the type of device that completed the acquisition:
  • PC"PC"
  • ダイヤル"Phone"
  • "Console-Xbox One""Console-Xbox One"
  • "コンソール-Xbox シリーズ X""Console-Xbox Series X"
  • IoT"IoT"
  • Server"Server"
  • Table"Tablet"
  • Holographic"Holographic"
  • 知ら"Unknown"
storeClientstoreClient stringstring 入手が発生した Store のバージョンを示す、以下のいずれかの文字列です。One of the following strings that indicates the version of the Store where the acquisition occurred:
  • "Windows Phone ストア (クライアント)""Windows Phone Store (client)"
  • "Microsoft Store (クライアント)" (2018 年3月23日より前にデータを照会する場合は "Windows ストア (クライアント)")"Microsoft Store (client)" (or "Windows Store (client)" if querying for data before March 23, 2018)
  • "Microsoft Store (web)" (2018 年3月23日より前にデータを照会する場合は "Windows ストア (web)")"Microsoft Store (web)" (or "Windows Store (web)" if querying for data before March 23, 2018)
  • "組織別のボリューム購入""Volume purchase by organizations"
  • 他の"Other"
osVersionosVersion stringstring 入手が発生した OS のバージョンです。The OS version on which the acquisition occurred. このメソッドでは、この値は常に "Windows 10" です。For this method, this value is always "Windows 10".
marketmarket stringstring 入手が発生した市場の ISO 3166 国コードです。The ISO 3166 country code of the market where the acquisition occurred.
gendergender stringstring 入手したユーザーの性別を指定する、以下のいずれかの文字列です。One of the following strings that specifies the gender of the user who made the acquisition:
  • "m""m"
  • "f""f"
  • 知ら"Unknown"
ageage stringstring 入手したユーザーの年齢グループを示す、以下のいずれかの文字列です。One of the following strings that indicates the age group of the user who made the acquisition:
  • "13 未満""less than 13"
  • "13-17""13-17"
  • "18-24""18-24"
  • "25-34""25-34"
  • "35-44""35-44"
  • "44-55""44-55"
  • "55 より大きい""greater than 55"
  • 知ら"Unknown"
acquisitionTypeacquisitionType stringstring 入手の種類を示す、以下のいずれかの文字列です。One of the following strings that indicates the type of acquisition:
  • 空け"Free"
  • サブスクリプション"Trial"
  • 貢物"Paid"
  • "プロモーションコード""Promotional code"
  • Iap"Iap"
  • "Subscription Iap""Subscription Iap"
  • "プライベートユーザー""Private Audience"
  • "事前の順序""Pre Order"
  • "Xbox ゲームパス" (2018 年3月23日より前にデータを照会する場合は "ゲームパス")"Xbox Game Pass" (or "Game Pass" if querying for data before March 23, 2018)
  • ディスク"Disk"
  • "前払いコード""Prepaid Code"
  • "課金される前の注文""Charged Pre Order"
  • "取り消された事前注文""Cancelled Pre Order"
  • "失敗した事前順序""Failed Pre Order"
acquisitionQuantityacquisitionQuantity 整数 (integer)integer 発生した入手の数です。The number of acquisitions that occurred.
inAppProductIdinAppProductId stringstring このアドオンが使用される製品の製品 ID。Product ID of the product where this add-on is used.
inAppProductNameinAppProductName stringstring このアドオンが使用される製品の製品名。Product Name of the product where this add-on is used.
paymentInstrumentTypepaymentInstrumentType stringstring 取得に使用する支払い方法の種類。Payment instrument type used for the acquisition.
sandboxIdsandboxId stringstring ゲーム用に作成されたサンドボックス ID。The Sandbox ID created for the game. この値には、小売の値またはプライベートサンドボックス ID を指定できます。This can be the value RETAIL or a private sandbox ID.
xboxTitleIdxboxTitleId stringstring XDP からの製品の Xbox タイトル ID (該当する場合)。Xbox Title ID of the product from XDP, if applicable.
localCurrencyCodelocalCurrencyCode stringstring パートナーセンターアカウントの国に基づく現地通貨コード。Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId stringstring XDP からの製品の Xbox 製品 ID (該当する場合)。Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId stringstring XDP からの製品の可用性 ID (該当する場合)。Availability ID of the product from XDP, if applicable.
skuIdskuId stringstring XDP からの製品の SKU ID (該当する場合)。SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName stringstring XDP からの製品の SKU 表示名 (該当する場合)。SKU Display Name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId stringstring XDP から製品の Xbox 親製品 ID (該当する場合)。Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName stringstring XDP からの製品の親製品名 (該当する場合)。Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName stringstring XDP からの製品の種類名 (該当する場合)。Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType stringstring XDP から製品の税の種類を購入します (該当する場合)。Purchase Tax Type of the product from XDP, if applicable.
purchasePriceUSDAmountpurchasePriceUSDAmount numbernumber このアドオンに関して顧客が支払った金額を、米国ドルに換算します。The amount paid by the customer for the add-on, converted to USD.
purchasePriceLocalAmountpurchasePriceLocalAmount numbernumber アドオンに適用された税額。The tax amount applied to the add-on.
purchaseTaxUSDAmountpurchaseTaxUSDAmount numbernumber アドオンに適用された税金額を米国ドルに変換した値。The tax amount applied to the add-on, converted to USD.
purchaseTaxLocalAmountpurchaseTaxLocalAmount numbernumber 該当する場合は、XDP から製品の税の現地金額を購入します。Purchase Tax Local Amount of the product from XDP, if applicable.

応答の例Response example

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

{ 
  "Value": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null, 
    
    "TotalCount": 7601 
}