進行您的第一個 API 呼叫以存取商業市集分析數據

發行項
03/09/2025

如需存取商業市集分析數據的 API 清單，請參閱 API 來存取商業市集分析資料。在您進行第一次 API 調用之前，請確定您已符合必要條件，透過程式化方式存取商業市場分析數據。

令牌產生

呼叫任何方法之前，您必須先取得Microsoft Entra 存取令牌。您必須將Microsoft Entra 存取令牌傳遞至 API 中每個方法的 Authorization 標頭。取得存取令牌之後，您有 60 分鐘的時間才能使用令牌。令牌到期之後，您可以更新令牌，並繼續使用它來進一步呼叫 API。

警告

Resource='https://graph.microsoft.com' 將在 2024 年 8 月 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 Token 之後，請遵循下列步驟來建立您的第一個程式設計存取報告。

您可以從下列資料集下載資料（datasetName）：

報表名稱	API 中的數據集名稱
訂單	ISVOrder
用法	ISVUsage
客戶	ISVCustomer
Marketplace 市場洞察	ISVMarketplaceInsights
收入	ISV 收入
客戶保留期	ISV Offer 保留
服務品質	ISVQualityOfService
許可證	ISV 授權
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：建立自訂查詢

在此步驟中，我們將使用訂單報表中的訂單標識碼，為我們想要的報表建立自定義查詢。如果在查詢中未指定，則預設 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
}

您可以透過 Swagger API URL來試用 API。

程式設計存取架構

共用方式為

進行您的第一個 API 呼叫以存取商業市集分析數據

令牌產生

以程序設計方式呼叫 API

步驟 1：使用取得數據集 API 進行 REST 呼叫

步驟 2：建立自訂查詢

步驟 3：執行測試查詢 API

步驟 4：建立報告

步驟 5：執行報表執行 API

意見反應

其他資源

共用方式為

進行您的第一個 API 呼叫以存取商業市集分析數據

令牌產生

以程序設計方式呼叫 API

步驟 1：使用取得數據集 API 進行 REST 呼叫

步驟 2：建立自訂查詢

步驟 3：執行測試查詢 API

步驟 4：建立報告

步驟 5：執行報表執行 API

相關內容

意見反應

其他資源