資料摘要 API 概覽 (預覽版)

2025-05-14

[本文章是發行前版本文件，且隨時可能變更。]

製作者使用 Power Pages 摘要 API 來新增帶有生成式 AI 的頁面內容摘要。此功能使網站使用者無需閱讀整個頁面即可了解頁面內容的概況。此 API 建立在 Power Pages Web API 之上，為頁面上使用的 Dataverse 表提供資料匯總。

重要

這是預覽功能。
預覽功能不供生產時使用，而且可能功能受限。這些功能應受補充使用規定規範，並且是在正式發行前先行推出，讓客戶可以搶先體驗並提供意見反應。

必要條件

啟用 Web API 的網站設定。
只有 Power Pages Web API 支援的表才可用於匯總。有關 Power Pages Web API 的詳細資訊，請參閱 Web API 概述。
此功能在 Government Community Cloud (GCC)、Government Community Cloud - High (GCC High) 或 Department of Defense (DoD) 區域不可用。

網站設定

在您的 Web API 中啟用頁面並為摘要 API 功能設定以下網站設定。

網站設定名稱	Description
摘要/資料/啟用	啟用或停用摘要功能。預設值：false 有效值：true、false
Summarization/prompt/{any_identifier}	使用這些設定來提供摘要說明。類型：字串範例: 名稱：Summarization/prompt/case_summary 值：摘要關鍵細節和關鍵訊息
Summarization/Data/ContentSizeLimit	修改摘要內容的輸入大小限制。類型：整數預設值：100,000

網站設定名稱

Description

摘要/資料/啟用

啟用或停用摘要功能。
預設值：false
有效值：true、false

Summarization/prompt/{any_identifier}

使用這些設定來提供摘要說明。
類型：字串

範例:
名稱：Summarization/prompt/case_summary
值：摘要關鍵細節和關鍵訊息

Summarization/Data/ContentSizeLimit

修改摘要內容的輸入大小限制。
類型：整數
預設值：100,000

API 結構描述

方法	URI	JSON 範例
POST	[網站 URI]/_api/summarization/data/v1.0/tablesetname	`{ "InstructionIdentifier":"", "RecommendationConfig":"" }`

屬性名稱	Description
InstructionIdentifier	此屬性是選擇性的。若要傳遞額外的總結說明，請使用網站設定新增提示。始終提供先前定義的網站設定名稱。
RecommendationConfig	此屬性是選擇性的。使用此屬性傳遞摘要 API 建議的提示。該值必須經過散列處理並且保持不變。

注意

此 API 遵循 Power Pages Web API 支援的標準開放資料協定 (OData) 規範。摘要 API 支援 Power Pages Web API 中可用的所有讀取操作。

Sample

透過關注關鍵細節和重要資訊來總結案件類型、主題、描述和案件歷史。

Request

POST [Power Pages URL]/_api/summarization/data/v1.0/incidents(aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb)?$select=description,title&$expand=incident_adx_portalcomments($select=description)
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"InstructionIdentifier": "Summarization/prompt/case_summary"
}

回應

HTTP/1.1 200 OK
OData-Version: 4.0
{
  "Summary": "The data results provide information…",
  "Recommendations": [
    {
      "Text": "would you like to know about…?",
      "Config": "HSYmaicakjvIwTFYeCIjKOyC7nQ4RTSiDJ+/LBK56r4="
    }
  ]
}

摘要回應提供了微調摘要的建議提示。若要使用這些建議，請在請求正文中傳遞不帶 InstructionIdentifier 屬性的設定值。

安全性

摘要 API 遵循為資料表和資料欄權限設定的角色型安全性。它僅考慮使用者可以存取的記錄進行匯總。

驗證摘要 API

您不需要包括驗證代碼，因為應用程式工作階段會管理驗證和授權。所有 Web API 呼叫都必須包含跨網站偽造要求 (CSRF) 權杖。

錯誤代碼和訊息

下表描述了使用摘要 API 時可能遇到的不同錯誤代碼和訊息。

狀態碼	錯誤碼	Error message
400	90041001	生成式 AI 功能已停用
400	90041003	該網站已停用資料摘要。請使用網站設定來啟用。
400	90041004	內容長度超出限制
400	90041005	找不到要摘要的記錄
400	90041006	摘要內容時發生錯誤。

資料匯總 API 常見問題

共用方式為