Uw eerste API-aanroep maken
Op deze pagina wordt uitgelegd hoe u uw eerste API-aanroep naar Apps en Games maakt.
API-aanroeppatroon
In het volgende diagram ziet u het API-aanroeppatroon dat wordt gebruikt om een nieuwe rapportsjabloon te maken, het aangepaste rapport te plannen en foutgegevens op te halen.
Deze lijst bevat meer informatie over het patroondiagram van de API-aanroep.
- De clienttoepassing kan het aangepaste rapportschema/de sjabloon definiëren door de API Rapportquery maken aan te roepen. U kunt ook een rapportsjabloon
(QueryId)
gebruiken in de lijst met systeemquery's. - Bij succes retourneert de API voor het maken van rapportsjablonen de
QueryId
. - De clienttoepassing roept vervolgens de Create Report API aan met de begindatum van het rapport, herhalingsinterval, herhaling en een optionele callback-URI.
- Bij succes retourneert de API om rapporten te maken de
ReportID
. - De clienttoepassing roept de Status-API aan om de status van het rapport op te halen.
- De clienttoepassing gebruikt vervolgens de API voor het ophalen van rapportuitvoeringen om een query uit te voeren op de status van het rapport met het
Report ID
datumbereik. - Bij succes wordt de downloadkoppeling voor het rapport geretourneerd en kan de toepassing het downloaden van de gegevens initiëren.
Rapportquerytaal opgeven
Hoewel we systeemquery's bieden die u kunt gebruiken om rapporten te maken, kunt u ook uw eigen query's maken op basis van uw bedrijfsbehoeften. Zie Aangepaste queryspecificatie voor meer informatie over aangepaste query's.
Verificatie
Voer eerst onboarding uit naar het Partnercentrum-account door de vereisten voor het gebruik van de Microsoft Store Analytics-API te voltooien. Haal vervolgens een Microsoft Entra-toegangstoken op. Volg stap 1 en stap 2 alleen. Stap 3 is redundant voor deze stroom.
Programmatische API-aanroep
Nadat u het Microsoft Entra-token hebt verkregen zoals beschreven in de vorige sectie, volgt u deze stappen om uw eerste programmatische toegangsrapport te maken.
Gegevens kunnen worden gedownload uit de volgende gegevenssets (datasetName):
Rapportnaam | Naam van gegevensset in API |
---|---|
Verwerving | Acquisities |
Overname van uitbreidingen | AddOnAcquisitions |
Kanalen en conversie | ChannelsAndConversions |
Gamepass-gebruik | GamePass |
Gamepass-prestaties | Aankoop van GamePass |
Gezondheid: Crashes en gebeurtenissen | HealthFailureHits |
Installeert | Installeert |
Beoordelingen | Beoordelingen |
Recensies | Recensies |
Duurzaamheid | Duurzaamheid |
Dagelijks gebruik | Dagelijks Gebruik |
Maandelijks gebruik | Maandelijks Gebruik |
Wenslijst | Wenslijst |
Betrokkenheid bij evenementen | Xevents_Metrics |
Prijspromoties - Flexibel | Xprice_Flexible_Offer |
Prijsacties - Doelgericht | Xprice_Targeted_Offer |
In de volgende secties ziet u voorbeelden van het programmatisch openen van de inhoud uit de gegevensset Overname.
Een REST-aanroep maken met behulp van de GET Datasets-API
Het API-antwoord bevat de naam van de gegevensset van waaruit u het rapport kunt downloaden. Voor de specifieke gegevensset bevat het API-antwoord ook de lijst met selecteerbare kolommen die kunnen worden gebruikt voor uw aangepaste rapportsjabloon.
Rapportquery-API maken
Deze API helpt bij het maken van aangepaste query's waarmee de gegevensset wordt gedefinieerd waaruit kolommen en metrische gegevens moeten worden geëxporteerd. De API biedt de flexibiliteit om een nieuwe rapportagesjabloon te maken op basis van uw bedrijfsbehoeften.
U kunt ook de systeemquery's gebruiken die we bieden. Wanneer aangepaste rapportsjablonen niet nodig zijn, kunt u de Rapport-API rechtstreeks aanroepen met behulp van de QueryIds van de systeemquery's die wij bieden.
Aanvraagvoorbeeld
curl
--location
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \
--header 'Authorization: Bearer <AzureADToken>'
Responsvoorbeeld
{
"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
}
}
De aangepaste query maken
In deze stap maken we een aangepaste query voor het gewenste rapport. Deze query wordt gebruikt telkens wanneer er een rapport is vereist (execute now
of schedule
).
Aanvraagvoorbeeld
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."
}'
Responsvoorbeeld
{
"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
}
Bij een geslaagde uitvoering van de query wordt een queryId gegenereerd die moet worden gebruikt om het rapport te genereren.
Query ophalen
Geeft een lijst weer van alle beschikbare query's. De bestaande query die in de bovenstaande stap is gemaakt, moet hier worden weergegeven.
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \
--header 'Authorization: Bearer <token> \
Responsvoorbeeld
{
"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
}
Een direct asynchroon rapport maken
In deze stap gebruiken we de eerder gegenereerde QueryId om het rapport te maken. De onderstaande query wordt gebruikt om nu het rapport uit te voeren. Het genereren van rapporten is asynchroon en vereist een afzonderlijke API-aanroep om het rapport op te halen.
Aanvraagvoorbeeld
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
}'
Responsvoorbeeld
{
"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
}
De reportId: 'execution' wordt gegenereerd. Deze id moet worden gebruikt om een download van het rapport te plannen.
Notitie
Raadpleeg Inzicht in het veld totalRecurrenceCount voor geplande rapporten voor meer informatie over het totalRecurrenceCount
-veld.
Het directe rapport downloaden
Aanvraagvoorbeeld
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \
--header 'Authorization: Bearer <token>' \
Responsvoorbeeld
{
"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
}
De reportAccessSecureLink kan worden aangeroepen om het rapport te downloaden.
Een planningsrapport maken
De API-aanroepen helpen bij het maken van een planningsrapport.
Aanvragen
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
}'
Antwoord
{
"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
}
Rapportstatus bekijken en details ophalen
Nu we een rapport hebben gemaakt, maken we een API-aanroep om de rapportstatus en de downloadbare koppeling op te halen, zodat het rapport naar de client kan worden gedownload. Om deze aanroep te maken, voeren we een query uit met dezelfde reportId die in de vorige stap is gegenereerd.
Aanvragen
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \
--header 'Authorization: Bearer<token>' \
Reactie
{
"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
}
Een planningsrapport maken met webhook
De webhook fungeert als een eindpunt dat wordt aangeroepen zodra het rapport gereed is. De callbackURL-parameter moet worden opgegeven.
Partners moeten hun webhook-handler ontwikkelen. Wanneer het rapport klaar is in het vorige voorbeeld, wordt de 'https://msnotify.com' aangeroepen als een melding. In de aanroep kunnen partners de lijst met geplande rapporten en hun statussen ophalen en vervolgens de hierboven genoemde API's gebruiken om het bestand te downloaden.
Aanvragen
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-documentatie
Raadpleeg de OpenAPI-specificatie. Plak de inhoud van de specificatie in de public Swagger-editor om de API's te bekijken en clients te genereren in voorkeurstalen (C#, python, enzovoort) om de API's te gebruiken.
Belangrijk
Deze API heeft standaardqueryparameters ingesteld voor executionStatus=Completed
en getLatestExecution=true
. Daarom zal het aanroepen van de API voordat de eerste geslaagde uitvoering van het rapport voltooid is, een 404-fout opleveren. Uitvoeringen die in behandeling zijn, kunnen worden verkregen door executionStatus=Pending
in te stellen.