Выполнение первого вызова API

Статья
06/13/2024

На этой странице объясняется, как сделать первый вызов API к приложениям и играм.

Шаблон вызова API

На следующей схеме показан шаблон вызова API, используемый для создания нового шаблона отчета, планирования пользовательского отчета и получения данных о сбоях.

Этот список содержит дополнительные сведения о схеме шаблона вызова API.

Клиентское приложение может определить настраиваемую схему или шаблон отчета, вызвав API создания запросов отчета. Кроме того, можно использовать шаблон (QueryId) отчета из списка системных запросов.
При успешном выполнении API создания шаблона отчета возвращает QueryIdзначение .
Затем клиентское приложение вызывает API создания отчетов, используя QueryID, а также дату начала отчета, интервал повтора, периодичность и URI обратного вызова (необязательно).
При успешном выполнении API создания отчетов возвращает ReportID.
Клиентское приложение вызывает API состояния, чтобы получить состояние отчета.
Затем клиентское приложение использует API получения сведений о выполнении отчетов для запроса состояния отчета с указанием Report ID и диапазоном дат.
При успешном выполнении возвращается ссылка на скачивание отчета, после чего приложение может инициировать скачивание данных.

Указание языка запросов отчета

Хотя мы предоставляем системные запросы, которые можно использовать для создания отчетов, вы также можете создавать собственные запросы на основе ваших бизнес-потребностей. Дополнительные сведения о пользовательских запросах см. в разделе Спецификация пользовательских запросов.

Проверка подлинности

Во-первых, перейдите к учетной записи Центра партнеров, выполнив предварительные требования для использования API аналитики Microsoft Store. Затем получите маркер доступа Microsoft Entra. Следуйте только шагу 1 и шагу 2. Шаг 3 является избыточным для этого потока.

Программный вызов API

После получения маркера Microsoft Entra, как описано в предыдущем разделе, выполните следующие действия, чтобы создать первый отчет программного доступа.

Данные можно скачать из следующих наборов данных (datasetName):

Имя отчета	Имя набора данных в API
Приобретение	Приобретения
Приобретение надстройки	AddOnAcquisitions
Каналы и преобразование	ChannelAndConversions
Использование gamepass	GamePass
Производительность gamepass	GamePassPurchase
Работоспособности: сбои и события	HealthFailureHits
Установки	Установки
Рейтинги	Рейтинги
Оценки	Оценки
Устойчивое развитие	Устойчивое развитие
Ежедневное использование	UsageDaily
Использование—ежемесячно	ИспользованиеMonthly
Список желаний	Список желаний
Взаимодействие с событиями	Xevents_Metrics
Повышение цен — гибкая	Xprice_Flexible_Offer
Повышение цен — целевые	Xprice_Targeted_Offer

В следующих разделах показаны примеры программного доступа к содержимому из набора данных "Приобретение".

Вызов REST с помощью API получения наборов данных

Ответ API предоставляет имя набора данных, откуда можно скачать отчет. Для конкретного набора данных ответ API также предоставляет список выбираемых столбцов, которые можно использовать для настраиваемого шаблона отчета.

API создания запросов отчетов

Этот API позволяет создавать пользовательские запросы, определяющие набор данных, из которого необходимо экспортировать столбцы и метрики. Он позволяет гибко создавать шаблоны отчетов с учетом потребностей организации.

Вы также можете использовать системные запросы, которые предоставляем мы. Если пользовательские шаблоны отчетов не требуются, вы можете вызвать API создания отчетов непосредственно с помощью идентификаторов запросов системных запросов, которые мы предоставляем.

Пример запроса

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

Пример ответа

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

Создание настраиваемого запроса

На этом шаге мы создадим настраиваемый запрос для нужного отчета. Этот запрос создается каждый раз, когда требуется отчет (execute now или schedule).

Пример запроса

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

Пример ответа

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

При успешном выполнении запроса создается идентификатор запроса, который необходимо использовать для создания отчета.

Получение запроса

Выводит список всех доступных запросов. Существующий запрос, созданный на приведенном выше шаге, должен отражаться здесь.

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

Пример ответа

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

Создание мгновенного асинхронного отчета

На этом шаге мы используем ранее созданный queryId для создания отчета. Следующий запрос используется для выполнения отчета. Создание отчета является асинхронным и требует отдельного вызова API для получения отчета.

Пример запроса

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

Пример ответа

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

Идентификатор отчета: "выполнение" создается. Этот идентификатор необходимо использовать для планирования скачивания отчета.

Примечание.

Дополнительные сведения о поле см. в разделе "Общие сведения о totalRecurrenceCount поле TotalRecurrenceCount" для запланированных отчетов.

Скачивание мгновенного отчета

Пример запроса

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

Пример ответа

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

Для скачивания отчета можно вызвать reportAccessSecureLink .

Создание отчета о расписании

Вызовы API помогают создать отчет о расписании.

Запросить

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 
}

Получение состояния отчета и сведения о скачивании

Теперь, когда мы создали отчет, мы создадим вызов API, чтобы получить состояние отчета и ее скачиваемую ссылку, чтобы отчет можно было скачать на клиент. Чтобы сделать этот вызов, мы запрашиваем тот же идентификатор отчета , созданный на предыдущем шаге.

Запросить

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 
}

Создание отчета расписания с помощью веб-перехватчика

Веб-перехватчик работает как конечная точка, которая вызывается сразу после готовности отчета. Необходимо указать параметр callbackURL .

Партнерам необходимо написать обработчик веб-перехватчика. В предыдущем примере после готовности отчета вызывается какhttps://msnotify.com уведомление. В вызове партнеры могут получить список запланированных отчетов и их состояния, а затем использовать указанные выше API для скачивания файла.

Запросить

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

См. спецификацию OpenAPI. Вставьте содержимое спецификации в редакторе Public Swagger, чтобы просмотреть API и создать клиенты на предпочитаемых языках (C#, python и т. д.) для использования API.

Внимание

В этом API параметры executionStatus=Completed и getLatestExecution=true имеют значения по умолчанию. Поэтому вызов API до первого успешного выполнения отчета вернет ошибку 404. Для получения ожидающих выполнений можно использовать параметр executionStatus=Pending.

Поделиться через

Выполнение первого вызова API

Шаблон вызова API

Указание языка запросов отчета

Проверка подлинности

Программный вызов API

Вызов REST с помощью API получения наборов данных

API создания запросов отчетов

Пример запроса

Пример ответа

Создание настраиваемого запроса

Пример запроса

Пример ответа

Получение запроса

Пример ответа

Создание мгновенного асинхронного отчета

Пример запроса

Пример ответа

Скачивание мгновенного отчета

Пример запроса

Пример ответа

Создание отчета о расписании

Запросить

Response

Получение состояния отчета и сведения о скачивании

Запросить

Response

Создание отчета расписания с помощью веб-перехватчика

Запросить

Документация по API

Обратная связь

Дополнительные ресурсы