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) 位於「Type in API」(輸入 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 處理文件的對應原始文件。

擷取一種原始文件，並在管道中觸發 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 欄位只能包含一個擷取處理器。input_path 欄位下的所有文件都會視為同一種文件類型，並由相同的擷取處理器處理。

在管道中擷取多種原始文件，並觸發 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 擷取管道支援在擷取文件時進行選用自訂作業，如下列選項所述：

如果管道在同一個 Cloud Storage 資料夾中觸發多次，請使用 skip_ingested_documents 旗標略過已擷取的檔案。如果 Cloud Storage 中的文件含有 status=ingested 中繼資料 (管道的狀態追蹤功能)，啟用這個旗標後，系統就不會重新擷取文件。
使用 document_acl_policy 旗標在建立文件時提供額外的文件層級 ACL 政策。這項標記適用於在 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 倉儲前，進一步自訂欄位。cloud_function 值必須是 Document AI Warehouse 服務帳戶可存取的有效網址。每通電話必須在 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 會在每份文件中建立下列鍵/值組合。
- 鍵：status；值：status=queued、status=processed、status=ingested 或 status=failed。
- 鍵：error；值：the error message。

支援的文件類型

管道支援的文件類型與 Document AI Warehouse 支援的文件類型相同：文字、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 擷取管道。

執行 Cloud Storage 擷取管道，但不使用 Document AI 處理器。

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 擷取管道 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Cloud Storage 擷取管線的功能為何？

為什麼要使用這個管道？

管道功能

擷取設定

狀態追蹤

支援的文件類型

Cloud Storage 中繼資料的文件屬性

執行管道

REST

REST

取得長時間執行的作業結果

REST

後續步驟

Cloud Storage 擷取管道