商業市集的程式設計存取架構
此圖顯示用來建立新報表範本、排程自定義報表及擷取失敗數據的 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。