Выполните первый вызов API для доступа к данным аналитики коммерческой платформы Marketplace

  • Статья

Список API-интерфейсов для доступа к данным аналитики коммерческой платформы Marketplace см. в этой статье. Перед первым вызовом 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;
Коммерческая аналитика ISVMarketplaceInsights;
Выручка ISVRevenue
Хранение клиентов ISVOfferRetention
Качество обслуживания ISVQualityOfService
Лицензия ISVLicense
Версия образа виртуальной машины ISVMImageVersion

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

Шаг 1. Вызов REST с помощью API Get Datasets

Ответ 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 Report Executions

Чтобы получить безопасное расположение отчета (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-адреса API Swagger.

Связанный контент