最初の API 呼び出しを作成する

[アーティクル]
06/13/2024

このページでは、アプリとゲームへの最初の API 呼び出しを行う方法について説明します。

API 呼び出しパターン

次の図は、新しいレポートテンプレートの作成、カスタムレポートのスケジュール設定、およびエラーデータの取得に使用される API 呼び出しパターンを示しています。

この一覧では、API 呼び出しパターン図の詳細を示します。

クライアントアプリケーションは、レポートクエリの作成 API を呼び出すことによって、カスタムレポートスキーマ/テンプレートを定義できます。または、システムクエリの一覧からレポートテンプレート(QueryId)を使用することもできます。
成功した場合、レポートテンプレートの 作成 API はを QueryId返します。
その後、クライアントアプリケーションでは、QueryID と共にレポートの開始日、繰り返し間隔、繰り返し回数、およびオプションのコールバック URI を使用して、レポートの作成 API を呼び出します。
成功した場合、レポートの作成 API から ReportID が返されます。
クライアントアプリケーションは Status API を呼び出してレポートの状態を取得します。
その後、クライアントアプリケーションで レポート実行状態の取得 API を使用し、Report ID と日付範囲を指定してレポートの状態のクエリを実行します。
成功すると、レポートのダウンロードリンクが返され、アプリケーションでデータのダウンロードを開始できます。

レポートクエリ言語を指定する

レポートの作成に使用できるシステムクエリが用意されていますが、ビジネスニーズに基づいて独自のクエリを作成することもできます。カスタムクエリの詳細については、「カスタムクエリの仕様」を参照してください。

認証

まず、Microsoft Store 分析 API を使用するための前提条件を満たして、パートナーセンターアカウントにオンボードします。次に、 Microsoft Entra アクセストークンを取得します。手順 1 と手順 2 にのみ従ってください。手順 3 は、このフローに対して冗長です。

プログラムによる API 呼び出し

前のセクションで説明したように Microsoft Entra トークンを取得したら、次の手順に従って、最初のプログラムによるアクセスレポートを作成します。

データは、次のデータセット (datasetName) からダウンロードできます。

[レポート名]	API のデータセット名
取得	取得
アドオンの取得	AddOnAcquisitions
チャネルと変換	ChannelsAndConversions
Gamepass の使用状況	GamePass
Gamepass のパフォーマンス	GamePassPurchase
正常性: クラッシュとイベント	HealthFailureHits
インストール	インストール
Ratings	Ratings
レビュー	レビュー
持続可能性	持続可能性
Usage-Daily	UsageDaily
Usage-Monthly	UsageMonthly
Wishlist	Wishlist
Events Engagement	Xevents_Metrics
価格プロモーション - 柔軟	Xprice_Flexible_Offer
価格プロモーション - 対象	Xprice_Targeted_Offer

次のセクションでは、Acquisition データセットからコンテンツにプログラムでアクセスする方法の例を示します。

データセットの取得 API を使用して REST 呼び出しを行う

この API 応答では、レポートをダウンロードできるデータセット名が提供されます。特定のデータセットについては、この API 応答でカスタムレポートテンプレートに使用できる選択可能な列の一覧も提供されます。

レポートクエリの作成 API

この API では、列およびメトリックのエクスポート元となるデータセットを定義するカスタムクエリを作成できます。この API は、ビジネスニーズに基づいて新しいレポートテンプレートを作成するための柔軟性を提供します。

また、用意されているシステムクエリを使用することもできます。カスタムレポートテンプレートが必要ない場合は、提供するシステムクエリの QueryId を使用して、レポートの作成 API を直接呼び出すことができます。

要求の例

curl  
--location  
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \  
--header 'Authorization: Bearer <AzureADToken>'

応答の例

{ 
    "value": [ 
        { 
            "columnFilters": {}, 
            "aggregationToDateRangeMapping": { 
                "Hourly": "LAST_72_HOURS", 
                "Daily": "LAST_30_DAYS,LAST_3_MONTHS", 
                "Weekly": "LAST_6_MONTHS,LAST_12_MONTHS", 
                "Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS" 
            }, 
            "datasetName": "Acquisitions", 
            "selectableColumns": [ 
                "TitleId", 
                "ProductId", 
                "XboxProductId", 
                "ProductTypeName", 
                "TitleName", 
                "CatalogId", 
                "SandboxId", 
                "SkuId", 
                "SkuTypeName", 
                "SkuDisplayName", 
                "AvailabilityId", 
                "RegionName", 
                "CountryName", 
                "Market", 
                "PaymentType", 
                "StoreClientName", 
                "StoreClientCategory", 
                "ParentProductName", 
                "ParentProductId", 
                "XboxParentProductId", 
                "AcquisitionType", 
                "PurchaseTaxType", 
                "LocalCurrencyCode", 
                "SupportedPlatform", 
                "Age", 
                "Gender", 
                "OsVersion", 
                "DeviceType", 
                "DateStamp" 
            ], 
            "availableMetrics": [ 
                "PurchaseQuantity", 
                "PurchasePriceUSDAmount", 
                "PurchaseTaxUSDAmount", 
                "PurchasePriceLocalAmount", 
                "PurchaseTaxLocalAmount" 
            ], 
            "availableDateRanges": [ 
                "LAST_72_HOURS", 
                "LAST_30_DAYS", 
                "LAST_3_MONTHS", 
                "LAST_6_MONTHS", 
                "LAST_12_MONTHS", 
                "LAST_2_YEARS", 
                "LAST_3_YEARS", 
                "LAST_4_YEARS" 
            ], 
            "minimumRecurrenceInterval": 1 
        } 
}

カスタムクエリを作成する

この手順では、必要なレポートのカスタムクエリを作成します。作成されたこのクエリは、レポートが必要な (execute now または schedule) たびに使用されます。

要求の例

curl  
--location  
--request POST ' https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \  
--header ' Authorization: Bearer <AzureAD_Token>' \  
--header 'Content-Type: application/json' \  
--data-raw  
            '{  
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",  
    "Name": "Consumer public API Create query",  
    "Description": "Acquisition query creation."  
}'

応答の例

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Query created successfully", 
    "statusCode": 200 
}

クエリが正常に実行されると、 レポートの生成に使用する必要がある queryId が生成されます。

クエリを取得する

使用可能なすべてのクエリを一覧表示します。上記の手順で作成した既存のクエリは、ここに反映されている必要があります。

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \ 
--header 'Authorization: Bearer <token> \

応答の例

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        }, 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "9PDC2J734M08", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "724c796e-ea64-438f-b784-f2e284349d2f", 
            "name": "Acquisition_Daily_30days_next2months", 
            "description": null, 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, DateStamp, PurchaseQuantity, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-01-23T17:21:42Z" 
        } 
    ], 
    "totalCount": 2, 
    "message": "Queries fetched successfully", 
    "statusCode": 200 
}

インスタント非同期レポートを作成する

この手順では、以前に生成された QueryId を 使用してレポートを作成します。次のクエリは、レポートを実行するために使用されます。レポートの生成は非同期であり、レポートをフェッチするには別の API 呼び出しが必要です。

要求の例

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer {{token}} \  
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create Report - Acquisition", 
"executeNow": true 
}'

応答の例

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "reportName": "Create Report - Acquisition", 
            "description": " Acquisition report ", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "", 
            "modifiedTime": null, 
            "executeNow": true, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T11:33:16Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

reportId: 'execution' が生成されます。この ID は、レポートのダウンロードをスケジュールするために使用する必要があります。

インスタントレポートをダウンロードする

要求の例

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \ 
--header 'Authorization: Bearer <token>' \

応答の例

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

reportAccessSecureLink を呼び出してレポートをダウンロードできます。

スケジュールレポートを作成する

API 呼び出しは、スケジュールレポートの作成に役立ちます。

要求

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer <token> \ 
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Creating a scheduled report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1 
}'

回答

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "reportName": "Create scheduled report - Acquisition", 
            "description": "Acquisition description", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "2024-03-26T11:38:20Z", 
            "modifiedTime": null, 
            "executeNow": false, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T18:00:19Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": 1, 
            "recurrenceCount": 49, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-28T18:00:19Z", 
            "totalRecurrenceCount": 49, 
            "nextExecutionStartTime": "2024-03-26T17:00:19Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

レポートの状態を取得し、詳細をダウンロードする

レポートを作成したので、API 呼び出しを行ってレポートの状態とそのダウンロード可能なリンクを取得し、レポートをクライアントにダウンロードできるようにします。この呼び出しを行うために、前の手順で生成されたのと同じ reportId を 使用してクエリを実行します。

要求

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \ 
--header 'Authorization: Bearer<token>' \

回答

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

webhook を使用してスケジュールレポートを作成する

Webhook は、レポートの準備ができたらすぐに呼び出されるエンドポイントとして機能します。 callbackURL パラメーターを指定する必要があります。

パートナーは、Webhook ハンドラーを記述する必要があります。前の例では、レポートの準備ができたら、'https://msnotify.com' が通知として呼び出されます。呼び出し時に、パートナーはスケジュールされたレポートとその状態の一覧を取得し、上記の API を使用してファイルをダウンロードできます。

要求

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer<token>' \ 
--header 'Content-Type: application/json' \ 
--header 'Cookie: ApplicationGatewayAffinity=3ebb3a6588e1f91ad543ccd7cdf31ec0; ApplicationGatewayAffinityCORS=3ebb3a6588e1f91ad543ccd7cdf31ec0' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1, 
"callbackURL": "https://msnotify.com", 
"callbackMethod": "get" 
}'

API ドキュメント

OpenAPI の仕様を参照してください。パブリック Swagger エディターに仕様の内容を貼り付けて API を表示し、API を使用するための優先言語 (C#、python など) でクライアントを生成します。

重要

この API には、既定のクエリパラメーターとして executionStatus=Completed および getLatestExecution=true が設定されています。そのため、レポートが最初に正常に実行される前に API を呼び出すと、404 エラーが返されます。保留中の実行は、executionStatus=Pending を設定することによって取得できます。

次の方法で共有

最初の API 呼び出しを作成する

API 呼び出しパターン

レポートクエリ言語を指定する

認証

プログラムによる API 呼び出し

データセットの取得 API を使用して REST 呼び出しを行う

レポートクエリの作成 API

要求の例

応答の例

カスタムクエリを作成する

要求の例

応答の例

クエリを取得する

応答の例

インスタント非同期レポートを作成する

要求の例

応答の例

インスタントレポートをダウンロードする

要求の例

応答の例

スケジュールレポートを作成する

要求

回答

レポートの状態を取得し、詳細をダウンロードする

要求

回答

webhook を使用してスケジュールレポートを作成する

要求

API ドキュメント

フィードバック

その他のリソース

次の方法で共有

最初の API 呼び出しを作成する

API 呼び出しパターン

レポート クエリ言語を指定する

認証

プログラムによる API 呼び出し

データセットの取得 API を使用して REST 呼び出しを行う

レポート クエリの作成 API

要求の例

応答の例

カスタム クエリを作成する

要求の例

応答の例

クエリを取得する

応答の例

インスタント非同期レポートを作成する

要求の例

応答の例

インスタント レポートをダウンロードする

要求の例

応答の例

スケジュール レポートを作成する

要求

回答

レポートの状態を取得し、詳細をダウンロードする

要求

回答

webhook を使用してスケジュール レポートを作成する

要求

API ドキュメント

フィードバック

その他のリソース

レポートクエリ言語を指定する

レポートクエリの作成 API

カスタムクエリを作成する

インスタントレポートをダウンロードする

スケジュールレポートを作成する

webhook を使用してスケジュールレポートを作成する