Freigeben über

Durchführen Ihres ersten API-Aufrufs

  • Artikel

Auf dieser Seite wird erläutert, wie Sie Ihren ersten API-Aufruf an Apps und Spiele vornehmen.

API-Aufrufmuster

Das folgende Diagramm zeigt das API-Aufrufmuster zum Erstellen einer neuen Berichtsvorlage, zum Planen des benutzerdefinierten Berichts und zum Abrufen von Fehlerdaten.

Diagramm des allgemeinen Flusses des API-Aufrufmusters.

Diese Liste enthält weitere Details zum API-Aufrufmusterdiagramm.

  1. Die Clientanwendung kann das benutzerdefinierte Berichtsschema/die benutzerdefinierte Vorlage definieren, indem die Api zum Erstellen von Berichtsabfragen aufgerufen wird. Alternativ können Sie eine Berichtsvorlage (QueryId) aus der Liste der Systemabfragen verwenden.
  2. Bei Erfolg gibt die Create Report Template API die QueryId.
  3. Die Clientanwendung ruft dann die API zum Erstellen von Berichten mithilfe von QueryID zusammen mit dem Startdatum des Berichts, dem Wiederholungsintervall, der Serie und einem optionalen Rückruf-URI auf.
  4. Wenn der Vorgang erfolgreich ist, gibt die API zum Erstellen von Berichten ReportID zurück.
  5. Die Clientanwendung ruft die Status-API auf, um den Status des Berichts abzurufen.
  6. Die Clientanwendung verwendet dann die API zum Abrufen von Berichtsausführungen, um den Status des Berichts mit der Report ID und dem Datumsbereich abzufragen.
  7. Bei erfolgreicher Ausführung wird der Link zum Herunterladen des Berichts zurückgegeben, und die Anwendung kann den Download der Daten initiieren.

Angeben der Berichtsabfragesprache

Obwohl wir Systemabfragen bereitstellen, die Sie zum Erstellen von Berichten verwenden können, können Sie auch eigene Abfragen basierend auf Ihren geschäftlichen Anforderungen erstellen. Weitere Informationen zu benutzerdefinierten Abfragen finden Sie unter Spezifikation für benutzerdefinierte Abfragen.

Authentifizierung

Integrieren Sie zunächst das Onboarding in das Partner Center-Konto, indem Sie die Voraussetzungen für die Verwendung der Microsoft Store-Analyse-API abschließen. Rufen Sie als Nächstes ein Microsoft Entra-Zugriffstoken ab. Führen Sie nur Schritt 1 und Schritt 2 aus. Schritt 3 ist für diesen Fluss redundant.

Programmgesteuerter API-Aufruf

Nachdem Sie das Microsoft Entra-Token wie im vorherigen Abschnitt beschrieben abgerufen haben, führen Sie die folgenden Schritte aus, um Ihren ersten programmgesteuerten Zugriffsbericht zu erstellen.

Daten können aus den folgenden Datasets (datasetName) heruntergeladen werden:

Berichtsname Datasetname in API
Anschaffung Käufe
Add-On-Erwerb AddOnAcquisitions
Kanäle und Konvertierung ChannelsAndConversions
Gamepass-Nutzung GamePass
Gamepass-Leistung GamePassPurchase
Integrität: Abstürze und Ereignisse HealthFailureHits
Installs Installs
Bewertungen Bewertungen
Überprüfungen Überprüfungen
Nachhaltigkeit Nachhaltigkeit
Täglicher Einsatz UsageDaily
Nutzungsmonatlich UsageMonthly
Wunschliste Wunschliste
Ereignisbindung Xevents_Metrics
Preisaktionen - Flexibel Xprice_Flexible_Offer
Preisaktionen – gezielt Xprice_Targeted_Offer

Die folgenden Abschnitte zeigen Beispiele für den programmgesteuerten Zugriff auf den Inhalt aus dem Acquisition-Dataset.

Durchführen eines REST-Aufrufs mithilfe der API zum Abrufen von Datasets

Die API-Antwort enthält den Namen des Datasets, von dem aus Sie den Bericht herunterladen können. Die API-Antwort für das jeweilige Dataset enthält auch die Liste der auswählbaren Spalten, die für Ihre benutzerdefinierte Berichtsvorlage verwendet werden können.

Erstellen einer Berichtsabfrage-API

Mithilfe dieser API können Sie benutzerdefinierte Abfragen erstellen, mit denen das Dataset definiert wird, aus dem Spalten und Metriken exportiert werden müssen. Die API bietet die Flexibilität, die für das Erstellen einer neuen Berichtsvorlage notwendig ist, die auf den Anforderungen Ihres Unternehmens basiert.

Sie können ebenfalls die von uns bereitgestellten Systemabfragen verwenden. Wenn benutzerdefinierte Berichtsvorlagen nicht benötigt werden, können Sie die Berichts-API erstellen direkt mithilfe der Abfrage-ID der von uns bereitgestellten Systemabfragen aufrufen.

Anforderungsbeispiel

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

Beispielantwort

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

Erstellen der benutzerdefinierten Abfrage

In diesem Schritt erstellen wir eine benutzerdefinierte Abfrage für den gewünschten Bericht. Diese erstellte Abfrage wird jedes Mal verwendet, wenn ein Bericht erforderlich ist (execute now oder schedule).

Anforderungsbeispiel

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

Beispielantwort

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

Bei erfolgreicher Ausführung der Abfrage wird eine queryId generiert, die zum Generieren des Berichts verwendet werden muss.

Abfrage abrufen

Listet alle verfügbaren Abfragen auf. Die im obigen Schritt erstellte vorhandene Abfrage sollte hier enthalten sein.

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

Beispielantwort

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

Erstellen eines sofort asynchronen Berichts

In diesem Schritt verwenden wir die zuvor generierte QueryId , um den Bericht zu erstellen. Die folgende Abfrage wird verwendet, um jetzt den Bericht auszuführen. Die Berichtgenerierung ist asynchron und erfordert einen separaten API-Aufruf zum Abrufen des Berichts.

Anforderungsbeispiel

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

Beispielantwort

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

Die reportId: 'execution' wird generiert. Diese ID muss verwendet werden, um einen Download des Berichts zu planen.

Hinweis

Ausführliche Informationen zum totalRecurrenceCount Feld finden Sie unter "Grundlegendes zum feld totalRecurrenceCount" für geplante Berichte.

Herunterladen des Sofortberichts

Anforderungsbeispiel

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

Beispielantwort

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

Der reportAccessSecureLink kann aufgerufen werden, um den Bericht herunterzuladen.

Erstellen eines Zeitplanberichts

Die API-Aufrufe helfen beim Erstellen eines Zeitplanberichts.

Anforderung

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

Antwort

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

Abrufen des Berichtsstatus und Downloaddetails

Nachdem wir einen Bericht erstellt haben, erstellen wir einen API-Aufruf, um den Berichtsstatus und den herunterladbaren Link abzurufen, damit der Bericht auf den Client heruntergeladen werden kann. Um diesen Aufruf auszuführen, fragen wir mit der gleichen reportId ab, die im vorherigen Schritt generiert wurde.

Anforderung

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

Antwort

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

Erstellen eines Zeitplanberichts mit Webhook

Der Webhook fungiert als Endpunkt, der aufgerufen wird, sobald der Bericht bereit ist. Der CallbackURL-Parameter muss bereitgestellt werden.

Partner müssen ihren Webhook-Handler schreiben. Im vorherigen Beispiel wird der Berichthttps://msnotify.com nach der Vorbereitung des Berichts als Benachrichtigung aufgerufen. Im Aufruf können Partner die Liste der geplanten Berichte und deren Status abrufen und dann die oben genannten APIs verwenden, um die Datei herunterzuladen.

Anfordern

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-Dokumentation

Weitere Informationen finden Sie in der OpenAPI-Spezifikation. Fügen Sie den Inhalt der Spezifikation im öffentlichen Swagger-Editor ein, um die APIs anzuzeigen und Clients in bevorzugten Sprachen (C#, Python usw.) zu generieren, um die APIs zu nutzen.

Wichtig

Diese API verfügt über Standardabfrageparameter, die für executionStatus=Completed und getLatestExecution=true festgelegt sind. Daher gibt das Aufrufen der API vor der ersten erfolgreichen Ausführung des Berichts einen Fehler von 404 zurück. Ausstehende Ausführungen können durch Festlegen von executionStatus=Pending abgerufen werden.