Wykonywanie pierwszego wywołania interfejsu API

Artykuł
06/13/2024

Na tej stronie wyjaśniono, jak wykonać pierwsze wywołanie interfejsu API do aplikacji i gier.

Wzorzec wywołań interfejsu API

Na poniższym diagramie przedstawiono wzorzec wywołania interfejsu API używany do tworzenia nowego szablonu raportu, planowania raportu niestandardowego i pobierania danych o błędach.

Ta lista zawiera więcej szczegółów na temat diagramu wzorca wywołania interfejsu API.

Aplikacja kliencka może zdefiniować niestandardowy schemat/szablon raportu, wywołując interfejs API tworzenia zapytania raportu. Alternatywnie możesz użyć szablonu (QueryId) raportu z listy zapytań systemowych.
Po pomyślnych działaniach interfejs API tworzenia szablonu raportu zwraca wartość QueryId.
Następnie aplikacja kliencka wywołuje interfejs API tworzenia raportu przy użyciu QueryID elementu wraz z datą rozpoczęcia raportu, interwałem powtórzenia, cyklem i opcjonalnym identyfikatorem URI wywołania zwrotnego.
Po pomyślnych działaniach interfejs API tworzenia raportu zwraca wartość ReportID.
Aplikacja kliencka wywołuje interfejs API stanu, aby uzyskać stan raportu.
Następnie aplikacja kliencka używa interfejsu API Pobierz wykonania raportów do wykonywania zapytań o stan raportu z zakresem Report ID dat i .
Po pomyślnym zakończeniu zostanie zwrócony link pobierania raportu, a aplikacja może zainicjować pobieranie danych.

Określanie języka zapytań raportu

Mimo że udostępniamy zapytania systemowe, których można użyć do tworzenia raportów, możesz również tworzyć własne zapytania na podstawie potrzeb biznesowych. Aby dowiedzieć się więcej na temat zapytań niestandardowych, zobacz Custom query specification (Specyfikacja zapytania niestandardowego).

Uwierzytelnianie

Najpierw dołącz do konta Centrum partnerskiego, wypełniając wymagania wstępne dotyczące korzystania z interfejsu API analizy sklepu Microsoft Store. Następnie uzyskaj token dostępu firmy Microsoft Entra. Postępuj zgodnie tylko z krokami 1 i Krok 2. Krok 3 jest nadmiarowy dla tego przepływu.

Programowe wywołanie interfejsu API

Po uzyskaniu tokenu Entra firmy Microsoft zgodnie z opisem w poprzedniej sekcji wykonaj następujące kroki, aby utworzyć pierwszy raport dostępu programowego.

Dane można pobrać z następujących zestawów danych (datasetName):

Nazwa raportu	Nazwa zestawu danych w interfejsie API
Nabycie	Przejęcia
Pozyskiwanie dodatków	AddOnAcquisitions
Kanały i konwersja	KanałyAndConversions
Użycie usługi Gamepass	GamePass
Wydajność usługi Gamepass	GamePassPurchase
Kondycja: awarie i zdarzenia	HealthFailureHits
Instaluje	Instaluje
Oceny	Oceny
Recenzje	Recenzje
Zrównoważony rozwój	Zrównoważony rozwój
Dzienne użycie	UżycieDaily
Użycie miesięczne	Miesiąc użycia
Lista życzeń	Lista życzeń
Zakontraktowanie zdarzeń	Xevents_Metrics
Promocje cenowe — elastyczne	Xprice_Flexible_Offer
Promocje cenowe — ukierunkowane	Xprice_Targeted_Offer

W poniższych sekcjach przedstawiono przykłady programowego uzyskiwania dostępu do zawartości z zestawu danych Pozyskiwanie.

Tworzenie wywołania REST przy użyciu interfejsu API Pobierania zestawów danych

Odpowiedź interfejsu API zawiera nazwę zestawu danych, z którego można pobrać raport. W przypadku określonego zestawu danych odpowiedź interfejsu API zawiera również listę wybranych kolumn, których można użyć dla niestandardowego szablonu raportu.

Tworzenie interfejsu API zapytania raportu

Ten interfejs API ułatwia tworzenie zapytań niestandardowych definiujących zestaw danych, z których należy eksportować kolumny i metryki. Interfejs API zapewnia elastyczność tworzenia nowego szablonu raportowania na podstawie potrzeb biznesowych.

Możesz również użyć zapytań systemowych, które udostępniamy. Gdy niestandardowe szablony raportów nie są potrzebne, możesz wywołać interfejs API tworzenia raportu bezpośrednio przy użyciu identyfikatorów QueryId zapytań systemowych, które udostępniamy.

Przykład żądania

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

Przykład odpowiedzi

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

Tworzenie zapytania niestandardowego

W tym kroku utworzymy zapytanie niestandardowe dla żądanego raportu. To utworzone zapytanie jest używane za każdym razem, gdy jest wymagany raport (execute now lub schedule).

Przykład żądania

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

Przykład odpowiedzi

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

Po pomyślnym wykonaniu zapytania jest generowany identyfikator queryId, który należy użyć do wygenerowania raportu.

Pobieranie zapytania

Wyświetla listę wszystkich dostępnych zapytań. Istniejące zapytanie utworzone w powyższym kroku powinno się odzwierciedlić tutaj.

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

Przykład odpowiedzi

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

Tworzenie natychmiastowego raportu asynchronicznego

W tym kroku użyjemy wcześniej wygenerowanego identyfikatora QueryId do utworzenia raportu. Poniższe zapytanie jest używane do wykonania teraz raportu. Generowanie raportu jest asynchroniczne i wymaga oddzielnego wywołania interfejsu API w celu pobrania raportu.

Przykład żądania

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

Przykład odpowiedzi

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

Identyfikator raportu: "wykonanie" jest generowany. Ten identyfikator należy użyć do zaplanowanego pobrania raportu.

Uwaga

Aby uzyskać szczegółowe informacje na temat totalRecurrenceCount pola, zobacz Opis pola totalRecurrenceCount dla zaplanowanych raportów.

Pobieranie raportu błyskawicznego

Przykład żądania

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

Przykład odpowiedzi

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

RaportAccessSecureLink można wywołać, aby pobrać raport.

Tworzenie raportu harmonogramu

Wywołania interfejsu API pomagają utworzyć raport harmonogramu.

Zażądaj

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 
}

Pobieranie stanu raportu i pobieranie szczegółów

Po utworzeniu raportu utworzymy wywołanie interfejsu API, aby uzyskać stan raportu i jego link do pobrania, aby można było pobrać raport do klienta. Aby wykonać to wywołanie, wysyłamy zapytania za pomocą tego samego identyfikatora reportId wygenerowanego w poprzednim kroku.

Zażądaj

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 
}

Tworzenie raportu harmonogramu za pomocą elementu webhook

Element webhook działa jako punkt końcowy wywoływany natychmiast po zakończeniu raportu. Należy podać parametr callbackURL .

Partnerzy muszą napisać procedurę obsługi elementów webhook. W poprzednim przykładzie, gdy raport będzie gotowy, element "https://msnotify.com" jest wywoływany jako powiadomienie. Podczas wywołania partnerzy mogą pobrać listę zaplanowanych raportów i ich stanów, a następnie pobrać plik przy użyciu powyższych interfejsów API.

Żądanie

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

Dokumentacja interfejsu API

Zapoznaj się ze specyfikacją interfejsu OpenAPI. Wklej zawartość specyfikacji w publicznym edytorze swagger, aby wyświetlić interfejsy API i wygenerować klientów w preferowanych językach (C#, Python itp.), aby korzystać z interfejsów API.

Ważne

Ten interfejs API ma domyślne parametry zapytania ustawione dla executionStatus=Completed parametrów i getLatestExecution=true. W związku z tym wywołanie interfejsu API przed pierwszym pomyślnym wykonaniem raportu zwróci błąd 404. Oczekujące wykonania można uzyskać, ustawiając wartość executionStatus=Pending.

Udostępnij za pośrednictwem

Wykonywanie pierwszego wywołania interfejsu API

Wzorzec wywołań interfejsu API

Określanie języka zapytań raportu

Uwierzytelnianie

Programowe wywołanie interfejsu API

Tworzenie wywołania REST przy użyciu interfejsu API Pobierania zestawów danych

Tworzenie interfejsu API zapytania raportu

Przykład żądania

Przykład odpowiedzi

Tworzenie zapytania niestandardowego

Przykład żądania

Przykład odpowiedzi

Pobieranie zapytania

Przykład odpowiedzi

Tworzenie natychmiastowego raportu asynchronicznego

Przykład żądania

Przykład odpowiedzi

Pobieranie raportu błyskawicznego

Przykład żądania

Przykład odpowiedzi

Tworzenie raportu harmonogramu

Zażądaj

Response

Pobieranie stanu raportu i pobieranie szczegółów

Zażądaj

Response

Tworzenie raportu harmonogramu za pomocą elementu webhook

Żądanie

Dokumentacja interfejsu API

Opinia

Dodatkowe zasoby