分析文件 API 回應
此內容適用於： 
v4.0 (預覽) v3.1 (GA) v3.0 (GA)
在本文中，我們將檢視作為 AnalyzeDocument 回應的一部分所傳回的不同物件，以及如何在您的應用程式中使用文件分析 API 回應。
分析文件要求
文件智慧 API 會分析影像、PDF 和其他文件檔，以擷取及偵測各種內容、版面配置、樣式和語意元素。 分析作業是非同步 API。 提交文件會傳回 Operation-Location 標頭，其中包含要輪詢完成的 URL。 當分析要求成功完成時，回應會包含模型資料擷取中所述的元素。
回應元素
內容元素是從文件擷取的基本文字元素。
版面配置元素會將內容元素分組成結構化單位。
樣式元素描述內容元素的字型和語言。
語意元素會將意義指派給指定的內容元素。
所有內容元素都會根據頁面進行分組，並依頁碼 (1 索引) 指定。 元素也會依讀取順序排序，以將語意上連續元素排列在一起，即使其跨行或資料行界限也一樣。 當段落和其他版面配置元素之間的讀取順序模棱兩可時，服務通常會以從左至右、從上到下的順序傳回內容。
注意
目前，文件智慧不支援跨頁面界限的讀取順序。 選取標記不會放置在周圍單字內。
最上層內容屬性包含讀取順序中所有內容元素的串連。 所有元素都會透過這個內容字串內的範圍，以讀取器順序指定其位置。 某些元素的內容並不總是連續的。
分析回應
每個 API 的分析回應都會傳回不同的物件。 API 回應包含適用元件模型中的元素。
| 回應內容 | 描述 | API |
|---|---|---|
| 頁面 | 從輸入文件的每個頁面辨識到的文字、行和範圍。 | 讀取、版面配置、一般文件、預先建置和自訂模型 |
| 段落 | 辨識為段落的內容。 | 讀取、版面配置、一般文件、預先建置和自訂模型 |
| 樣式 | 識別到的文字元素屬性。 | 讀取、版面配置、一般文件、預先建置和自訂模型 |
| 語言 | 識別到的語言與所擷取文字的每個範圍相關聯 | 參閱 |
| 資料表 | 從文件中識別及擷取到的表格式內容。 資料表與預先定型版面配置模型所識別到的資料表相關。 標示為資料表的內容會擷取為文件物件中的結構化欄位。 | 版面配置、一般文件、發票和自訂模型 |
| 圖形 | 從文件中識別和擷取的圖形 (圖表、影像)，提供有助於了解複雜資訊的視覺表示法。 | 版面配置模型 |
| sections | 從文件中識別和擷取的階層式文件結構。 附有對應元素 (段落、資料表、圖形) 的區段或子區段。 | 版面配置模型 |
| keyValuePairs | 預先定型模型所辨識到的機碼值組。 索引鍵是文件中具有相關聯值的文字範圍。 | 一般文件和發票模型 |
| 文件 | 辨識到的欄位會在文件清單內的 fields 字典中傳回 |
預先建置的模型、自訂模型。 |
如需關於每個 API 所傳回物件的詳細資訊，請參閱模型資料擷取。
元素屬性
跨越
範圍會以整體讀取順序指定每個元素的邏輯位置，而每個範圍都會將字元位移和長度指定到最上層內容字串屬性。 根據預設，字元位移和長度會以使用者感知字元 (也稱為 grapheme clusters 或文字元素) 的單位傳回。 若要容納使用不同字元單位的不同開發環境，使用者也可以指定 stringIndexIndex 查詢參數，以傳回 Unicode 字碼指標 (Python 3) 或 UTF16 程式碼單位 (JAVA、JavaScript、.NET)。 如需詳細資訊，請參閱多語言/表情符號支援。
周框區域
周框區域描述檔案中每個元素的視覺位置。 當元素在視覺上不連續或跨頁面 (資料表) 時，大多數元素的位置都是透過邊界區域陣列來描述的。 每個區域都會指定頁碼 (以 1 索引) 和周框多邊形。 周框多邊形會描述為一連串的點，從左側相對於元素的自然方向順時針排列。 針對四邊形，繪圖點是左上角、右上角、右下角和左下角。 每個點都代表其 x，y 座標在單位屬性所指定的頁面單位中。 一般而言，影像的測量單位是像素，而 PDF 則使用英吋。
注意
目前，文件智慧只會傳回 4 頂點四邊形做為周框多邊形。 未來版本可能會傳回不同的點數來描述更複雜的圖形，例如曲線或非矩形影像。 周框區域只會套用至轉譯的檔案，如果檔案未轉譯，則不會傳回周框區域。 目前不會轉譯 docx/xlsx/pptx/html 格式的檔案。
內容元素
Word
單字是由字元序列所組成的內容元素。 使用文件智慧時，單字會定義為相鄰字元序列，且空白字元會將單字彼此分隔。 對於未在單字之間使用空格分隔符號的語言，每個字元都會以個別單字的形式傳回，即使其不代表語意單字單位也一樣。
選取標記
選取項目標記是代表視覺字符的內容元素，表示選取項目的狀態。 核取方塊是選取項目標記的常見形式。 不過，它們在視覺形式上也會透過選項按鈕或框選的儲存格來表示。 您可以選取或取消選取選取項目標記的狀態，以不同的視覺表示來表示狀態。
版面配置元素
線條
行是以視覺空間分隔的連續內容元素排序序列，或是緊接在文字之間沒有空格分隔符號的語言連續內容元素排序序列。 在相同水平平面 (列)，但以多個視覺空間分隔的內容元素最常分割成多行。 雖然此功能有時會將語意上連續的內容分割成不同的行，但其可讓文字內容的標記法分割成多個資料行或儲存格。 會以垂直方向偵測到垂直寫入中的行。
段落
段落是構成邏輯單元的已排序行序列。 一般而言，行會共用行之間的一般對齊和間距。 段落通常會透過縮排、新增間距或項目符號/編號來進行分隔。 您只能將內容指派給單一段落。 選取段落也可能與文件中的功能角色相關聯。 目前支援的角色包括頁首、頁尾、頁碼、標題、區段標題和註腳。
頁
頁面是一組內容，通常會對應至紙張的一面。 轉譯的頁面是透過指定單位的寬度和高度加以區分。 一般而言，影像會使用像素，而 PDF 則使用英吋。 angle 屬性會針對可能旋轉的頁面，以度為單位描述整體文字角度。
注意
對於 Excel 之類的試算表，每個工作表都會對應至頁面。 對於 PowerPoint 之類的簡報，每個投影片都會對應至頁面。 對於沒有未轉譯 HTML 或 Word 文件之類網頁原生概念的檔案格式，檔案的主要內容會被視為單一頁面。
Table
資料表會將內容組織成格線配置中的一組儲存格。 資料列和資料行可能會以視覺化方式，以格線、色彩帶狀或更大的間距分隔。 資料表儲存格的位置是透過其資料列和資料行索引加以指定。 儲存格可能會跨越多個資料列和資料行。
根據其位置和樣式，儲存格可會分類為一般內容、資料列標頭、資料行標頭、虛設常式標頭或描述：
資料列標頭儲存格通常是資料列中第一個儲存格，會描述資料列中的其他儲存格。
資料行標頭儲存格通常是資料行中第一個儲存格，會描述資料行中的其他儲存格。
資料列或資料行可包含多個標題儲存格來描述階層式內容。
虛設常式標頭儲存格通常是第一個資料列和第一個資料行位置中的儲存格。 它可以是空的，或描述相同資料列/資料行中，標頭儲存格中的值。
描述儲存格通常會出現在資料表的最上層或底部區域，描述整體資料表內容。 不過，它有時可出現在資料表中間，以將資料表分成幾個區段。 一般而言，描述儲存格跨越單一資料列中的多個儲存格。
資料表標題會指定說明資料表的內容。 資料表還可以具有相關聯的標題和一組註腳。 不同於描述儲存格，標題通常會位於格線配置之外。 資料表註腳可標註資料表內的內容，通常以資料表方格下方常見的註腳符號標示。
版面配置表格與從表格式資料擷取到的文件欄位不同。 版面配置表格會從文件中的表格式視覺內容擷取，而不需要考慮內容的語意。 事實上，某些版面配置資料表是專為視覺版面配置所設計的，並不總是包含結構化資料。 從具有不同視覺版面配置的文件擷取結構化資料的方法 (例如收據的已項目化詳細資料)，通常需要大量的後置處理。 請務必將資料列或資料行標頭對應至具有標準化欄位名稱的結構化欄位。 根據文件類型，使用預建模型或定型自訂模型來擷取這類結構化內容。 所產生的資訊會公開為文件欄位。 這類定型的模型也可以處理表格式資料，而不需要標頭和非表格式形式的結構化資料，例如履歷的工作體驗區段。
圖形
文件中的圖形 (圖表、影像) 在補充和增強文字內容方面扮演著重要的角色，提供有助於了解複雜資訊的視覺表示法。 版面配置模型所偵測到的圖形物件具有關鍵屬性，例如 boundingRegions (圖形在文件頁面上的空間位置，包括頁碼和描述圖形邊界的多邊形座標)、spans (詳細說明與圖形相關的文字範圍，指定它們在文件文字中的偏移量和長度。此連接有助於將圖形與其相關文字內容相關聯)、elements (文件中與圖形相關或描述圖形的文字元素或段落的識別碼) 和 caption (如果有的話)。
{
"figures": [
{
"boundingRegions": [],
"spans": [],
"elements": [
"/paragraphs/15",
...
],
"caption": {
"content": "Here is a figure with some text",
"boundingRegions": [],
"spans": [],
"elements": [
"/paragraphs/15"
]
}
}
]
}
區段
階層式文件結構分析對於組織、理解及處理大量的文件至關重要。 這種方法對於對長文件進行語意分段以增強理解、幫助瀏覽和改進資訊檢索至關重要。 文件生成式 AI 中的檢索增強生成 (RAG) 的出現突顯出階層式文件結構分析的重要性。 版面配置模型支援輸出中的區段和子區段，其可識別每個區段內區段和物件的關聯性。 階層式結構會在每個區段的 elements 中維護。
{
"sections": [
{
"spans": [],
"elements": [
"/paragraphs/0",
"/sections/1",
"/sections/2",
"/sections/5"
]
},
...
}
表單欄位 (機碼值組)
表單欄位包含欄位標籤 (索引鍵) 和值。 欄位標籤通常是描述欄位意義的描述性文字字串。 其通常會出現在值的左側，不過也可以出現在值的上方或下方。 欄位值包含特定欄位執行個體的內容值。 此值可包含單字、選取項目標記和其他內容元素。 對於未填寫的表單欄位，它也可以為空。 特殊類型的表單欄位具有選取項目標記值，其右側有欄位標籤。 文件欄位與一般表單欄位概念類似但不同。 一般表單欄位中的欄位標籤 (索引鍵) 必須出現在文件中。 因此，其通常無法擷取資訊，例如收據中的商家名稱。 文件欄位會加上標籤，且不會擷取索引鍵。 文件欄位只會將擷取的值對應到加上標籤的索引鍵。 如需詳細資訊，請參閱 文件欄位。
樣式元素
樣式
樣式元素描述要套用至文字內容的字型樣式。 內容會透過範圍指定至全域內容屬性。 目前，唯一偵測到的字型樣式是文字是否為手寫。 當新增其他樣式時，可以透過多個不衝突的樣式物件來描述文字。 為了精簡起見，會透過單一樣式物件描述所有共用特定字型樣式的文字 (具有相同信賴度)。
{
"confidence": 1,
"spans": [
{
"offset": 2402,
"length": 7
}
],
"isHandwritten": true
}
語言
語言元素描述透過範圍指定至全域內容屬性的內容所偵測到的語言。 偵測到的語言是透過 BCP-47 語言標籤來指定，以指出主要語言和選擇性指令碼及區域資訊。 例如，英文和繁體中文分別會辨識為「en」和「zh-Hant」。 英國英文的區域拼字差異可能會導致文字被偵測為 en-GB。 語言元素不會在沒有主要語言的情況下涵蓋文字 (例如數字)。
語意元素
注意
這裡討論的語意元素適用於文件智慧預先建置的模型。此處討論的語意元素適用於文件智慧預先建置的模型。 您的自訂模型可能會傳回不同的資料表示法。 例如，自訂模型傳回的日期和時間可能會以不同於標準 ISO 8601 格式的模式來表示。
文件
文件是語意完整的單位。 一個檔案可以包含多個文件，例如 PDF 檔案內有多個稅務表單，或單一頁面內有多個收據。 不過，檔案內文件的順序基本上不會影響其所傳達的資訊。
注意
目前，文件智慧不支援單一頁面上的多個文件。
檔案類型描述共用一組通用語意欄位的文件，由結構化結構描述所代表，與其視覺範本或版面配置無關。 例如，「收據」類型的所有文件都可能包含商家名稱、交易日期和交易總計，雖然餐廳及旅館收據的外觀通常不同。
文件元素包含所偵測到文件類型的語意結構描述所指定欄位之間的已辨識欄位清單：
可以擷取或推斷文件欄位。 如果可解譯，則會透過擷取到的內容來表示擷取到的欄位，並且選擇性地表示其正規化值。
推斷的欄位沒有內容屬性，且只會透過其值來表示。
陣列欄位不包含內容屬性。 內容可以由陣列元素的內容串連而成。
物件欄位確實包含一個內容屬性，該屬性會指定表示物件的完整內容 (該物件可以是擷取的子欄位的超集)。
文件類型的語意結構描述是透過其所包含的欄位來描述的。 每個欄位結構描述都是透過其標準名稱和實值類型加以指定。 欄位實值類型包含基本 (例如字串)、複合 (例如位址)，以及結構化 (例如陣列、物件) 類型。 欄位實值類型也會指定執行以將偵測到的內容轉換成正規化標記法的語意正規化。 正規化可能與地區設定有關。
基本類型
| 欄位實值型別 | 描述 | 正規化標記法 | 範例 (欄位內容 - > 值) |
|---|---|---|---|
| string | 純文字 | 與內容相同 | 商家名稱："Contoso" → "Contoso" |
| date | Date | ISO 8601 - YYYY-MM-DD | 發票日期："5/7/2022" → "2022-05-07" |
| time | 時間 | ISO 8601 - hh:mm:ss | 交易時間："9:45 PM" → "21:45:00" |
| 電話號碼 | 電話號碼 | E.164 - +{CountryCode}{SubscriberNumber} | 公司電話號碼："(800) 555-7676" → "+18005557676" |
| countryRegion | 國家/地區 | ISO 3166-1 alpha-3 | 國家/地區："United States" → "USA" |
| selectionMark | Is selected | "signed" 或 "unsigned" | AcceptEula：☑ → "selected" |
| 簽章 | Is signed | 與內容相同 | LendeeSignature：{signature} → "signed" |
| 數值 | 浮點數 | 浮點數 | 數量："1.20" → 1.2 |
| 整數 | 整數 | 64 位元帶正負號的數字 | 計數："123" → 123 |
| boolean | 布林值 | true/false | IsStatutoryEmployee：☑ → true |
複合類型
貨幣：貨幣金額，並有選擇性的貨幣單位。 值，例如：
InvoiceTotal: $123.45{ "amount": 123.45, "currencySymbol": "$" }位址：剖析的位址。 例如：
ShipToAddress: 123 Main St., Redmond, WA 98052{ "poBox": "PO Box 12", "houseNumber": "123", "streetName": "Main St.", "city": "Redmond", "state": "WA", "postalCode": "98052", "countryRegion": "USA", "streetAddress": "123 Main St." }
結構化類型
陣列：相同類型的欄位清單
"Items": { "type": "array", "valueArray": [ ] }物件：可能不同類型的子欄位具名清單
"InvoiceTotal": { "type": "currency", "valueCurrency": { "currencySymbol": "$", "amount": 110 }, "content": "$110.00", "boundingRegions": [ { "pageNumber": 1, "polygon": [ 7.3842, 7.465, 7.9181, 7.465, 7.9181, 7.6089, 7.3842, 7.6089 ] } ], "confidence": 0.945, "spans": [ { "offset": 806, "length": 7 } ] }
下一步
使用 Document Intelligence Studio 嘗試處理自己的表單和文件。
完成 Document Intelligence 快速入門，並開始以您選擇的開發語言來建立文件處理應用程式。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應