Sdílet prostřednictvím

První volání rozhraní API

  • Článek

Tato stránka vysvětluje, jak provést první volání rozhraní API do aplikací a her.

Model volání rozhraní API

Následující diagram znázorňuje model volání rozhraní API použitý k vytvoření nové šablony sestavy, naplánování vlastní sestavy a načtení dat o selhání.

Diagram toku vysoké úrovně modelu volání rozhraní API

Tento seznam obsahuje další podrobnosti o diagramu vzoru volání rozhraní API.

  1. Klientská aplikace může definovat vlastní schéma sestavy nebo šablonu voláním rozhraní API pro vytvoření dotazu sestavy. Případně můžete použít šablonu sestavy (QueryId) ze seznamu systémových dotazů.
  2. Při úspěchu vrátí rozhraní API pro vytvoření šablony sestavy QueryIdhodnotu .
  3. Klientská aplikace pak volá rozhraní API pro vytvoření sestavy pomocí QueryID počátečního data sestavy, intervalu opakování, opakování a volitelného identifikátoru URI zpětného volání.
  4. Při úspěchu vrátí rozhraní API pro vytvoření sestavy ReportIDhodnotu .
  5. Klientská aplikace volá rozhraní API stavu, aby získala stav sestavy.
  6. Klientská aplikace pak pomocí rozhraní API Get Report Executions dotazuje stav sestavy s rozsahem dat a rozsahem Report ID dat.
  7. Při úspěchu se vrátí odkaz ke stažení sestavy a aplikace může zahájit stahování dat.

Zadání dotazovacího jazyka sestavy

I když poskytujeme systémové dotazy , které můžete použít k vytváření sestav, můžete také vytvářet vlastní dotazy na základě vašich obchodních potřeb. Další informace o vlastníchdotazch

Ověřování

Nejprve se připojte k účtu Partnerského centra dokončením požadavků pro použití rozhraní API pro analýzu Microsoft Storu. Dále získejte přístupový token Microsoft Entra. Postupujte podle kroku 1 a kroku 2. Krok 3 je pro tento tok redundantní.

Programové volání rozhraní API

Po získání tokenu Microsoft Entra, jak je popsáno v předchozí části, postupujte podle těchto kroků a vytvořte první programovou sestavu přístupu.

Data je možné stáhnout z následujících datových sad (datasetName):

Název sestavy Název datové sady v rozhraní API
Pořizovací cena Akvizice
Získání doplňku Doplňky AddOnAcquisitions
Kanály a převod ChannelsAndConversions
Využití gamepassu GamePass
Výkon gamepassu GamePassPurchase
Stav: Chybové ukončení a události HealthFailureHits
Instaluje Instaluje
Hodnocení Hodnocení
Kontroly Kontroly
Udržitelnost Udržitelnost
Využití denně UsageDaily
Využití měsíčně UsageMonthly
Seznam přání Seznam přání
Zapojení událostí Xevents_Metrics
Propagační akce s cenami – flexibilní Xprice_Flexible_Offer
Propagační akce s cenami – cílené Xprice_Targeted_Offer

Následující části ukazují příklady přístupu k obsahu z datové sady získání prostřednictvím kódu programu.

Volání REST pomocí rozhraní GET Datasets API

Odpověď rozhraní API poskytuje název datové sady, ze které si můžete sestavu stáhnout. Pro konkrétní datovou sadu poskytuje odpověď rozhraní API také seznam vybraných sloupců, které je možné použít pro vlastní šablonu sestavy.

Vytvoření rozhraní API pro dotazy na sestavy

Toto rozhraní API pomáhá vytvářet vlastní dotazy, které definují datovou sadu, ze které sloupce a metriky je potřeba exportovat. Rozhraní API poskytuje flexibilitu při vytváření nové šablony vytváření sestav na základě vašich obchodních potřeb.

Můžete také použít systémové dotazy , které poskytujeme. Pokud vlastní šablony sestav nejsou potřeba, můžete rozhraní API pro vytvoření sestavy volat přímo pomocí id dotazů systému, které poskytujeme.

Příklad požadavku

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

Příklad odpovědi

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

Vytvoření vlastního dotazu

V tomto kroku vytvoříme vlastní dotaz pro sestavu, kterou chceme. Tento dotaz se používá pokaždé, když je požadována sestava (execute now nebo schedule).

Příklad požadavku

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

Příklad odpovědi

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

Při úspěšném spuštění dotazu se vygeneruje ID dotazu, které je potřeba použít k vygenerování sestavy.

Získání dotazu

Zobrazí seznam všech dostupných dotazů. Zde by se měl odrážet existující dotaz vytvořený v předchozím kroku.

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

Příklad odpovědi

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

Vytvoření okamžité asynchronní sestavy

V tomto kroku použijeme k vytvoření sestavy dříve vygenerované ID dotazu. Následující dotaz slouží k provedení sestavy. Generování sestavy je asynchronní a vyžaduje samostatné volání rozhraní API pro načtení sestavy.

Příklad požadavku

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

Příklad odpovědi

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

Id sestavy: Execution se vygeneruje. Toto ID je potřeba použít k naplánování stahování sestavy.

Poznámka:

Podrobnosti o totalRecurrenceCount tomto poli najdete v tématu Vysvětlení pole totalRecurrenceCount pro plánované sestavy.

Stažení okamžité sestavy

Příklad požadavku

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

Příklad odpovědi

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

Pro stažení sestavy je možné vyvolat reportAccessSecureLink .

Vytvoření sestavy plánu

Volání rozhraní API pomáhají vytvořit sestavu plánu.

Požádat

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

Response

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

Získání stavu sestavy a podrobností o stažení

Teď, když jsme vytvořili sestavu, zavoláme rozhraní API, abychom získali stav sestavy a odkaz ke stažení, aby bylo možné sestavu stáhnout do klienta. Abychom toto volání provedli, dotazujeme se na stejné ID sestavy vygenerované v předchozím kroku.

Požádat

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

Response

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

Vytvoření sestavy plánu pomocí webhooku

Webhook funguje jako koncový bod, který se vyvolá hned, jak je sestava připravená. Je potřeba poskytnout parametr callbackURL .

Partneři musí napsat obslužnou rutinu webhooku. V předchozím příkladu se jakmile sestava připraví,https://msnotify.com vyvolá se jako oznámení "". Při vyvolání můžou partneři získat seznam naplánovaných sestav a jejich stavů a pak pomocí výše uvedených rozhraní API stáhnout soubor.

Žádost

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

Dokumentace API

Projděte si specifikaci OpenAPI. Vložte obsah specifikace ve veřejném editoru Swagger, abyste zobrazili rozhraní API a vygenerovali klienty v upřednostňovaných jazycích (C#, python atd.), aby bylo možné tato rozhraní API využívat.

Důležité

Toto rozhraní API má nastavené výchozí parametry dotazu pro executionStatus=Completed a getLatestExecution=true. Proto volání rozhraní API před prvním úspěšným spuštěním sestavy vrátí chybu 404. Čekající spuštění lze získat nastavením executionStatus=Pending.