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

文章
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

下一步

意見反映

意見反映

更多資源