Cloud Storage 取り込みパイプライン

このドキュメントでは、Cloud Storage 取り込みパイプラインの機能と、パイプラインの実行方法について説明します。

Cloud Storage 取り込みパイプラインの機能

ユーザーは、Cloud Storage から Document AI Warehouse にドキュメントを転送できます。ユーザーは、検索、ドキュメント管理ワークフロー、Document AI 出力のテストなどのタスクで処理されるように選択できます。

このパイプラインを使用する理由

多くのドキュメントを（処理の有無にかかわらず）取り込む必要がある場合、このパイプラインは信頼性の高いワークフローを提供します。また、ユーザーが概念実証や本番環境のワークロードのために Document AI Warehouse のお客様をオンボーディングするまでの時間を短縮するのにも役立ちます。

パイプライン機能

一般に、Cloud Storage 取り込みパイプラインは次のアクションをサポートしています。

未加工のドキュメントを Document AI ウェアハウスに取り込みます。

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
  }
}

Document AI で処理されたドキュメントを Document AI ウェアハウスに取り込みます。
```
{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}
```
processor_type は、入力ファイルが Document AI によって処理されたことを示すために必要です。processor_type（OCR_PROCESSOR、INVOICE_PROCESSOR、FORM_PARSER_PROCESSOR）は、API を入力フィールドのこちらで確認できます。
Document AI で処理されたドキュメントと対応する未加工のドキュメントを同じリクエストで取り込みます。
```
{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}
```
input_path の場所には、Document AI で処理されたドキュメントが含まれている必要があります。パイプラインは、その URI パスにある Doc AI で処理された各ドキュメントに対応する未加工ドキュメントを検索します。

1 種類の未加工ドキュメントを取り込み、パイプラインで Document AI 処理をトリガーします。

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    extract_processor_infos: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
      schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
    },
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

extract_processor_infos フィールドには、抽出プロセッサを 1 つだけ含める必要があります。input_path フィールドのすべてのドキュメントは 1 つのドキュメントタイプとみなされ、同じ抽出プロセッサによって処理されます。

複数の種類の未加工ドキュメントを取り込み、パイプラインで Document AI 処理をトリガーします。

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    split_classify_processor_info: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
    },
    extract_processor_infos: [
      {
        processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
        document_type: "DOCUMENT_TYPE",
        schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
      }
    ],
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

split_classify_processor_info フィールドは、ドキュメントをタイプ別に分類します。extract_processor_infos フィールド（配列として渡される）には、分類結果の各ドキュメントタイプに対応するさまざまな抽出プロセッサが含まれている必要があります。

取り込みの構成

Cloud Storage 取り込みパイプラインは、次のオプションで説明するように、ドキュメントの取り込み時にオプションのカスタマイズをサポートしています。

skip_ingested_documents フラグを使用して、同じ Cloud Storage フォルダでパイプラインが複数回トリガーされたときに、取り込まれたドキュメントをスキップします。Cloud Storage 内のドキュメントに、パイプラインのステータストラッキング機能である status=ingested メタデータが含まれている場合、このフラグが有効になっていると、ドキュメントは再取り込みされません。
ドキュメントの作成時に追加のドキュメントレベルの ACL ポリシーを指定するには、document_acl_policy フラグを使用します。このフラグは、Document AI ウェアハウスでドキュメントレベルの ACL が有効になっているプロジェクト用です。
ドキュメントにコンテンツが含まれている場合は、enable_document_text_extraction フラグを使用して、Document AI Warehouse に元ドキュメントのテキストを抽出させます。このフラグは Document AI 処理とは異なり、Document AI ウェアハウスでは次のドキュメントファイル形式のみがサポートされます。
- RAW_DOCUMENT_FILE_TYPE_TEXT
- RAW_DOCUMENT_FILE_TYPE_DOCX
folder フィールドを使用して、取り込んだドキュメントのターゲットフォルダを指定します。取り込まれたすべてのドキュメントは、指定された親フォルダにリンクされます。
cloud_function フィールドを使用して、ドキュメント proto ファイルのフィールドを Document AI Warehouse に送信する前にさらにカスタマイズします。cloud_function の値は、Document AI ウェアハウスサービスアカウントからアクセス可能な有効な URL である必要があります。各通話は 5 分以内に終了する必要があります。リクエストとレスポンスは JSON 形式です。これらのキーはリクエストペイロードにあります。
- display_name
- properties
- plain_text または cloud_ai_document.text
- reference_id
- document_schema_name
- raw_document_path
- raw_document_file_type
レスポンスペイロードのキーは、proto の一部として Document AI ウェアハウスに取り込まれます。キーが変更された場合や、レスポンスにキーが追加された場合、元の値は上書きされます。レスポンス内の余分なキーは破棄されます。対応する値が無効な場合、ドキュメントの取り込みは失敗します。
- display_name
- properties
- plain_text または cloud_ai_document.text
- reference_id
- document_acl_policy
- folder

pipeline_config を使用して取り込みパイプラインをカスタマイズする。

{
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    skip_ingested_documents: "true",
    pipeline_config: {
      enable_document_text_extraction: "true"
      folder: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documents/FOLDER_DOCUMENT_ID",
      cloud_function: "https://REGION-PROJECT_ID.cloudfunctions.net/CLOUD_FUNCTION_NAME"
    }
  }
}

ステータスのトラッキング

ステータストラッキングには、パイプライン全体と各ドキュメントの取り込み結果の進行状況が表示されます。

LRO が完了したかどうかを確認することで、パイプラインが完了したかどうかを確認できます。
パイプライン内の各ドキュメントのステータスは、Cloud Storage メタデータを表示して確認できます。Cloud Storage は、各ドキュメントに次の Key-Value ペアを作成します。
- キー: status。値: status=queued、status=processed、status=ingested、status=failed のいずれか。
- キー: error、値: the error message。

サポートされているドキュメントの種類

パイプラインでサポートされているドキュメントタイプは、Document AI ウェアハウスでサポートされているドキュメントタイプと同じです。テキスト、PDF、画像（スキャンされた PDF、TIFF ファイル、JPEG ファイル）、Microsoft Office ファイル（DOCX、PPTX、XSLX）。

Cloud Storage メタデータからのドキュメントプロパティ

パイプラインで Cloud Storage メタデータを使用して、Document AI Warehouse でカスタムプロパティを作成できます。Cloud Storage ドキュメントのメタデータ値は、そのキーがスキーマ内のプロパティ名と一致する場合、対応する Document AI Warehouse ドキュメントのプロパティに自動的にコピーされます。

パイプラインの実行

Cloud Storage 取り込みパイプラインでさまざまな機能をトリガーするには、さまざまなパラメータが必要です。詳細については、メソッド: projects.locations.runPipeline をご覧ください。

次のパートでは、Cloud Storage 取り込みパイプラインをトリガーする 2 つの例を示します。

Document AI プロセッサなしで Cloud Storage 取り込みパイプラインを実行します。

REST

curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
"schema_name": "projects/PROJECT_NUMBER/locations/
LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

Document AI プロセッサを使用して Cloud Storage 取り込みパイプラインを実行します。

REST

curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_with_doc_ai_processors_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
            "split_classify_processor_info": {
              "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
            },
            "extract_processor_infos": [
              {
                "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
                "document_type": "DOCUMENT_TYPE",
                "schema_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
              }
            ],
            "processor_results_folder_path": "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME/"
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

このコマンドは、長時間実行オペレーションのリソース名を返します。このリソース名を使用して、次の手順でパイプラインの進行状況を追跡できます。

長時間実行オペレーションの結果を取得する

REST

curl --location --request GET 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION' \
--header "Authorization: Bearer ${AUTH_TOKEN}"

次のステップ

取り込まれたドキュメントを確認するには、Document AI Warehouse のウェブアプリケーションに移動します。

Cloud Storage 取り込みパイプライン コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。