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

發行項
06/14/2024

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

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

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

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

報表查詢語言規格

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

建立報表查詢 API

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

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

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

要求語法

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

要求標頭

標題	類型	描述
授權	字串	必要。 Microsoft Entra 存取令牌。格式為 `Bearer <token>`。
內容-類型	`string`	`application/JSON`

路徑參數

無

查詢參數

無

要求承載範例

{
    "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`	Yes	查詢的使用者易記名稱	字串
`Description`	No	所建立查詢的描述	字串
`Query`	Yes	根據商務需求查詢字串	字串

注意

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

範例回覆

響應承載的結構如下：

回應碼：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
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

要求標頭

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

路徑參數

無

查詢參數

無

要求承載範例

{
  "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`	Yes	指派給報表的使用者易記名稱	String
`Description`	No	已建立報表的描述	String
`QueryId`	Yes	需要用於產生報表的查詢標識碼	String
`StartTime`	Yes	報表產生開始的 UTC 時間戳。格式應該是 yyyy-MM-ddTHH：mm：ssZ	String
`ExecuteNow`	No	此參數應該用來建立只執行一次的報表。 `StartTime`如果設定為，`RecurrenceCount`則會忽略、 `RecurrenceInterval`和`EndTimetrue`	布林值
`QueryStartTime`	No	選擇性地指定擷取數據的查詢開始時間。此參數僅適用於已 `ExecuteNow` 設定 `true`為的一次執行報表。格式應該是 yyyy-MM-ddTHH：mm：ssZ	時間戳為字串
`QueryEndTime`	No	選擇性地指定擷取數據的查詢結束時間。此參數僅適用於已 `ExecuteNow` 設定 `true`為的一次執行報表。格式應該是 yyyy-MM-ddTHH：mm：ssZ	時間戳為字串
`RecurrenceInterval`	Yes	產生報表的時數頻率。最小值為 1，最大值為 17520	整數
`RecurrenceCount`	Yes	要產生的報表數目。限制取決於周期間隔	整數
`Format`	No	匯出檔案的檔案格式。預設格式為 CSV	CSV/TSV
`CallbackUrl`	No	可選擇性地設定為回呼目的地的可公開存取 URL	String
`CallbackMethod`	No	取得/張貼方法，可使用回呼 URL 進行設定	GET/POST
`EndTime`	Yes	報表產生即將結束的UTC時間戳。格式應該是 yyyy-MM-ddTHH：mm：ssZ	String

注意

建立報表時，EndTime或和的組合RecurrenceIntervalRecurrenceCount是必要專案。

範例回覆

響應承載的結構如下：

回應碼：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`	在報表建立期間的要求承載中提供的查詢標識碼
`Query`	將針對此報表執行的查詢文字
`User`	用來建立報表的使用者標識碼
`CreatedTime`	UTC 以下列格式建立報表的時間：yyyy-MM-ddTHH：mm：ssZ
`ModifiedTime`	UTC 上次以下列格式修改報表的時間：yyyy-MM-ddTHH：mm：ssZ
`ExecuteNow`	報表建立期間在要求承載中提供的 ExecuteNow 參數
`queryStartTime`	在報表建立期間，要求承載中提供的查詢開始時間。只有在設定為「True」時才 `ExecuteNow` 適用
`queryEndTime`	在報表建立期間，要求承載中提供的查詢結束時間。只有在設定為「True」時才 `ExecuteNow` 適用
`StartTime`	在報表建立期間的要求承載中提供的開始時間
`ReportStatus`	報表執行的狀態。可能的值為 Paused、 Active 和 Inactive。
`RecurrenceInterval`	在報表建立期間，要求承載中提供的周期間隔
`RecurrenceCount`	報告的剩餘週期計數
`CallbackUrl`	報表建立期間在要求承載中提供的回呼 URL
`CallbackMethod`	報表建立期間在要求承載中提供的回呼方法
`Format`	報表建立期間在要求承載中提供的報表檔案格式
`EndTime`	在報表建立期間的要求承載中提供的結束時間。只有在設定為「True」時才 `ExecuteNow` 適用
`TotalRecurrenceCount`	`RecurrenceCount` 在報表建立期間的要求承載中提供
`nextExecutionStartTime`	下一次報表執行開始的 UTC 時間戳
`TotalCount`	Value 陣列中的記錄數目
`StatusCode`	結果碼。可能的值為 200、400、401、403、500
`message`	執行 API 的狀態消息

取得報表執行 API

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

重要

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

要求語法

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

要求標頭

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

路徑參數

無

查詢參數

參數名稱	必要	類型	描述
`reportId`	Yes	字串	篩選以取得此自變數中指定之報表 `reportId` 的執行詳細數據。
`executionId`	No	字串	篩選以取得此自變數中指定之報表 `executionId` 的詳細數據。您可以使用分號 “;” 來指定多個 `executionIds` 。
`executionStatus`	No	string/enum	篩選以取得此自變數中指定之報表 `executionStatus` 的詳細數據。有效值為：`Pending`、、`RunningPaused`、和`Completed` 預設值是 `Completed`。
`getLatestExecution`	No	boolean	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 。您可以選取中的 reportAccessSecureLinkURL 來下載報表。

詞彙

回應中專案的主要定義。

參數	描述
`ExecutionId`	執行實例的通用唯一識別碼（UUID）
`ReportId`	與執行實例相關聯的報表標識碼
`RecurrenceInterval`	報表建立期間提供的周期間隔
`RecurrenceCount`	報表建立期間提供的週期計數
`CallbackUrl`	與執行實例相關聯的回呼 URL
`CallbackMethod`	報表建立期間在要求承載中提供的回呼方法
`Format`	執行結束時產生的檔案格式
`ExecutionStatus`	報表執行實例的狀態。有效值為：`Pending`、、`RunningPaused`、和`Completed`
`ReportLocation`	下載報表的位置。
`ReportAccessSecureLink`	可安全地存取報表的連結
`ReportExpiryTime`	UTC 時間之後，報表連結會以下列格式到期：yyyy-MM-ddTHH：mm：ssZ
`ReportGeneratedTime`	以下列格式產生報表的 UTC 時間：yyyy-MM-ddTHH：mm：ssZ
`EndTime`	在報表建立期間的要求承載中提供的結束時間。只有在設定為「True」時才 `ExecuteNow` 適用
`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

相關內容

意見反應

其他資源