发出第一次 API 调用以访问商业市场分析数据

有关用于访问商业市场分析数据的 API 列表,请参阅用于访问商业市场分析数据的 API。 在进行第一次 API 调用之前,请确保满足 以编程方式访问商业市场分析数据的先决条件

令牌生成

在调用任何方法之前,必须先获取 Microsoft Entra 访问令牌。 需要将 Microsoft Entra 访问令牌传递给 API 中每个方法的授权标头。 获取访问令牌后,请在 60 分钟内使用它,否则它会过期。 该令牌过期后,可以刷新该令牌,并继续使用它来进一步调用 API。

警告

Resource='https://graph.microsoft.com' 将在 2024 年 8 月 30 日之后弃用。 请相应地计划迁移到 Resource='https://api.partnercenter.microsoft.com' 。

请参阅下面用于生成令牌的示例请求。 生成令牌所需的三个值为 clientIdclientSecrettenantIdresource 参数应设置为 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
VM 映像版本 ISVVMImageVersion

以下部分演示了如何以编程方式从 ISVOrder 数据集访问 OrderId 的示例。

步骤 1:使用“获取数据集”API 发出 REST 调用

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:创建自定义查询

在此步骤,我们将使用“订单”报表中的“订单 ID”针对所需的报表创建自定义查询。 如果未在查询中指定,则默认的 timespan 为 6 个月。

请求示例:

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
}

可以通过 Swagger API URL 试用 API。