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

项目
06/14/2024

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

令牌生成

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

警告

Resource='https://graph.microsoft.com' 将在 2024 年 6 月 30 日之后弃用。请相应地计划迁移到 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 中的数据集名称
下单(O)	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
编程式访问范例

通过

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

令牌生成

编程式 API 调用

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

步骤 2：创建自定义查询

步骤 3：执行测试查询 API

步骤 4：创建报表

步骤 5：执行“报表执行”API

后续步骤

反馈

反馈

其他资源