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

文章
04/19/2024

如需存取商業市集分析數據的 API 清單，請參閱存取商業市集分析數據的 API。進行第一次 API 呼叫之前，請確定您符合以程式設計方式存取商業市集分析數據的必要條件。

令牌產生

呼叫任何方法之前，您必須先取得 Microsoft Entra 存取令牌。您必須將 Microsoft Entra 存取令牌傳遞至 API 中每個方法的 Authorization 標頭。取得存取令牌之後，您有 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 Token 之後，請遵循下列步驟來建立您的第一個程式設計存取報告。

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

報表名稱	API 中的數據集名稱
訂單	ISVOrder
使用方式	ISVUsage
客戶	ISVCustomer
Marketplace 深入解析	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：建立自訂查詢

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

Share via

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

令牌產生

以程序設計方式呼叫 API

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

步驟 2：建立自訂查詢

步驟 3：執行測試查詢 API

步驟 4：建立報告

步驟 5：執行報表執行 API

下一步

意見反映

意見反映

更多資源