共用方式為


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

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

說明用來建立新報表範本、排程自定義報表及擷取失敗數據的 API 呼叫模式。 圖 1:API 呼叫模式的高階流程

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

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

報表查詢語言規格

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

建立報表查詢 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,則會忽略 StartTimeRecurrenceIntervalRecurrenceCountEndTime 布爾
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 字串

注意

建立報表時,EndTimeRecurrenceIntervalRecurrenceCount 的組合是必要的。

範例回應

響應承載的結構如下:

回應碼: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 報表執行的狀態。 可能的值為 PausedActiveInactive
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=CompletedgetLatestExecution=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 報表的詳細資訊。
有效值為:PendingRunningPausedCompleted
預設值為 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 報表執行實例的狀態。
有效值為:PendingRunningPausedCompleted
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。