ドキュメント API 応答を分析する

[アーティクル]
10/16/2024

この記事では、AnalyzeDocument 応答の一部として返されるさまざまなオブジェクトと、アプリケーションでドキュメント分析 API 応答を使用する方法について説明します。

ドキュメント要求を分析する

Document Intelligence API は、画像、PDF、その他のドキュメントファイルを分析して、さまざまなコンテンツ、レイアウト、スタイル、セマンティック要素を抽出および検出します。 Analyze 操作は非同期 API です。ドキュメントを送信すると、完了をポーリングする URL を含む Operation-Location ヘッダーが返されます。分析要求が正常に完了すると、応答には、「モデルデータの抽出」で説明されている要素が含まれます。

応答の要素

コンテンツ要素は、ドキュメントから抽出された基本的なテキスト要素です。
レイアウト要素は、コンテンツ要素を構造単位にグループ化します。
スタイル要素は、コンテンツ要素のフォントと言語の説明です。
セマンティック要素は、指定されたコンテンツ要素に意味を割り当てます。

すべてのコンテンツ要素は、ページ番号 (1-indexed) で指定されたページごとにグループ化されます。また、行や列の境界をまたいでいる場合でも、読み取り順に並べ替えられ、意味的に連続した要素がまとめて配置されます。段落やその他のレイアウト要素間の読み取り順があいまいな場合、サービスでは通常、コンテンツを左から右、上から下の順に返します。

Note

現在、Document Intelligence では、ページ境界を越える読み取り順はサポートされていません。選択マークは、周辺語内に配置されません。

最上位コンテンツのプロパティには、すべてのコンテンツ要素を読み取り順に連結したものが含まれます。すべての要素は、このコンテンツ文字列内のスパンを使用して、読み取り順の位置を指定します。一部の要素の内容は、常に連続しているわけではありません。

応答を分析する

各 API の Analyze では、さまざまなオブジェクトが返されます。 API 応答には、該当するコンポーネントモデルの要素が含まれます。

応答コンテンツ	説明	API
ページ	入力ドキュメントの各ページで認識された単語、行、スパン。	読み取り、レイアウト、一般ドキュメント、事前構築済み、カスタムモデル
段落	段落として認識されたコンテンツ。	読み取り、レイアウト、一般ドキュメント、事前構築済み、カスタムモデル
スタイル	識別されたテキスト要素プロパティ。	読み取り、レイアウト、一般ドキュメント、事前構築済み、カスタムモデル
言語	抽出されたテキストの各スパンに関連付けられている言語として識別されたもの	Read
tables	ドキュメントから識別および抽出された表形式のコンテンツ。テーブルは、事前トレーニング済みのレイアウトモデルによって識別されたテーブルに関連します。テーブルとしてラベル付けされたコンテンツは、ドキュメントオブジェクト内の構造化フィールドとして抽出されます。	レイアウト、一般ドキュメント、請求書、カスタムモデル
図形	ドキュメントから識別および抽出された図 (グラフ、画像) は、複雑な情報の解釈に役立つ視覚的表現を提供します。	レイアウトモデル
sections	ドキュメントから識別および抽出された階層型ドキュメント構造。対応する要素 (段落、テーブル、図) がアタッチされたセクションまたはサブセクション。	レイアウトモデル
keyValuePairs	事前トレーニング済みモデルによって認識されたキーと値のペア。キーは、関連付けられた値を含むドキュメントからのテキストのスパンです。	一般ドキュメントおよび請求書モデル
ドキュメント	認識されたフィールドは、ドキュメントの一覧内の `fields` ディクショナリに返されます	事前構築済みモデルおよびカスタムモデル。

各 API によって返されるオブジェクトの詳細については、「モデルデータの抽出」を参照してください。

要素のプロパティ

範囲

スパンは、全体的な読み取り順での各要素の論理的な位置を指定します。各スパンは、最上位のコンテンツ文字列プロパティへの文字オフセットと長さを指定します。既定では、文字のオフセットと長さは、ユーザーが認識する文字 (grapheme clusters またはテキスト要素とも呼ばれます) の単位で返されます。異なる文字単位を使用するさまざまな開発環境に対応するために、ユーザーは、スパンのオフセットと長さを Unicode コードポイント (Python 3) または UTF16 コード単位 (Java、JavaScript、.NET) で返す stringIndexIndex クエリパラメーターを指定することができます。詳細については、「多言語 / 絵文字のサポート」を参照してください。

検出されたスパンの例のスクリーンショット。

境界領域

境界領域は、ファイル内の各要素の視覚的な位置の説明です。要素が視覚的に連続していない場合、またはページ間 (テーブル) でない場合、ほとんどの要素の位置は境界領域の配列を介して記述されます。各領域は、ページ番号 (1-indexed) と多角形領域を指定します。多角形領域は、要素の自然な向きに対して左から時計回りに一連の点として記述されます。四角形の場合、プロットポイントは左上隅、右上隅、右下隅、および左下隅になります。各ポイントは、unit プロパティで指定されたページ単位の x、y 座標を表します。一般に、画像の測定単位はピクセルですが、PDF ではインチが使用されます。

検出された境界領域の例のスクリーンショット。

Note

現在、ドキュメントインテリジェンスは境界ポリゴンとして 4 頂点四辺形のみを返します。将来のバージョンでは、曲線や四角形以外の画像など、より複雑な図形を表すために異なる数のポイントが返される可能性があります。境界領域は、レンダリングされたファイルにのみ適用され、ファイルがレンダリングされない場合、境界領域は返されません。現在、docx/xlsx/pptx/html 形式のファイルはレンダリングされません。

コンテンツ要素

Word

単語は、一連の文字で構成されるコンテンツ要素です。 Document Intelligence では、単語は隣接する文字のシーケンスとして定義され、単語同士は空白で区切られます。単語間にスペース区切りを使用しない言語の場合、セマンティックな単語単位を表していない場合でも、各文字は個別の単語として返されます。

検出された単語の例のスクリーンショット。

選択マーク

選択マークは、選択の状態を示すビジュアルグリフを表すコンテンツ要素です。チェックボックスは、選択マークの一般的な形式です。ただし、これらは、ラジオボタンまたはボックス化されたセルを使用して視覚的フォームで表されます。選択マークの状態は、状態を示すさまざまな視覚的表現で選択または選択解除できます。

検出された選択マークの例のスクリーンショット。

レイアウト要素

折れ線

行は、空白表示で区切られた連続するコンテンツ要素、または単語間にスペース区切り記号がない言語の場合はすぐに隣接するコンテンツ要素の順序付けされたシーケンスです。同じ水平面 (行) にあるが、複数の空白表示で区切られているコンテンツ要素は、多くの場合、複数の行に分割されます。この機能によって、意味的に連続したコンテンツが別々の行に分割される場合がありますが、テキストコンテンツを複数の列またはセルに分割して表すことができます。縦書きの行は、縦方向に検出されます。

検出された行の例のスクリーンショット。

段落

段落は、論理単位を形成する行の順序付けされたシーケンスです。通常、行の配置と間隔は、行間で共通しています。多くの場合、段落はインデント、追加された間隔、箇条書きまたは行番号で区切られます。コンテンツは、1 つの段落にのみ割り当てることができます。選択した段落は、ドキュメント内の機能ロールに関連付けることもできます。現在サポートされているロールには、ページヘッダー、ページフッター、ページ番号、タイトル、セクション見出し、脚注があります。

検出された段落の例のスクリーンショット。

ページ

ページはコンテンツのグループであり、通常、紙の片面に対応します。レンダリングされたページは、指定した単位の幅と高さによって特徴付けられます。一般に、画像ではピクセルが使用され、PDF ではインチが使用されます。 angle プロパティは、回転可能なページのテキスト全体の角度を度単位で表します。

Note

Excel などのスプレッドシートの場合、各シートはページにマップされます。 PowerPoint などのプレゼンテーションの場合、各スライドはページにマップされます。 HTML や Word 文書のように、ページをレンダリングしないというネイティブの概念がないファイル形式の場合、ファイルのメインコンテンツは 1 ページと見なされます。

テーブル

テーブルは、コンテンツをグリッドレイアウト内のセルのグループに編成します。行と列は、グリッド線、色の縞模様、または大きい間隔で視覚的に区切ることができます。テーブルのセルの位置は、行と列のインデックスによって指定されます。セルは複数の行と列にまたがることができます。

セルは、その位置とスタイルに基づいて、一般的なコンテンツ、行ヘッダー、列ヘッダー、スタブヘッド、または説明として分類できます：

行ヘッダーセルは通常、行の最初のセルであり、行内の他のセルの説明です。
列ヘッダーセルは通常、列の最初のセルであり、列内の他のセルの説明です。
1 つの行または列に複数のヘッダーセルを含め、階層コンテンツを記述できます。
スタブヘッドセルは通常、最初の行と最初の列の位置にあるセルです。空にすることも、同じ行/列のヘッダーセルの値を記述することもできます。
説明セルは通常、テーブルの一番上または一番下の領域に表示され、テーブルコンテンツ全体の説明です。ただし、テーブルをセクションに分割するために、テーブルの中央に表示される場合があります。通常、説明セルは 1 つの行の複数のセルにまたがって表示されます。
テーブルキャプションは、テーブルを説明するコンテンツを指定します。テーブルには、さらにキャプションと脚注のセットを関連付けることができます。説明セルとは異なり、キャプションは通常、グリッドレイアウトの外にあります。テーブル脚注は、テーブル内のコンテンツ (多くの場合、表のグリッドの下にある脚注記号でマークされます) に注釈を付けます。

レイアウトテーブルは、表形式のデータから抽出されたドキュメントフィールドとは異なります。レイアウトテーブルはドキュメント内の表形式のビジュアルコンテンツから抽出され、コンテンツのセマンティクスは考慮されません。実際、一部のレイアウトテーブルは視覚的なレイアウト用に純粋に設計されており、常に構造化データが含まれているとは限りません。領収書の品目別の明細など、さまざまなビジュアルレイアウトを持つドキュメントから構造化データを抽出する方法は、一般に、かなりの後処理を必要とします。行または列のヘッダーを、正規化されたフィールド名を持つ構造化フィールドにマップすることが不可欠です。このような構造化コンテンツを抽出するには、ドキュメントの種類に応じて、事前構築済みモデルを使用するか、カスタムモデルをトレーニングします。結果の情報は、ドキュメントフィールドとして公開されます。このようなトレーニング済みモデルは、ヘッダーのない表形式のデータや履歴書の職歴セクションなど、表形式以外の構造化データを処理することもできます。

Note

2024-07-31-preview 以降、図形と表の境界領域はコアコンテンツのみに対応し、関連するキャプションや脚注は除外します。

レイアウトテーブル

図形

ドキュメント内の図形 (グラフ、イメージ) は、複雑な情報の解釈に役立つ視覚的表現を提供して、テキストコンテンツを補完し拡張する上で重要な役割を果たします。レイアウトモデルによって検出される図形オブジェクトには、boundingRegions (ページ番号や図形の境界を囲む多角形座標など、ドキュメントページ上の図形の空間位置)、spans (ドキュメントのテキスト内でのオフセットと長さを指定する、図形に関連するテキストスパンの詳細) などの主要なプロパティがあります。この接続は、図形を関連するテキストコンテキストに関連付けるのに役立ち、elements (図に関連する、または図を説明するドキュメント内のテキスト要素または段落の識別子)、caption (存在する場合) です。

output=figures が最初の Analyze 操作中に指定されると、サービスは、/analyeResults/{resultId}/figures/{figureId} 経由でアクセスできるすべての検出済みの図形に対してトリミングされた画像を生成します。 figureIndex がページあたり 1 つにリセットされる {pageNumber}.{figureIndex} の文書化されていない規則に従って、FigureId が各図形オブジェクトに含まれます。

{
    "figures": [
      {
        "id": "{figureId}",
        "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"
        ]
      },
...
}

フォームフィールド (キーと値のペア)

フォームフィールドは、フィールドラベル (キー) と値で構成されます。フィールドラベルは通常、フィールドの意味を説明する説明テキスト文字列です。多くの場合、これは値の左側に表示されますが、値の上または下に表示することもできます。フィールド値には、特定のフィールドインスタンスのコンテンツ値が含まれます。この値は、単語、選択マーク、その他のコンテンツ要素で構成される場合があります。また、入力されていないフォームフィールドの場合は空にすることもできます。特殊な種類のフォームフィールドとして、右側にフィールドラベルのある選択マーク値が含まれているものがあります。ドキュメントフィールドは、一般的なフォームフィールドと似ていますが、概念が異なります。一般的なフォームフィールドのフィールドラベル (キー) は、ドキュメントに表示する必要があります。したがって、通常、領収書にマーチャント名などの情報をキャプチャすることはできません。ドキュメントフィールドにはラベルが付き、キーは抽出されません。ドキュメントフィールドは、抽出された値のみをラベル付きキーにマップします。詳細については、「ドキュメントフィールド」を参照してください。

検出されたキーと値のペアの例を示すスクリーンショット。

スタイル要素

スタイル

スタイル要素は、テキストコンテンツに適用するフォントスタイルの説明です。コンテンツは、スパンを使用してグローバルコンテンツプロパティに指定されます。現在、検出されるフォントスタイルは、テキストが手書きかどうかだけです。他のスタイルが追加されると、テキストメッセージは複数の非変換スタイルオブジェクトを介して記述できます。コンパクト化のために、(同じ信頼度を持つ) 特定のフォントスタイルを共有するすべてのテキストは、1 つのスタイルオブジェクトを使用して記述されます。

検出された手書きスタイルのテキストの例を示すスクリーンショット。


{
    "confidence": 1,
    "spans": [
        {
            "offset": 2402,
            "length": 7
        }
    ],
    "isHandwritten": true
}

Language

言語要素は、スパンを使用してグローバルコンテンツプロパティに指定されたコンテンツの検出された言語の説明です。検出された言語は、プライマリ言語と、オプションのスクリプトおよび領域の情報を示す BCP-47 言語タグを使用して指定されます。たとえば、英語および繁体字中国語はそれぞれ "en" および zh-Hant として認識されます。英国英語の地域的なスペルの違いにより、en-GB としてテキスト検出される可能性があります。言語要素は、主要な言語 (数字など) のないテキストには対応していません。

セマンティックの要素

Note

ここで説明するセマンティック要素は、Document Intelligence 事前構築済みモデルに適用されます。カスタムモデルは、異なるデータ表現を返す場合があります。たとえば、カスタムモデルによって返される日付と時刻は、標準の ISO 8601 書式設定とは異なるパターンで表される場合があります。

ドキュメント

ドキュメントは意味的に完全な単位です。ファイルには、PDF ファイル内の複数の税フォームや、1 つのページ内の複数の領収書など、複数のドキュメントを含めることができます。ただし、ファイル内のドキュメントの順序は、基本的に、伝達される情報には影響しません。

Note

現在の Document Intelligence では、1 つのページ上の複数のドキュメントはサポートされていません。

ドキュメントの種類では、ビジュアルテンプレートやレイアウトに関係なく、構造化スキーマによって表されるセマンティックフィールドの共通セットを共有するドキュメントについて説明します。たとえば、「receipt」型のすべてのドキュメントには、販売者名、取引日、トランザクション合計を含めることができますが、レストランとホテルのレシートは外観が異なることがよくあります。

ドキュメント要素には、検出されたドキュメントの種類のセマンティックスキーマによって指定されたフィールドの中から認識されたフィールドの一覧が含まれます。

ドキュメントフィールドは抽出または推論できます。抽出されたフィールドは、抽出されたコンテンツと、必要に応じてその正規化された値 (解釈可能な場合) によって表されます。
推論されたフィールドにはコンテンツプロパティがないため、その値によってのみ表されます。
配列フィールドにはコンテンツプロパティは含まれません。コンテンツは配列要素のコンテンツから連結できます。
オブジェクトフィールドには、抽出されたサブフィールドのスーパーセットにすることができるオブジェクトを表す完全なコンテンツを指定するコンテンツプロパティが含まれています。

ドキュメント型のセマンティックスキーマは、ドキュメントに含まれるフィールドを介して記述されます。各フィールドスキーマは、正規名と値の型で指定されます。フィールド値の型としては、基本 (文字列など)、複合 (アドレスなど)、構造化 (配列、オブジェクトなど) 型があります。フィールド値の型では、検出されたコンテンツを正規化表現に変換するために実行されるセマンティック正規化も指定します。正規化はロケールに依存する場合があります。

基本型

フィールド値の型	説明	正規化された表現	例 (フィールドコンテンツ -> 値)
string	プレーンテキスト	コンテンツと同じ	MerchantName: "Contoso" → "Contoso"
日付	Date	ISO 8601 - YYYY-MM-DD	InvoiceDate: "5/7/2022" → "2022-05-07"
time	Time	ISO 8601 - hh:mm:ss	TransactionTime: "9:45 PM" → "21:45:00"
phoneNumber	電話番号	E.164 - +{CountryCode}{SubscriberNumber}	WorkPhone: "(800) 555-7676" → "+18005557676"
countryRegion	国/リージョン	ISO 3166-1 alpha-3	CountryRegion: "United States" → "USA"
selectionMark	選択済み	"signed" または "unsigned"	AcceptEula: ☑ → "selected"
signature	署名済み	コンテンツと同じ	LendeeSignature: {signature} → "signed"
number	浮動小数点数	浮動小数点数	Quantity: "1.20" → 1.2
整数 (integer)	整数	64 ビット符号付き	Count: "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 クイックスタートを完了し、選択した開発言語でドキュメント処理アプリの作成を開始します。

次の方法で共有

ドキュメント API 応答を分析する

ドキュメント要求を分析する

応答の要素

応答を分析する

要素のプロパティ

範囲

境界領域

コンテンツ要素

Word

選択マーク

レイアウト要素

折れ線

段落

ページ

テーブル

図形

セクション

フォームフィールド (キーと値のペア)

スタイル要素

スタイル

Language

セマンティックの要素

ドキュメント

基本型

複合型

構造化型

次のステップ

フィードバック

その他のリソース

次の方法で共有

ドキュメント API 応答を分析する

ドキュメント要求を分析する

応答の要素

応答を分析する

要素のプロパティ

範囲

境界領域

コンテンツ要素

Word

選択マーク

レイアウト要素

折れ線

段落

ページ

テーブル

図形

セクション

フォーム フィールド (キーと値のペア)

スタイル要素

スタイル

Language

セマンティックの要素

ドキュメント

基本型

複合型

構造化型

次のステップ

フィードバック

その他のリソース

フォームフィールド (キーと値のペア)