アドオンの入手数の取得

[アーティクル]
01/17/2024

特定の日付範囲やその他オプションのフィルター内で、アプリのアドオンの集計入手データを JSON 形式で取得するには、Microsoft Store 分析 API の次のメソッドを使用します。この情報は、パートナーセンターのアドオン取得レポートでも確認できます。

前提条件

このメソッドを使うには、最初に次の作業を行う必要があります。

Microsoft Store 分析 API に関するすべての前提条件を満たします (前提条件がまだ満たされていない場合)。
このメソッドの要求ヘッダーで使う Azure AD アクセストークンを取得します。アクセストークンを取得した後、アクセストークンを使用できるのは、その有効期限が切れるまでの 60 分間です。トークンの有効期限が切れたら新しいトークンを取得できます。

要求

要求の構文

認証方法	要求 URI
GET	`https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions`

要求ヘッダー

Header	型	説明
承認	string	必須。 Bearer<トークン> という形式の Azure AD アクセストークン。

要求パラメーター

applicationId または inAppProductId パラメーターは必須です。アプリに登録されているすべてのアドオンの入手データを取得するには、applicationId パラメーターを指定します。単一のアドオンの入手データを取得するには、inAppProductId パラメーターを指定します。両方を指定した場合、applicationId パラメーターは無視されます。

パラメーター	型	内容	必須
applicationId	string	アドオンの入手データを取得するアプリの Store ID。	はい
inAppProductId	string	入手データを取得するアドオンの Store ID。	はい
startDate	日付	取得するアドオン入手データの期間の開始日。既定値は現在の日付です。	いいえ
endDate	日付	取得するアドオン入手データの期間の終了日。既定値は現在の日付です。	いいえ
top	int	要求で返すデータの行数です。最大値および指定しない場合の既定値は 10000 です。クエリにこれを上回る行がある場合は、応答本文に次リンクが含まれ、そのリンクを使ってデータの次のページを要求できます。	いいえ
skip	int	クエリでスキップする行数です。大きなデータセットを操作するには、このパラメーターを使用します。たとえば、top=10000 と skip=0 を指定すると、データの最初の 10,000 行が取得され、top=10000 と skip=10000 を指定すると、データの次の 10,000 行が取得されます。	No
filter	string	応答内の行をフィルター処理する 1 つまたは複数のステートメントです。詳しくは、次の「フィルターフィールド」セクションをご覧ください。	No
aggregationLevel	string	集計データを取得する時間範囲を指定します。次のいずれかの文字列を指定できます。day、week、または month。指定しない場合、既定値は day です。	No
orderby	string	各アドオン入手の結果データ値の順序を指定するステートメント。構文は orderby=field [order],field [order],... です。field パラメーターは次のいずれかの文字列になります。 date acquisitionType ageGroup storeClient gender market osVersion deviceType orderName order パラメーターは省略可能であり、asc または desc を指定して、各フィールドを昇順または降順にすることができます。既定値は asc です。 orderby 文字列の例: orderby=date,market	No
groupby	string	指定したフィールドのみにデータ集計を適用するステートメントです。次のフィールドを指定できます。 date applicationName inAppProductName acquisitionType ageGroup storeClient gender market osVersion deviceType orderName 返されるデータ行には、groupby パラメーターで指定されたフィールドと、次のものが含まれます。 date applicationId inAppProductId acquisitionQuantity groupby パラメーターは、aggregationLevel パラメーターと同時に使用できます。例: &groupby=ageGroup,market&aggregationLevel=week	いいえ

フィルターフィールド

要求の filter パラメーターには、応答内の行をフィルター処理する 1 つまたは複数のステートメントが含まれます。各ステートメントには eq 演算子または ne 演算子と関連付けられるフィールドと値が含まれ、and または or を使ってステートメントを組み合わせることができます。 filter パラメーターの例を次に示します。

filter=market eq 'US' and gender eq 'm'
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’)

サポートされているフィールドの一覧については、次の表をご覧ください。 filter パラメーターでは、文字列値を単一引用符で囲む必要があります。

Fields	説明
acquisitionType	次の文字列のいずれかです。 free trial paid promotional code iap
ageGroup	次の文字列のいずれかです。 less than 13 13-17 18-24 25-34 35-44 44-55 greater than 55 不明
storeClient	次の文字列のいずれかです。 Windows Phone Store (client) Microsoft Store (クライアント) Microsoft Store (ウェブ) Volume purchase by organizations その他
性別	次の文字列のいずれかです。 m f 不明
market	入手が行われた市場の、ISO 3166 国コードで記述された文字列。
osVersion	次の文字列のいずれかです。 Windows Phone 7.5 Windows Phone 8 Windows Phone 8.1 Windows Phone 10 Windows 8 Windows 8.1 Windows 10 Windows 11 不明
deviceType	次の文字列のいずれかです。 PC 電話 Console-Xbox One Console-Xbox Series X IoT Holographic 不明
orderName	アドオンの取得に使用されたプロモーションコードの注文の名前を指定する文字列 (これは、ユーザーがプロモーションコードを利用してアドオンを取得した場合にのみ適用されます)。

要求の例

アドオン入手データを取得するための要求の例を、いくつか次に示します。 inAppProductId と applicationId の値は、アドオンまたはアプリの適切なストア ID に置き換えます。

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>

回答

応答本文

値	種類	説明
値	配列	アドオン入手集計データが格納されているオブジェクトの配列。各オブジェクト内のデータの詳細については、以下の「アドオン入手値」セクションを参照してください。
@nextLink	string	データの追加ページがある場合、この文字列には、データの次のページを要求するために使用できる URI が含まれます。たとえば、要求の top パラメーターが 10000 に設定されていて、そのクエリに対するアドオン取得データが 10,000 行を超える場合に、この値が返されます。
TotalCount	int	クエリの結果データ内の行の総数です。

アドオン入手値

Value 配列の要素には、次の値が含まれます。

値	種類	説明
date	string	入手データの期間の最初の日付。要求に日付を指定した場合、この値はその日付になります。要求に週、月、またはその他の日付範囲を指定した場合、この値はその日付範囲の最初の日付になります。
inAppProductId	string	取得データの対象であるアドオンの Store ID。
inAppProductName	string	アドオンの表示名この値は、aggregationLevel パラメーターが day に設定されている場合 (かつ、groupby パラメーターに inAppProductName フィールドを指定していない場合) にのみ応答データに表示されます。
applicationId	string	アドオン取得データの対象であるアプリの Store ID。
applicationName	string	アプリの表示名です。
deviceType	string	取得を完了したデバイスの種類。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
orderName	string	トリガーの名前。
storeClient	string	入手が行われた Store のバージョン。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
osVersion	string	入手が行われた OS バージョン。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
market	string	入手が行われた市場の ISO 3166 国コード。
性別	string	取得を行ったユーザーの性別。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
ageGroup	string	取得を行ったユーザーの年齢グループ。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
acquisitionType	string	取得の種類 (free、paid その他)。サポートされる文字列の一覧については、前の「フィルターフィールド」セクションをご覧ください。
acquisitionQuantity	integer	発生した入手の数。

要求と応答の例

以下のコードスニペットは、要求の例、およびこれらの要求の JSON 返信の本文を示しています。

サンプル要求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

サンプル応答

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NBLGGAAGZDQ",
            "date": "2022-07-29",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 18.12,
            "purchasePriceLocalAmount": 18.12,
            "purchaseTaxUSDAmount": 1.13,
            "purchaseTaxLocalAmount": 1.13
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Episode 4",
            "addonProductId": "9NAAAAAAAAAQ",
            "date": "2017-01-07",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 4.147206,
            "purchasePriceLocalAmount": 3.99,
            "purchaseTaxUSDAmount": 0.686004,
            "purchaseTaxLocalAmount": 0.66
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NALGGGZ5QDQ",
            "date": "2018-04-01",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.99,
            "purchasePriceLocalAmount": 1.99,
            "purchaseTaxUSDAmount": 0.0,
            "purchaseTaxLocalAmount": 0.0
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Strategy Guide Episode 4",
            "addonProductId": "9NBLGGGZ5QDQ",
            "date": "2021-11-25",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.31902922876179,
            "purchasePriceLocalAmount": 150.0,
            "purchaseTaxUSDAmount": 0.114315866492689,
            "purchaseTaxLocalAmount": 13.0
        },
    ],
    "TotalCount": 4,
    "DataFreshnessTimestamp": "2022-07-29T05:54:00"
}

次の方法で共有

アドオンの入手数の取得

前提条件

要求

要求の構文

要求ヘッダー

要求パラメーター

フィルターフィールド

要求の例

回答

応答本文

アドオン入手値

要求と応答の例

サンプル要求

サンプル応答

フィードバック

その他のリソース

次の方法で共有

アドオンの入手数の取得

前提条件

要求

要求の構文

要求ヘッダー

要求パラメーター

フィルター フィールド

要求の例

回答

応答本文

アドオン入手値

要求と応答の例

サンプル要求

サンプル応答

関連トピック

フィードバック

その他のリソース

フィルターフィールド