Создание первого вызова API для доступа к данным аналитики коммерческой платформы
Для получения списка API для доступа к данным аналитики коммерческого маркетплейса см. API для доступа к данным аналитики коммерческого маркетплейса. Перед первым вызовом API убедитесь, что вы выполнили необходимые условия для программного доступа к данным аналитики коммерческой платформы.
Создание токенов
Перед вызовом любого из методов необходимо сначала получить маркер доступа Microsoft Entra. Необходимо передать токен доступа Microsoft Entra в заголовок авторизации каждого метода в API. После получения маркера доступа у вас есть 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно обновить маркер и продолжить использовать его для дальнейших вызовов API.
Предупреждение
Resource='https://graph.microsoft.com' будет устарел после 30 августа 2024 года. Запланируйте миграцию в Resource="https://api.partnercenter.microsoft.com" соответствующим образом.
Ознакомьтесь с примером запроса ниже для генерации токена. Три значения, необходимые для создания маркера, — clientId, clientSecretи tenantId. Параметр resource должен иметь значение https://api.partnercenter.microsoft.com.
Пример запроса :
curl --location --request POST 'https://login.microsoftonline.com/{TenantId}/oauth2/token' \
--header 'return-client-request-id: true' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'resource=https://api.partnercenter.microsoft.com' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'grant_type=client_credentials'
пример ответа :
{
"token_type": "Bearer",
"expires_in": "3599",
"ext_expires_in": "3599",
"expires_on": "1612794445",
"not_before": "1612790545",
"resource": "https://api.partnercenter.microsoft.com",
"access_token": {Token}
}
Дополнительные сведения о получении токена Microsoft Entra для вашего приложения можно найти в разделе Межсервисные вызовы с использованием учетных данных клиента (общий секрет или сертификат).
Программный вызов API
После получения маркера Microsoft Entra, как описано в предыдущем разделе, выполните следующие действия, чтобы создать первый отчет программного доступа.
Данные можно скачать из следующих наборов данных (datasetName):
| Имя отчета | Имя набора данных в API |
|---|---|
| Заказ | ISVOrder |
| Употребление | ISVUsage |
| Клиент | ISVCustomer |
| Инсайты Marketplace | ISVMarketplaceInsights |
| Доход | ISVДоход |
| Хранение клиентов | ISVOfferRetention |
| Качество обслуживания | ISVQualityOfService |
| Лицензия | ISVLicense |
| Версия образа виртуальной машины | ISVVMImageVersion |
В следующих разделах показаны примеры программного доступа к OrderId из набора данных ISVOrder.
Шаг 1. Выполнение вызова REST с помощью API получения наборов данных
Ответ API предоставляет имя набора данных, из которого можно скачать отчет. Для конкретного набора данных ответ API также предоставляет список настраиваемых столбцов, которые можно использовать для пользовательского шаблона отчета.
пример запроса:
curl
--location
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledDataset ' \
--header 'Authorization: Bearer <AzureADToken>'
пример ответа :
{
"value": [
{
"datasetName": "ISVOrder",
"selectableColumns": [
"MarketplaceSubscriptionId",
"MonthStartDate",
"OfferType",
"AzureLicenseType",
"MarketplaceLicenseType",
"SKU",
"CustomerCountry",
"IsPreviewSKU",
"AssetId",
"Quantity",
"CloudInstanceName",
"IsNewCustomer",
"OrderStatus",
"OrderCancelDate",
"CustomerCompanyName",
"OrderPurchaseDate",
"OfferName",
"IsPrivateOffer",
"TermStartDate",
"TermEndDate",
"PurchaseRecordId",
"PurchaseRecordLineItemId",
"BilledRevenue",
"Currency",
"HasTrial",
"IsTrial",
"TrialEndDate",
"OrderAction",
"QuantityChanged",
"EventTimestamp",
"CustomerId",
"BillingAccountId",
"PlanId",
"BillingTerm",
"BillingPlan",
"ReferenceId",
"AutoRenew",
"OrderVersion",
"ListPriceUSD",
"DiscountPriceUSD",
"IsPrivatePlan",
"OfferId",
"PrivateOfferId",
"PrivateOfferName",
"BillingId",
"Version",
"CustomerAdjustmentUSD",
"MultiParty",
"PartnerInfo"
],
"availableMetrics": [],
"availableDateRanges": [
"LAST_MONTH",
"LAST_3_MONTHS",
"LAST_6_MONTHS",
"LAST_1_YEAR",
"LIFETIME"
],
"minimumRecurrenceInterval": 1
},
],
"totalCount": 1,
"message": "Dataset fetched successfully",
"statusCode": 200
}
Шаг 2. Создание настраиваемого запроса
На этом шаге мы будем использовать идентификатор заказа из отчета "Заказы" для создания пользовательского запроса для нужного отчета. Значение по умолчанию timespan, если не указано в запросе, составляет шесть месяцев.
пример запроса :
curl
--location
--request POST ' https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries' \
--header ' Authorization: Bearer <AzureAD_Token>' \
--header 'Content-Type: application/json' \
--data-raw
'{
"Query": "SELECT OrderId from ISVOrder",
"Name": "ISVOrderQuery1",
"Description": "Get a list of all Order IDs"
}'
пример ответа :
{
"value": [
{
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"name": "ISVOrderQuery1",
"description": "Get a list of all Order IDs",
"query": "SELECT OrderId from ISVOrder",
"type": "userDefined",
"user": "142344300",
"createdTime": "2024-01-06T05:38:34",
"modifiedTime": null
}
],
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200
}
При успешном выполнении запроса создается queryId, который необходимо использовать для создания отчета.
Шаг 3. Выполнение API тестового запроса
На этом шаге мы будем использовать API тестового запроса, чтобы получить первые 100 строк для созданного запроса.
пример запроса:
curl
--location
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries/testQueryResult?exportQuery=SELECT%20OrderId%20from%20ISVOrder' \
--header ' Authorization: Bearer <AzureADToken>'
пример ответа :
{
"value": [
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2ba8"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bb8"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bc8"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bd8"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2be8"
},
.
.
.
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf0"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf1"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf2"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf3"
},
{
"OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf4"
}
],
"totalCount": 100,
"message": null,
"statusCode": 200
}
Шаг 4. Создание отчета
На этом шаге мы будем использовать ранее созданный QueryId для создания отчета.
пример запроса :
curl
--location
--request POST 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport' \
--header ' Authorization: Bearer <AzureADToken>' \
--header 'Content-Type: application/json' \
--data-raw
'{
"ReportName": "ISVReport1",
"Description": "Report for getting list of Order Ids",
"QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"StartTime": "2024-01-06T19:00:00Z",
"RecurrenceInterval": 48,
"RecurrenceCount": 20,
"Format": "csv"
}'
пример ответа :
{
"value": [
{
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"reportName": "ISVReport1",
"description": "Report for getting list of Order Ids",
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"query": "SELECT OrderId from ISVOrder",
"user": "142344300",
"createdTime": "2024-01-06T05:46:00Z",
"modifiedTime": null,
"startTime": "2024-01-06T19:00:00Z",
"reportStatus": "Active",
"recurrenceInterval": 48,
"recurrenceCount": 20,
"callbackUrl": null,
"format": "csv"
}
],
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200
}
При успешном выполнении создается reportId, который необходимо использовать для планирования загрузки отчета.
Шаг 5. Выполнение API выполнения отчетов
Чтобы получить безопасное расположение отчета (URL-адрес), теперь мы будем выполнять API выполнения отчетов.
пример запроса :
Curl
--location
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/72fa95ab-35f5-4d44-a1ee-503abbc88003' \
--header ' Authorization: Bearer <AzureADToken>' \
пример ответа :
{
"value": [
{
"executionId": "1f18b53b-df30-4d98-85ee-e6c7e687aeed",
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"recurrenceInterval": 48,
"recurrenceCount": 20,
"callbackUrl": null,
"format": "csv",
"executionStatus": "Pending",
"reportAccessSecureLink": null,
"reportExpiryTime": null,
"reportGeneratedTime": null
}
],
"totalCount": 1,
"message": null,
"statusCode": 200
}
Вы можете попробовать API через URL-адрес Swagger API .