Effettuare la prima chiamata API

Articolo
01/31/2025

Questa pagina illustra come effettuare la prima chiamata API ad App e Giochi.

Modello di chiamata API

Il diagramma seguente illustra il modello di chiamata API usato per creare un nuovo modello di report, pianificare il report personalizzato e recuperare i dati sugli errori.

Questo elenco fornisce altri dettagli sul diagramma dei modelli di chiamata API.

L'applicazione client può definire lo schema/modello di report personalizzato chiamando l'API Crea query report. In alternativa, è possibile usare un modello (QueryId) di report dall'elenco di query di sistema.
In caso di esito positivo, l'API Crea modello di report restituisce .QueryId
L'applicazione client chiama quindi l'API Crea report usando insieme alla QueryID data di inizio del report, all'intervallo di ripetizione, alla ricorrenza e a un URI di callback facoltativo.
In caso di esito positivo, l'API Crea report restituisce .ReportID
L'applicazione client chiama l'API Stato per ottenere lo stato del report.
L'applicazione client usa quindi l'API Get Report Executions per eseguire una query sullo stato del report con l'intervallo Report ID di date e .
In caso di esito positivo, viene restituito il collegamento di download del report e l'applicazione può avviare il download dei dati.

Specificare il linguaggio di query del report

Sebbene siano disponibili query di sistema che è possibile usare per creare report, è anche possibile creare query personalizzate in base alle esigenze aziendali. Per altre informazioni sulle query personalizzate, vedere Specifica di query personalizzata.

Autenticazione

Prima di tutto, eseguire l'onboarding nell'account del Centro per i partner completando i prerequisiti per l'uso dell'API di analisi di Microsoft Store. Ottenere quindi un token di accesso Microsoft Entra. Seguire solo il passaggio 1 e il passaggio 2. Il passaggio 3 è ridondante per questo flusso.

Chiamata API a livello di codice

Dopo aver ottenuto il token Microsoft Entra come descritto nella sezione precedente, seguire questa procedura per creare il primo report di accesso a livello di codice.

I dati possono essere scaricati dai set di dati seguenti (datasetName):

Nome del report	Nome del set di dati nell'API
Acquisizione	Acquisizioni
Acquisizione di componenti aggiuntivi	AddOnAcquisitions
Canali e conversioni	ChannelsAndConversions
Utilizzo gamepass	GamePass
Prestazioni gamepass	GamePassPurchase
Integrità: arresti anomali ed eventi	HealthFailureHits
Installs	Installs
Ratings	Ratings
Recensioni	Recensioni
Sostenibilità	Sostenibilità
Utilizzo giornaliero	UsageDaily
Utilizzo mensile	UsageMonthly
Elenco dei desideri	Elenco dei desideri
Engagement degli eventi	Xevents_Metrics
Promozioni tariffarie - Flessibili	Xprice_Flexible_Offer
Promozioni dei prezzi - Mirato	Xprice_Targeted_Offer

Le sezioni seguenti illustrano esempi di come accedere a livello di codice al contenuto dal set di dati Acquisizione.

Effettuare una chiamata REST usando l'API Get Datasets

La risposta DELL'API fornisce il nome del set di dati da cui è possibile scaricare il report. Per il set di dati specifico, la risposta api fornisce anche l'elenco di colonne selezionabili che possono essere usate per il modello di report personalizzato.

Creare un'API di query del report

Questa API consente di creare query personalizzate che definiscono il set di dati da cui devono essere esportate colonne e metriche. L'API offre la flessibilità necessaria per creare un nuovo modello di report in base alle esigenze aziendali.

È anche possibile usare le query di sistema fornite. Quando i modelli di report personalizzati non sono necessari, è possibile chiamare l'API Crea report direttamente usando i valori QueryId delle query di sistema fornite.

Esempio di richiesta

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

Risposta di esempio

{ 
    "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 
        } 
}

Creare la query personalizzata

In questo passaggio viene creata una query personalizzata per il report desiderato. Questa query creata viene usata ogni volta che è presente un report obbligatorio (execute now o schedule).

Esempio di richiesta

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."  
}'

Risposta di esempio

{ 
    "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 
}

Al termine dell'esecuzione della query, viene generato un valore queryId che deve essere usato per generare il report.

Ottenere una query

Elenca tutte le query disponibili. La query esistente creata nel passaggio precedente dovrebbe riflettere qui.

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

Risposta di esempio

{ 
    "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 
}

Creare un report asincrono istantaneo

In questo passaggio viene usato il valore QueryId generato in precedenza per creare il report. La query seguente viene usata per eseguire ora il report. La generazione di report è asincrona e richiede una chiamata API separata per recuperare il report.

Esempio di richiesta

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 
}'

Risposta di esempio

{ 
    "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 
}

Il reportId: 'execution' viene generato. Questo ID deve essere usato per pianificare un download del report.

Nota

Per informazioni dettagliate sul totalRecurrenceCount campo, vedere Informazioni sul campo totalRecurrenceCount per i report pianificati.

Scaricare il report istantaneo

Esempio di richiesta

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

Risposta di esempio

{ 
    "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 
}

È possibile richiamare reportAccessSecureLink per scaricare il report.

Creare un report di pianificazione

Le chiamate API consentono di creare un report di pianificazione.

Richiedi

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 
}'

Risposta

{ 
    "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 
}

Ottenere lo stato del report e scaricare i dettagli

Dopo aver creato un report, verrà eseguita una chiamata API per ottenere lo stato del report e il relativo collegamento scaricabile in modo che il report possa essere scaricato nel client. Per effettuare questa chiamata, viene eseguita una query con lo stesso id report generato nel passaggio precedente.

Richiedi

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

Risposta

{ 
    "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 
}

Creare un report di pianificazione con webhook

Il webhook funziona come endpoint richiamato non appena il report è pronto. È necessario specificare il parametro callbackURL .

I partner devono scrivere il gestore webhook. Nell'esempio precedente, quando il report è pronto, viene richiamato "https://msnotify.com" come notifica. Nella chiamata, i partner possono ottenere l'elenco di report pianificati e i relativi stati e quindi usare le API indicate in precedenza per scaricare il file.

Richiedi

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" 
}'

Documentazione API

Fare riferimento alla specifica OpenAPI. Incollare il contenuto della specifica nell'editor Swagger pubblico per visualizzare le API e generare client in linguaggi preferiti (C#, Python e così via) per usare le API.

Importante

Questa API ha parametri di query predefiniti impostati per executionStatus=Completed e getLatestExecution=true. Di conseguenza, la chiamata all'API prima della prima esecuzione corretta del report restituirà un errore 404. Le esecuzioni in sospeso possono essere ottenute impostando executionStatus=Pending.

Condividi tramite

Effettuare la prima chiamata API

Modello di chiamata API

Specificare il linguaggio di query del report

Autenticazione

Chiamata API a livello di codice

Effettuare una chiamata REST usando l'API Get Datasets

Creare un'API di query del report

Esempio di richiesta

Risposta di esempio

Creare la query personalizzata

Esempio di richiesta

Risposta di esempio

Ottenere una query

Risposta di esempio

Creare un report asincrono istantaneo

Esempio di richiesta

Risposta di esempio

Scaricare il report istantaneo

Esempio di richiesta

Risposta di esempio

Creare un report di pianificazione

Richiedi

Risposta

Ottenere lo stato del report e scaricare i dettagli

Richiedi

Risposta

Creare un report di pianificazione con webhook

Richiedi

Documentazione API

Commenti e suggerimenti

Risorse aggiuntive