商業市集的程式設計存取架構

發行項
03/08/2025

此圖顯示用來建立新報表範本、排程自定義報表及擷取失敗數據的 API 呼叫模式。

圖 1：API 呼叫模式的高階流程

此清單提供圖 1 的詳細資料。

用戶端應用程式可以呼叫建立報表查詢 API來定義自定義報表架構/範本。或者，您可以從系統查詢的清單中使用報表範本（QueryId）。
成功時，建立報表範本 API 會傳回 QueryId。
用戶端應用程式接著會使用 QueryID，配合報表開始日期、重複間隔、循環週期，以及選用的回呼 URI，呼叫建立報表 API。
成功時，建立報表 API 會傳回 ReportID。
用戶端應用程式會在報表資料準備好供下載時，即刻透過回撥 URI 接收通知。
用戶端應用程式接著會使用取得報表執行 API，以 Report ID 和日期範圍查詢報表的狀態。
成功時，會傳回報表下載連結，而且應用程式可以起始數據的下載。

報表查詢語言規格

雖然我們提供系統查詢您可用來建立報表，但您也可以根據業務需求建立自己的查詢。若要深入瞭解自訂查詢，請參閱自訂查詢規格。

建立報表查詢 API

此 API 有助於建立自訂查詢，以定義需要匯出數據行和計量的數據集。 API 提供根據業務需求建立新報告範本的彈性。

您也可以使用我們提供的系統查詢。當不需要自定義報表範本時，您可以使用我們提供的系統查詢，直接呼叫建立報表 API。

下列範例示範如何建立自定義查詢，從上個月的 ISVUsage 數據集，取得付費 SKU 的標準化使用量和預估財務費用。

要求語法

方法	要求 URI
貼文	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

要求標頭

頁眉	類型	描述
授權	字串	必填。 Microsoft Entra 存取令牌。格式為 `Bearer <token>`。
Content-Type	`string`	`application/JSON`

Path 參數

沒有

查詢參數

沒有

請求負載範例

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

詞彙

下表提供請求負載中元素的關鍵定義。

參數	必填	描述	允許的值
`Name`	是的	查詢的易記名稱	字串
`Description`	不	所建立查詢的描述	字串
`Query`	是的	根據商務需求查詢字串	字串

注意

如需自定義查詢範例，請參閱範例查詢。

範例回應

響應承載的結構如下：

回應碼：200、400、401、403、500

回應負載範例：

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

詞彙

下表提供回應中元素的主要定義。

參數	描述
`QueryId`	已建立查詢的通用唯一識別碼（UUID）
`Name`	在建立查詢時請求數據負載中提供的名稱
`Description`	在建立查詢時，在要求承載中提供的描述
`Query`	建立查詢期間在要求承載中提供的自定義報表查詢
`Type`	針對手動建立的查詢，設定為 `userDefined`
`User`	用來建立查詢的使用者標識碼
`CreatedTime`	建立查詢的 UTC 時間。格式：yyyy-MM-ddTHH：mm：ssZ
`TotalCount`	Value 陣列中的記錄數目
`StatusCode`	結果碼可能的值為 200、400、401、403、500
`message`	執行 API 的狀態消息

建立報表 API

成功建立自定義報表範本，並在建立報表查詢回應中接收 QueryID 時，可以呼叫此 API 來排程定期執行的查詢。您可以設定要傳遞報表的頻率和排程。針對我們提供的系統查詢，也可以使用 QueryId呼叫建立報表 API。

要求語法

方法	要求 URI
發佈	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

請求標頭

頁眉	類型	描述
授權	字串	必填。 Microsoft Entra 存取令牌。格式為 `Bearer <token>`。
內容類型	字串	`application/JSON`

Path 參數

沒有

查詢參數

沒有

要求承載範例

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

詞彙

下表提供要求有效負載中元素的關鍵定義。

參數	必填	描述	允許的值
`ReportName`	是的	給予報表的使用者友好的名稱	字串
`Description`	不	已建立報表的描述	字串
`QueryId`	是的	需要用於產生報表的查詢標識碼	字串
`StartTime`	是的	報表產生開始的 UTC 時間戳。格式應該是 yyyy-MM-ddTHH：mm：ssZ	字串
`ExecuteNow`	不	此參數應該用來建立只執行一次的報表。如果設定為 `true`，則會忽略 `StartTime`、`RecurrenceInterval`、`RecurrenceCount`和 `EndTime`	布爾
`QueryStartTime`	不	選擇性地指定擷取數據的查詢開始時間。這個參數僅適用於一次執行報表，其 `ExecuteNow` 設定為 `true`。格式應該是 yyyy-MM-ddTHH：mm：ssZ	時間戳為字串
`QueryEndTime`	不	選擇性地指定擷取數據的查詢結束時間。這個參數僅適用於一次執行報表，其 `ExecuteNow` 設定為 `true`。格式應該是 yyyy-MM-ddTHH：mm：ssZ	時間戳為字串
`RecurrenceInterval`	是的	產生報表的時數頻率。最小值為 1，最大值為 17520	整數
`RecurrenceCount`	是的	要產生的報表數目。限制條件取決於重複間隔	整數
`Format`	不	匯出檔案的檔案格式。預設格式為 CSV	CSV/TSV
`CallbackUrl`	不	可選擇性地設定為回呼目的地的可公開存取 URL	字串
`CallbackMethod`	不	取得/張貼方法，可使用回呼 URL 進行設定	GET/POST
`EndTime`	是的	報表產生即將結束的UTC時間戳。格式應該是 yyyy-MM-ddTHH：mm：ssZ	字串

注意

建立報表時，EndTime 或 RecurrenceInterval 和 RecurrenceCount 的組合是必要的。

範例回應

響應承載的結構如下：

回應碼：200、400、401、403、404、500

響應負載：

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

詞彙表

下表提供回應中元素的關鍵定義。

參數	描述
`ReportId`	您要建立報表的通用唯一識別碼（UUID）
`ReportName`	在報表建立請求的數據載荷中提供的名稱
`Description`	報表創建時在請求載體中提供的描述
`QueryId`	報表建立時在請求承載中提供的查詢 ID
`Query`	針對此報表將執行的查詢文字
`User`	用來建立報表的使用者標識碼
`CreatedTime`	UTC 以下列格式建立報表的時間：yyyy-MM-ddTHH：mm：ssZ
`ModifiedTime`	UTC 時間報表上次修改的格式為：yyyy-MM-ddTHH:mm:ssZ
`ExecuteNow`	報表建立期間在要求承載中提供的 ExecuteNow 參數
`queryStartTime`	在建立報告期間，請求負載中提供的查詢的開始時間。只有當 `ExecuteNow` 設為「True」時才適用
`queryEndTime`	建立報表時，在請求內容中提供的查詢結束時間。只有當 `ExecuteNow` 設為「True」時才適用
`StartTime`	建立報表時，請求內容中所提供的開始時間
`ReportStatus`	報表執行的狀態。可能的值為 Paused、Active和 Inactive。
`RecurrenceInterval`	報表建立過程中的請求負載中提供的重複間隔
`RecurrenceCount`	報告的剩餘次數計數
`CallbackUrl`	報表建立時在請求載荷中提供的回呼 URL
`CallbackMethod`	在報表建立過程中於請求承載提供的回呼方法
`Format`	建立報表時請求內容中提供的報表檔案格式
`EndTime`	在報表建立過程中的請求負載中提供的結束時間。只有當 `ExecuteNow` 設為「True」時才適用
`TotalRecurrenceCount`	在報表建立期間，在要求承載中提供的 `RecurrenceCount`
`nextExecutionStartTime`	下一次報表執行開始的 UTC 時間戳
`TotalCount`	Value 陣列中的記錄數目
`StatusCode`	結果碼。可能的值為 200、400、401、403、500
`message`	執行 API 的狀態消息

取得報表執行結果的 API

您可以使用此方法，使用從建立報表 API收到的 ReportId 來查詢報表執行的狀態。如果報表已準備好下載，此方法會傳回報表下載連結。否則，方法會傳回狀態。您也可以使用此 API 來取得指定報表所發生的所有執行。

重要

此 API 已針對 executionStatus=Completed 和 getLatestExecution=true設定預設查詢參數。因此，在報表第一次成功執行之前呼叫 API 會傳回 404。您可以藉由設定 executionStatus=Pending來取得待執行的任務。

要求語法

方法	要求 URI
獲取	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

要求標頭

頁眉	類型	描述
授權	字串	必填。 Microsoft Entra 存取令牌。格式為 `Bearer <token>`。
內容類型	字串	`application/json`

Path 參數

沒有

查詢參數

參數名稱	必填	類型	描述
`reportId`	是的	字串	篩選以取得只包含此自變數中所指定 `reportId` 報表的執行詳細數據。
`executionId`	不	字串	篩選，只取得此自變數中指定 `executionId` 報表的詳細數據。您可以使用分號 “;” 來指定多個 `executionIds`。
`executionStatus`	不	string/enum	篩選，只取得在此參數中指定的 `executionStatus` 報表的詳細資訊。有效值為：`Pending`、`Running`、`Paused`和 `Completed` 預設值為 `Completed`。
`getLatestExecution`	不	布爾	API 會傳回最新報表執行的詳細數據。根據預設，此參數會設定為 `true`。如果您選擇將此參數的值傳遞為 `false`，則 API 會傳回過去 90 天的執行實例。

請求負載

沒有

範例回應

響應承載的結構如下：

回應碼：200、400、401、403、404、500

響應負載範例

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

報表執行完成後，會顯示 Completed 的執行狀態。您可以選取 reportAccessSecureLink中的 URL 來下載報表。

詞彙

回應中元素的關鍵定義。

參數	描述
`ExecutionId`	執行實例的通用唯一識別碼（UUID）
`ReportId`	與執行實例相關聯的報表標識碼
`RecurrenceInterval`	報表生成時提供的重複間隔
`RecurrenceCount`	在報表建立時提供的重複次數
`CallbackUrl`	與執行實例相關聯的回呼網址
`CallbackMethod`	報表建立過程中，在要求有效負載中提供的回呼方法
`Format`	執行結束時產生的檔案格式
`ExecutionStatus`	報表執行實例的狀態。有效值為：`Pending`、`Running`、`Paused`和 `Completed`
`ReportLocation`	下載報表的位置。
`ReportAccessSecureLink`	可安全地存取報表的連結
`ReportExpiryTime`	UTC 時間之後，報表連結會以下列格式到期：yyyy-MM-ddTHH：mm：ssZ
`ReportGeneratedTime`	以下列格式產生報表的 UTC 時間：yyyy-MM-ddTHH：mm：ssZ
`EndTime`	報表創建時的請求有效負載中提供的結束時間。只有當 `ExecuteNow` 設為「True」時才適用
`TotalRecurrenceCount`	在報表建立時，在請求承載中提供的 `RecurrenceCount`
`nextExecutionStartTime`	下一次報表執行開始的 UTC 時間戳
`TotalCount`	Value 陣列中的數據集數目
`StatusCode`	結果碼可能的值為 200、400、401、403、404 和 500
`message`	執行 API 的狀態消息

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

針對 Marketplace Insights 報表進行第一個 API 呼叫

共用方式為

商業市集的程式設計存取架構

報表查詢語言規格

建立報表查詢 API

建立報表 API

取得報表執行結果的 API

意見反應

其他資源

共用方式為

商業市集的程式設計存取架構

報表查詢語言規格

建立報表查詢 API

建立報表 API

取得報表執行結果的 API

相關內容

意見反應

其他資源