Hướng dẫn sử dụng

Glasswall Conform được thiết kế để tiền xử lý các tệp PDF nhằm đáp ứng các tiêu chuẩn cho quá trình xử lý tiếp theo. Công cụ này trích xuất và tái dựng nội dung trực quan và nên được sử dụng cùng với Glasswall Embedded Engine để có khả năng bảo vệ Content Disarm and Reconstruction (CDR) đầy đủ.

Tài liệu này cung cấp hướng dẫn sử dụng Conform để tái dựng tài liệu PDF, cùng với một số ví dụ về cách gọi công cụ dòng lệnh.

Cài đặt

Conform được cài đặt dưới dạng lệnh toàn hệ thống có thể truy cập từ terminal của bạn.

Sau khi cài đặt, lệnh glasswall_conform sẽ khả dụng trên PATH của hệ thống. Bạn có thể cần khởi động lại phiên terminal để thay đổi này có hiệu lực.

Windows

Conform cho Windows được phân phối dưới dạng trình cài đặt .exe. Công cụ được cài đặt vào C:\Program Files (x86)\Glasswall Conform và thêm thư mục này vào PATH của hệ thống.

Cài đặt Conform bằng cách chạy trình cài đặt và làm theo hướng dẫn:

.\glasswall-conform-1.1.0.exe

Hoặc cài đặt ở chế độ im lặng để tự động hóa hoặc dùng trong môi trường CI:

.\glasswall-conform-1.1.0.exe /VERYSILENT

Linux

Conform cho Linux được phân phối dưới dạng cả gói .rpm và .deb.

Cả hai đều cài đặt tệp vào /opt/glasswall_conform và tạo một liên kết tượng trưng trong /usr/local/bin để cho phép chạy glasswall_conform từ dòng lệnh.

RPM (ví dụ: Rocky 9, Rocky 8)

sudo yum -y install ./glasswall_conform-1.1.0-1.x86_64.rpm

DEB (ví dụ: Ubuntu 24.04, Ubuntu 22.04)

sudo apt-get -y install ./glasswall-conform_1.1.0_amd64.deb

Thiết lập

Trước khi gọi glasswall_conform, hãy đảm bảo rằng môi trường của bạn được thiết lập chính xác.

Đối với các chế độ sử dụng Embedded Engine, thư mục được truyền vào --library-directory phải chứa các tệp nhị phân của Embedded Engine. Conform xác minh điều này khi khởi động và dừng lại với một thông báo ngắn nếu chúng không có mặt.

Linux

Đối với các chế độ xử lý sử dụng Embedded Engine, LD_LIBRARY_PATH phải được thiết lập để bao gồm thư mục chứa Embedded Engine. Ví dụ: nếu Embedded Engine ở đường dẫn /home/azureuser/glasswall/Release-16.2.0 thì bạn có thể tạm thời sửa đổi LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/home/azureuser/glasswall/Release-16.2.0:$LD_LIBRARY_PATH

Ubuntu

Trên các hệ thống dựa trên Ubuntu, nếu bạn gặp thông báo lỗi libgthread-2.0.so.0: cannot open shared object file: No such file or directory, bạn có thể khắc phục bằng cách cài đặt gói cần thiết bằng lệnh sau:

DEBIAN_FRONTEND=noninteractive && apt update && apt install -y libglib2.0-0

Windows

Chúng tôi khuyến nghị cài đặt các phần phụ thuộc của Windows bằng chocolatey.

Đối với tất cả các chế độ xử lý, Microsoft Visual C++ Redistributable phải được cài đặt.

Đối với các chế độ xử lý sử dụng Embedded Engine:

PATH phải được thiết lập để bao gồm thư mục chứa Embedded Engine. Ví dụ: nếu Embedded Engine nằm tại đường dẫn C:/glasswall/Release-16.2.0, bạn có thể tạm thời sửa đổi PATH:
```
SET "PATH=%PATH%;C:/glasswall/Release-16.2.0"
```
Cần cài đặt OpenSSL light hoặc OpenSSL.

Ví dụ cài đặt docker trên Windows cho vcredist140 và openssl.light bằng chocolatey:

# escape=`
FROM mcr.microsoft.com/windows/servercore:ltsc2022

USER ContainerAdministrator
WORKDIR C:\temp\
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

# Download and install Chocolatey, to install OpenSSL and Visual C++ Redistributable
RUN Invoke-WebRequest -Uri 'https://chocolatey.org/install.ps1' -OutFile 'install.ps1'; `
    ./install.ps1; ` 
    Remove-Item install.ps1; `
    Import-Module "$env:ChocolateyInstall/helpers/chocolateyProfile.psm1"; `
    choco install -y --fail-on-unfound --no-progress --stop-on-first-package-failure vcredist140; `
    choco install -y --fail-on-unfound --no-progress --stop-on-first-package-failure openssl.light;

Cấp phép

Glasswall Conform yêu cầu giấy phép hợp lệ để hoạt động. Để nhận tệp giấy phép, hãy liên hệ [email protected].

Đối số --license có thể được dùng trong tất cả các chế độ xử lý để chỉ định trực tiếp đường dẫn đến tệp giấy phép hoặc đường dẫn đến thư mục chứa tệp gwkey.lic.

Chế độ Engine (engine, engine_memory): --license là tùy chọn. Nếu không được chỉ định, Conform sẽ tự động tìm kiếm trong --library-directory một tệp gwkey.lic. Nếu tìm thấy, tệp đó sẽ được sử dụng làm giấy phép. Nếu không tìm thấy, một lỗi sẽ được đưa ra.
Các chế độ chỉ dùng Conform (conform_only, conform_only_memory): --license là bắt buộc vì không có thư mục thư viện để tìm kiếm.

Nếu giấy phép bị thiếu, không hợp lệ hoặc không chứa các quyền cần thiết, Conform sẽ thoát với mã lỗi 2.

  --license LICENSE      Path to the Glasswall Conform license file, or a directory containing 'gwkey.lic'.
                         Required for conform_only and conform_only_memory modes.
                         In engine modes, defaults to 'gwkey.lic' in the library directory if not specified.

Các chế độ xử lý

Conform được chạy từ dòng lệnh và cung cấp một số chế độ xử lý để xử lý tệp. Khi gọi glasswall_conform, đối số vị trí đầu tiên chỉ định chế độ xử lý. Các chế độ xử lý khả dụng là:

engine: Bảo vệ tệp bằng Engine. Các tệp không phù hợp sẽ được Conform tái tạo rồi được Engine xử lý.
conform_only: Tái tạo tệp chỉ bằng Conform, không cung cấp khả năng bảo vệ CDR.
engine_memory: Chấp nhận một tệp được mã hóa base64 qua đầu vào tiêu chuẩn. Bảo vệ một tệp duy nhất trong bộ nhớ bằng Engine. Nếu tệp không phù hợp, tệp sẽ được tái tạo bằng Conform rồi được Engine xử lý. Tệp đã xử lý được trả về qua đầu ra tiêu chuẩn hoặc lỗi được trả về qua đầu ra lỗi tiêu chuẩn.
conform_only_memory: Chấp nhận một tệp được mã hóa base64 qua standard input. Tái tạo một tệp duy nhất chỉ bằng Conform, không cung cấp bảo vệ CDR. Tệp đã tái tạo được trả về qua standard output, hoặc lỗi được trả về qua standard error.

Để hiển thị các chế độ xử lý khả dụng:

glasswall_conform -h

engine

Chế độ xử lý này là mặc định được thiết kế sẵn và làm sạch tệp bằng công nghệ Glasswall CDR. Chế độ này yêu cầu quyền truy cập vào Embedded Engine và một giấy phép hợp lệ.

Để xem ví dụ về cách gọi chế độ xử lý này, hãy xem: Bảo vệ đầu cuối đến đầu cuối.

Các tệp đã xử lý được sắp xếp vào một trong ba thư mục con đầu ra:

01_engine_success: Các tệp được Embedded Engine xử lý thành công mà không cần Conform tái tạo.
02_conform_engine_success: Các tệp PDF ban đầu không thể được Embedded Engine xử lý, nhưng đã được Conform tái tạo và sau đó được Embedded Engine xử lý thành công.
03_failure: Các tệp không thể được xử lý bằng cả Embedded Engine và Conform, hoặc chứa nội dung đã được đặt thành không cho phép bằng một policy quản lý nội dung tùy chỉnh.

Để hiển thị các đối số dòng lệnh cho chế độ xử lý engine:

glasswall_conform engine -h

conform_only

Chế độ xử lý này tái tạo tệp mà không sử dụng Embedded Engine. Chế độ này không cung cấp bảo vệ CDR.

Để xem ví dụ về cách gọi chế độ xử lý này, hãy xem: Tái tạo tệp mà không có bảo vệ CDR

Các tệp đã xử lý được sắp xếp vào một trong hai thư mục con đầu ra:

01_conform_success: Các tệp được Conform tái cấu trúc thành công.
02_failure: Các tệp không thể được Conform tái cấu trúc.

Để hiển thị các đối số dòng lệnh cho chế độ xử lý conform_only:

glasswall_conform conform_only -h

engine_memory

Chế độ này chấp nhận một tệp được mã hóa base64 qua đầu vào tiêu chuẩn và xử lý tệp đó bằng Embedded Engine. Nếu tệp không tuân thủ, tệp sẽ được Conform tái cấu trúc, sau đó được xử lý bởi Engine. Đầu ra cuối cùng được trả về qua đầu ra tiêu chuẩn hoặc lỗi được trả về qua đầu ra lỗi tiêu chuẩn. Không có tệp nào được ghi vào đĩa.

Chế độ này lý tưởng để tích hợp với các hệ thống lưu giữ tệp trong bộ nhớ và không phụ thuộc vào đầu vào hoặc đầu ra của hệ thống tệp.

Để xem ví dụ về cách gọi chế độ xử lý này, hãy xem: Xử lý tệp trong bộ nhớ mà không đọc từ hoặc ghi vào đĩa.

Để hiển thị các đối số dòng lệnh cho chế độ xử lý engine_memory:

glasswall_conform engine_memory -h

Đối số tùy chọn --file-name có thể được dùng để chỉ định tên của tệp trong bộ nhớ. Tên này được dùng khi ghi log và bản tóm tắt sau xử lý, và mặc định là 8 ký tự đầu tiên của dữ liệu được mã hóa base64 nếu không được chỉ định.

conform_only_memory

Chế độ này chấp nhận một tệp được mã hóa base64 qua đầu vào tiêu chuẩn và chỉ tái cấu trúc tệp đó bằng Conform (không có bảo vệ CDR). Tệp đã được tái cấu trúc được trả về qua đầu ra tiêu chuẩn hoặc lỗi được trả về qua đầu ra lỗi tiêu chuẩn. Không có tệp nào được ghi vào đĩa.

Để xem ví dụ về cách gọi chế độ xử lý này, hãy xem: Xử lý tệp trong bộ nhớ mà không đọc từ hoặc ghi vào đĩa.

Để hiển thị các đối số dòng lệnh cho chế độ xử lý conform_only_memory:

glasswall_conform conform_only_memory -h

Kiểm thử

Có sẵn một bộ dữ liệu các tệp PDF thử nghiệm để đánh giá Conform theo yêu cầu. Vui lòng liên hệ với chúng tôi để yêu cầu quyền truy cập vào các tệp thử nghiệm qua Kiteworks.

Ví dụ

Examples

Bảo vệ đầu cuối đến đầu cuối

Ví dụ này minh họa việc sử dụng chế độ xử lý engine ở mức cơ bản nhất.

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0

Thư mục đầu vào ví dụ:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

Thư mục đầu ra ví dụ sau khi xử lý:

/home/azureuser/output_files
├───01_engine_success
│       conforming_docx.docx
│       conforming_pdf.pdf
│
├───02_conform_engine_success
│       nonconforming_pdf.pdf
│
└───03_failure
        corrupt_docx.docx
        unsupported_filetype.txt

Lưu ý rằng tên các thư mục con có thể được tùy chỉnh bằng các đối số sau:

--engine-success-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp đã được xử lý thành công bởi Embedded Engine mà không cần Conform tái tạo. Mặc định là 01_engine_success
--conform-success-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp ban đầu không thể được xử lý bởi Embedded Engine, nhưng đã được Conform tái tạo và sau đó được Embedded Engine xử lý thành công. Mặc định là 02_conform_engine_success
--failure-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp không thể được xử lý bằng cả Embedded Engine và Conform. Mặc định là 03_failure

Nếu muốn tất cả các tệp được bảo vệ thành công được ghi vào cùng một thư mục đầu ra, bất kể Conform có được dùng để tái tạo tệp hay không, bạn có thể chỉ định ghi tệp vào cùng một đường dẫn thư mục con thành công. Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --engine-success-path success --conform-success-path success --failure-path failure

Ví dụ đầu ra terminal rút gọn sau khi xử lý:

Glasswall Conform processed 3/5 files (60.00%)
Glasswall Conform failed to process 2/5 files. (40.00%)
Exceptions:
  PdfExtractionError (Total: 2)
    - 1x Unable to extract content from PDF: '/home/azureuser/input_files/corrupt_docx.docx'
    - 1x Unable to extract content from PDF: '/home/azureuser/input_files/unsupported_filetype.txt'
2024-11-06 14:28:50.242 glasswall_conform.config.logging INFO     engine_mode                   Total elapsed time: 5.55 seconds

Tái tạo tệp mà không có bảo vệ CDR

Chế độ xử lý conform_only không cung cấp khả năng bảo vệ CDR và yêu cầu một thư mục đầu vào -i, một thư mục đầu ra -o và một đường dẫn --license. Xem conform_only.

glasswall_conform conform_only -i /home/azureuser/input_files -o /home/azureuser/output_files --license /home/azureuser/gwkey.lic

Xử lý tệp trong bộ nhớ mà không đọc từ hoặc ghi ra đĩa

Các chế độ xử lý engine_memory và conform_only_memory có thể được sử dụng để xử lý tệp trong bộ nhớ mà không dùng I/O.

Nếu xử lý thành công, tệp đầu ra được mã hóa base64 sẽ được trả về qua đầu ra chuẩn. Nếu xảy ra lỗi trong quá trình xử lý, một thông báo lỗi và bản tóm tắt sau xử lý sẽ được ghi vào đầu ra lỗi chuẩn.

Ví dụ về đầu ra lỗi chuẩn cho lỗi hết thời gian chờ:

Error: Processing failed for file: 'hus11976.pdf'. Summary: {'conform_version': '0.11.2', 'operating_system': 'Windows', 'summary_verbosity': 'all', 'processing_rates': {'success': 0.0, 'failure': 100.0}, 'processing_counts': {'success': 0, 'failure': 1, 'total': 1}, 'processing_time': {'elapsed_seconds': 8.25, 'files_per_sec': 0.12, 'secs_per_file': 8.25}, 'processing_arguments': {'mode': 'engine_memory', 'library_directory': 'C:/azure/sdk.editor/2.1394.0/build-sdk-editor-windows-amd64-dev_license', 'cautious_mode': False, 'max_workers': 1, 'timeout_seconds': 5.0, 'memory_limit_gib': 11.96, 'function_name': 'protect_file', 'content_management_policy': None}, 'processing_success': [], 'processing_failure': [{'file_name': 'hus11976.pdf', 'timed_out': True, 'out_of_memory': False, 'max_memory_used_in_gib': 0.32227325439453125, 'elapsed_time': 5.0007593631744385, 'exception': 'TimeoutError()', 'success': False}]}

Ví dụ sử dụng cơ bản:

Chuyển trực tiếp một chuỗi mã hóa base64 của tệp PDF trong bộ nhớ vào glasswall_conform

echo "U29tZUJhc2U2NERhdGE=" | glasswall_conform.exe engine_memory -l "C:/azure/sdk.editor/2.1394.0" --file-name "SomeBase64Data"

Hoặc sử dụng Python thông qua subprocess

import base64
import os
import subprocess

# File in memory, for this example simply loaded from a file path
file_path = r"C:\conform\input\Set-08-016599.pdf"
with open(file_path, "rb") as f:
    file_bytes = f.read()
# Convert to base64-encoded string
encoded_file_bytes = base64.b64encode(file_bytes).decode("utf-8")

file_name = os.path.basename(file_path)
command = " ".join(
    [
        "glasswall_conform",
        "engine_memory",
        '-l "C:/azure/sdk.editor/2.1394.0"',
        f'--file-name "{file_name}"',  # Optional, used for summary and logs
        f'--summary-path "C:/conform/summary_{file_name}.json"',  # Optional
        '--watermark "Processed for security: Visual elements may vary"',  # Optional
    ]
)
# Run Conform with the base64-encoded string as an input
result = subprocess.run(command, input=encoded_file_bytes, text=True, capture_output=True, shell=True)

if result.stderr:
    # Conform failed, handle error gracefully here
    print(result.stderr)
else:
    # Conform succeeded, convert the conformed file from base64 to bytes
    conformed_file_bytes = base64.b64decode(result.stdout)
    # Do something with the conformed file bytes, e.g. write to a file
    with open("conformed_file.pdf", "wb") as f:
        f.write(conformed_file_bytes)

Tương tự, chế độ conform_only_memory có thể được sử dụng bằng cách thay engine_memory trong các ví dụ ở trên, bỏ đối số -l và chỉ định --license vì tham số này là bắt buộc cho chế độ này.

Chế độ nhanh và chế độ thận trọng

Chế độ nhanh là chế độ xử lý mặc định trong Conform. Chế độ này mang lại tốc độ xử lý nhanh nhất và chất lượng hiển thị tốt nhất cho các tệp PDF, nhưng có thể không phù hợp với các tình huống yêu cầu tuân thủ rất nghiêm ngặt các đặc tả PDF.

Nếu chế độ nhanh bị tắt hoặc không thể xử lý một tệp, Conform sẽ tự động chuyển sang chế độ thận trọng. Chế độ này ưu tiên tính tuân thủ và giảm thiểu rủi ro bằng cách thay thế các phông chữ nhúng, giúp giảm các vấn đề liên quan đến phông chữ tùy chỉnh hoặc không xác định. Chế độ thận trọng có thể làm giảm độ trung thực hiển thị, chẳng hạn như hình ảnh bị giảm chất lượng hoặc bị thiếu, kích thước phông chữ không nhất quán hoặc thiếu văn bản.

Chỉ nên tắt fast mode khi việc tuân thủ rất nghiêm ngặt các tiêu chuẩn PDF là điều thiết yếu, ngay cả khi phải đánh đổi độ trung thực hiển thị.
Chỉ nên tắt cautious mode khi việc giữ lại phông chữ nhúng là điều thiết yếu, hoặc khi hình thức hiển thị quan trọng hơn việc Conform có thể xử lý thành công phạm vi PDF rộng hơn.

Có thể tắt fast mode bằng đối số dòng lệnh tùy chọn --disable-fast-mode. Có thể tắt cautious mode bằng đối số dòng lệnh tùy chọn --disable-cautious-mode.

Khi Conform xử lý tệp thành công bằng fast mode:

Tốc độ xử lý nhanh nhất.
Hiển thị trực quan tốt nhất.
Các phông chữ nhúng tùy chỉnh không được thay thế.
Có thể không phù hợp với các trường hợp yêu cầu tuân thủ rất nghiêm ngặt các tiêu chuẩn PDF.

Khi Conform sử dụng cơ chế dự phòng cautious mode:

Tốc độ xử lý chậm hơn.
In a small number of cases, may result in reduced visual appearance, such as:
- Hình ảnh và đồ họa bị suy giảm chất lượng hoặc bị thiếu.
- Có sự khác biệt về hình thức hiển thị văn bản (ví dụ: kích thước, kiểu phông chữ hoặc khoảng cách).
- Thiếu văn bản khi đang sử dụng các phông chữ nhúng không xác định.
Xử lý PDF với mức độ tuân thủ đặc tả nghiêm ngặt hơn.
Thay thế các phông chữ nhúng tùy chỉnh bằng các phông chữ an toàn đã biết.

Chức năng của Glasswall Python Wrapper

Trong chế độ xử lý engine, hàm protect_file từ Glasswall Python Wrapper được sử dụng mặc định để xử lý tệp bằng Embedded Engine. Có thể thay đổi điều này bằng đối số dòng lệnh tùy chọn -f.

Một policy quản lý nội dung sanitise mặc định sẽ được áp dụng nếu không chỉ định tệp policy bằng đối số dòng lệnh tùy chọn -c.

Đối số dòng lệnh bắt buộc -l phải trỏ tới một thư mục chứa Embedded Engine.

Các đối số sau liên quan đến Glasswall Python Wrapper:

  -l LIBRARY_DIRECTORY, --library-directory LIBRARY_DIRECTORY
                        Required. Path to directory containing the Embedded Engine.
  -f FUNCTION_NAME, --function-name FUNCTION_NAME
                        Optional. Glasswall Python Wrapper function name to call during multiprocessing, such as 'protect_file' or 'export_file'. Default: 'protect_file'.
  -c CONTENT_MANAGEMENT_POLICY, --content-management-policy CONTENT_MANAGEMENT_POLICY
                        Optional. Path to Embedded Engine content management policy file. If not provided, the default 'sanitise' policy is used.
  --log-level-console-wrapper {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing Glasswall Python Wrapper logs to console. Default INFO.

Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 -f protect_file -c /home/azureuser/glasswall/config.xml

Đa xử lý

Tất cả các chế độ xử lý đều tận dụng GlasswallProcessManager của Glasswall Python Wrapper để xử lý tệp đồng thời một cách hiệu quả.

Các đối số sau liên quan đến đa xử lý:

  -w MAX_WORKERS, --max-workers MAX_WORKERS
                        Optional. Maximum workers for multiprocessing, 0=auto. Default: 0.
  -t TIMEOUT_SECONDS, --timeout-seconds TIMEOUT_SECONDS
                        Optional. Multiprocessing timeout per file in seconds. Default: 180.
  -m MEMORY_LIMIT_GIB, --memory-limit-gib MEMORY_LIMIT_GIB
                        Optional. Multiprocessing memory limit per file in GiB, 0=auto (4GiB min, worker distributed max). Default: 0.

Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 -t 300 -m 12

Ghi log

Mức ghi nhật ký mặc định cho Conform và Glasswall Python Wrapper là INFO. Các đối số sau liên quan đến ghi nhật ký:

  --log-level-console {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing logs to console. Default INFO.
  --log-level-file {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing logs to file. If not provided, logs will not be written to file.
  --log-path LOG_PATH   Optional. Path to output log file. Default is a timestamp-named file located at: '%TEMP%/glasswall_conform/logs'.
  --log-level-console-wrapper {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing Glasswall Python Wrapper logs to console. Default INFO.

Để hạn chế hầu hết nhật ký:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --log-level-console CRITICAL --log-level-console-wrapper CRITICAL

Tùy chỉnh tỷ lệ xử lý nội dung

Phần này chỉ áp dụng khi chế độ nhanh bị tắt.

Theo mặc định, Conform tạo tệp đầu ra bất cứ khi nào có thể, ngay cả khi chỉ một phần nội dung của tài liệu gốc đã được xử lý thành công. Hành vi này có thể không phải lúc nào cũng mong muốn và có thể được tùy chỉnh cho các loại nội dung khác nhau trong mỗi tài liệu.

Conform sử dụng "ước đoán tốt nhất" khi xử lý nội dung văn bản bị lỗi định dạng, hỏng hoặc không được hỗ trợ để đảm bảo rằng càng nhiều văn bản càng tốt được chuyển từ tài liệu gốc sang tài liệu đã được conform. Ví dụ: nếu màu nét của văn bản bị lỗi định dạng hoặc ở định dạng màu không được hỗ trợ, văn bản vẫn được giữ lại trong tài liệu đầu ra, với màu nét mặc định là màu đen.

Cách tiếp cận "ước đoán tốt nhất" này có thể dẫn đến văn bản trông tương tự bản gốc hoặc trong một số trường hợp là văn bản không hiển thị nhưng vẫn tồn tại trong tài liệu đầu ra. Vì chúng tôi không thể đảm bảo rằng ước đoán tốt nhất của mình sẽ xử lý văn bản theo cùng cách như trong tài liệu gốc, tỷ lệ xử lý phản ánh điều này dưới dạng nội dung chưa được xử lý đầy đủ. Do đó, tỷ lệ xử lý thấp đối với văn bản không phải lúc nào cũng cho thấy tài liệu sẽ trông khác biệt về mặt hiển thị khi áp dụng các ước đoán tốt nhất.

Có ba đối số để đặt tỷ lệ thành công tối thiểu khi xử lý nội dung:

  --text-min-success-rate TEXT_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing text. Default: 0.0.
  --image-min-success-rate IMAGE_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing images. Default: 0.0.
  --graphic-min-success-rate GRAPHIC_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing graphics. Default: 0.0.

Nếu không đạt giá trị tỷ lệ xử lý nội dung tối thiểu thì quá trình xử lý đối với tệp đó sẽ được coi là thất bại và tệp đầu ra sẽ không được ghi.

Đóng dấu bản quyền

Tính năng đóng dấu bản quyền bị tắt theo mặc định, nhưng có thể được bật bằng đối số --watermark. Văn bản sẽ được thêm với cỡ chữ 12 bằng màu xám đậm bán trong suốt. Dấu bản quyền thường được đặt ở góc trên bên phải của tài liệu, tuy nhiên tùy thuộc vào góc xoay đã được áp dụng cho trang, hướng có thể khác nhau. Độ dài văn bản tối đa cho một dấu bản quyền hiện là 256 ký tự.

  --watermark WATERMARK
                        Optional. Adds a watermark to each page of the reconstructed document. Default '' (disabled).

Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --watermark "Glasswall Conform"

Ẩn CID

Phần này chỉ áp dụng khi chế độ nhanh bị tắt.

Trong PDF, một số phông chữ sử dụng một hệ thống gọi là CID (Character Identifier) để quản lý các tập ký tự lớn. Khi tạo một PDF mới, nếu công cụ gặp các ký tự không thể xử lý, công cụ sẽ thay thế chúng bằng ký tự dấu hỏi mặc định (?). Bạn có thể điều chỉnh cách các CID không thể xử lý được biểu diễn trong PDF của mình bằng đối số --suppress-cid:

  --suppress-cid SUPPRESS_CID
                        Optional. Replace CID metadata that may be printed to the visual layer due to font array omissions with the supplied string, with placeholder text.
                        Glasswall Conform restricts the processing of PDFs to only known secure fonts. This is a deliberate security feature to make the PDF conform safely. Default '■'.

Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --suppress-cid "?"

Thay thế phông chữ

Phần này chỉ áp dụng khi chế độ nhanh bị tắt.

Conform hỗ trợ các biến thể đậm, nghiêng và đậm nghiêng của 14 phông chữ Type1 cơ sở và phông chữ Cambria. Conform cũng hỗ trợ một số phông chữ tùy chỉnh.

14 phông chữ Type1 cơ sở là:

Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
Symbol
ZapfDingbats

Các phông chữ nhúng không được hỗ trợ có thể được thay thế bằng phông chữ Cambria. Nếu Cambria không hỗ trợ một glyph từ phông chữ nhúng, ký tự đó sẽ bị ẩn. Để biết thêm thông tin về việc này, xem Ẩn CID.

Theo mặc định, một số phông chữ sans serif thường được nhúng sẽ được thay thế bằng Helvetica thay vì Cambria để có sự tương đồng về mặt hiển thị. Tính năng này và các tính năng thay thế phông chữ khác có thể được sửa đổi bằng các đối số sau:

  --disable-base-14-fonts
                        Optional. Disable matching embedded fonts to base 14 fonts.
                        This will result in more fonts being replaced by the fallback font, Cambria. Default False.
  --disable-custom-fonts
                        Optional. Disable matching embedded fonts to custom fonts.
                        This will result in lower support for custom embedded fonts, and more fonts being replaced by the fallback font, Cambria. Default False.
  --disable-sans-serif-replacement
                        Optional. Disable replacing some sans serif fonts with Helvetica instead of the fallback font, Cambria.
                        This will result in some replaced sans serif fonts looking more visually different when compared to the original file. Default False.

Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --disable-custom-fonts

Lọc bao gồm và loại trừ tệp

Conform cho phép kiểm soát bổ sung đối với những tệp nào trong thư mục đầu vào sẽ được xử lý bằng cách sử dụng bộ lọc bao gồm và loại trừ. Các bộ lọc này cho phép bạn chỉ định những tệp cần xử lý hoặc bỏ qua bằng ký tự đại diện kiểu Unix shell cơ bản trực tiếp từ dòng lệnh. Nếu một tệp khớp với cả quy tắc bao gồm và quy tắc loại trừ, tệp đó sẽ bị loại trừ.

Theo mặc định, nếu bỏ qua các đối số --include-files và --exclude-files, Conform sẽ xử lý tất cả các tệp có trong thư mục đầu vào.

Các đối số sau liên quan đến việc bao gồm và loại trừ tệp:

  --include-files INCLUDE_FILES
                        Optional. Can be either a path to a file containing file paths/patterns or a semicolon-separated list of patterns (e.g. '*.pdf;*/SET_03/*'). Only matching files will be processed.   
                        If None, all files are included. Default: None.
  --exclude-files EXCLUDE_FILES
                        Optional. Can be either a path to a file containing file paths/patterns or a semicolon-separated list of patterns. Any matching files will be excluded from processing. If None, no   
                        files are excluded. Default: None.

Bảng sau minh họa ví dụ về một số mẫu có thể được sử dụng:

Mẫu	Ý nghĩa	Ví dụ	Khớp	Không khớp
`*`	Khớp với mọi thứ	`*.pdf`	`file.pdf`, `report.pdf`	`file.docx`
`?`	Khớp với bất kỳ ký tự đơn nào	`file_?.pdf`	`file_1.pdf`, `file_A.pdf`	`file_10.pdf`
`[seq]`	Khớp với bất kỳ ký tự nào trong `seq`	`file_[AB].pdf`	`file_A.pdf`, `file_B.pdf`	`file_C.pdf`
`[!seq]`	Khớp với bất kỳ ký tự nào không có trong `seq`	`file_[!AB].pdf`	`file_C.pdf`, `file_D.pdf`	`file_A.pdf`, `file_B.pdf`

Các lưu ý về phân biệt chữ hoa chữ thường

Tên tệp phân biệt chữ hoa chữ thường trên Linux nhưng không phân biệt chữ hoa chữ thường trên Windows. Điều này ảnh hưởng đến cách đường dẫn tệp hoặc mẫu được diễn giải trên các hệ điều hành khác nhau.

Trên Linux, report.pdf và Report.pdf được coi là các tệp khác nhau.
Trên Windows, cả hai được coi là cùng một tệp.

Khuyến nghị: Để đảm bảo tính nhất quán trên các nền tảng, hãy sử dụng cách viết hoa/thường nhất quán trong tên tệp và mẫu. Nếu làm việc trên nhiều môi trường, hãy cân nhắc sử dụng mẫu ký tự đại diện (*) khi phù hợp để tránh không khớp.

Xử lý việc bao gồm một tệp đơn

Nếu chỉ định một tệp duy nhất bằng --include-files, hãy lưu ý rằng Conform trước tiên sẽ kiểm tra xem giá trị được cung cấp có phải là một tệp trên đĩa hay không, và nếu không phải thì giá trị đó sẽ được coi là một mẫu.

Vấn đề tiềm ẩn: Nếu người dùng chỉ định:

--include-files "/home/azureuser/input_files/first.pdf"

Conform sẽ nhận thấy rằng /home/azureuser/input_files/first.pdf tồn tại dưới dạng một tệp và sẽ cố đọc từ đó như một tệp danh sách chứa nhiều đường dẫn hoặc mẫu.

Giải pháp: Để chỉ rõ rằng đây là một mẫu cho một tệp duy nhất, hãy thêm dấu chấm phẩy ở cuối:

--include-files "/home/azureuser/input_files/first.pdf;"

Điều này đảm bảo rằng Conform xử lý đường dẫn đó như một mẫu thay vì một tệp danh sách.

Bao gồm các tệp PDF cụ thể

Để chỉ xử lý các tệp PDF có chứa "report" trong tên tệp:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "*report*.pdf"

Kết quả: Chỉ các tệp như annual_report.pdf, summary_report_2023.pdf, v.v. được xử lý.

Loại trừ các tệp PDF cụ thể

Để xử lý tất cả các tệp PDF ngoại trừ những tệp có chứa "draft" trong tên:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --exclude-files "*draft*.pdf"

Kết quả: Tất cả các tệp PDF đều được xử lý, ngoại trừ các tệp như proposal_draft.pdf và internal_draft_v2.pdf.

Loại trừ toàn bộ một thư mục

Để loại trừ tất cả tệp bên trong /home/azureuser/input_files/archive/:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --exclude-files "*/archive/*"

Kết quả: Mọi thứ bên trong /home/azureuser/input_files/archive/ đều bị bỏ qua.

Kết hợp include và exclude

Nếu một tệp khớp với cả quy tắc include và exclude, tệp đó sẽ bị loại trừ.

Để xử lý tất cả tệp từ SET_03, nhưng loại trừ các tệp chứa "error_log":

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "*/SET_03/*" --exclude-files "*error_log*"

Kết quả: Chỉ các tệp từ SET_03/ được xử lý, ngoại trừ bất kỳ tệp nào có chứa "error_log" trong tên tệp.

Sử dụng tệp cho danh sách lớn

Đối với việc lọc phức tạp hơn, bạn có thể cung cấp một tệp chứa nhiều mẫu hoặc đường dẫn tệp tuyệt đối thay vì chỉ định trực tiếp chúng.

Ví dụ sử dụng tệp danh sách include:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "include_list.txt"

Ví dụ về include_list.txt:

*/SET_03/*.pdf
*reports_2023_*.pdf
/home/azureuser/input_files/SET_02/splat.pdf

Kết quả: Chỉ xử lý các tệp từ SET_03/, các tệp chứa reports_2023_, và tệp cụ thể /home/azureuser/input_files/SET_02/splat.pdf.

Cấu trúc tệp đầu ra và phân loại

Cấu trúc thư mục cho các tệp đầu ra có thể được tùy chỉnh cho cả chế độ xử lý engine và conform_only bằng đối số dòng lệnh --output-structure.

  --output-structure {categorised,mirrored}
                        Optional. Defines the directory structure of output files. 'categorised' organises output files into subdirectories based on processing status ('engine_success', 'conform_success', 'failure').
                        'mirrored' places successfully processed output files directly in the output directory, maintaining the original input directory structure, and failed files will not be copied. Default: categorised.   

Nếu bỏ qua, cấu trúc mặc định categorised sẽ được sử dụng. Có thêm các tùy chọn để tùy chỉnh tên các thư mục con theo danh mục:

--engine-success-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp đã được xử lý thành công bởi Embedded Engine mà không cần Conform tái tạo. Mặc định là 01_engine_success
--conform-success-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp ban đầu không thể được xử lý bởi Embedded Engine, nhưng đã được Conform tái tạo và sau đó được Embedded Engine xử lý thành công. Mặc định là 02_conform_engine_success
--failure-path: Tùy chọn. Tên thư mục con đầu ra cho các tệp không thể được xử lý bằng cả Embedded Engine và Conform. Mặc định là 03_failure

Ví dụ về cấu trúc đầu ra `categorised`

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0

Thư mục đầu vào ví dụ:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

Thư mục đầu ra ví dụ sau khi xử lý:

/home/azureuser/output_files
├───01_engine_success
│       conforming_docx.docx
│       conforming_pdf.pdf
│
├───02_conform_engine_success
│       nonconforming_pdf.pdf
│
└───03_failure
        corrupt_docx.docx
        unsupported_filetype.txt

Khi sử dụng cấu trúc đầu ra categorised, nếu muốn tất cả các tệp đã được bảo vệ thành công được ghi vào cùng một thư mục đầu ra, bất kể Conform có được dùng để tái tạo tệp hay không, bạn có thể chỉ định ghi các tệp vào cùng một đường dẫn thư mục con thành công. Ví dụ:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --engine-success-path success --conform-success-path success --failure-path failure

Ví dụ về cấu trúc đầu ra `mirrored`

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --output-structure mirrored

Thư mục đầu vào ví dụ:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

Thư mục đầu ra ví dụ sau khi xử lý:

/home/azureuser/output_files
    conforming_docx.docx
    conforming_pdf.pdf
    nonconforming_pdf.pdf

Tóm tắt sau xử lý

Theo mặc định, một bản tóm tắt sẽ được ghi sau khi Conform hoàn tất xử lý các tệp. Bản tóm tắt cung cấp thông tin chi tiết như trạng thái trả về, thời gian xử lý và mức sử dụng bộ nhớ cho từng tệp. Đối số --summary-verbosity kiểm soát những tệp nào được đưa vào bản tóm tắt. Thiết lập này độc lập với mức ghi log và không ảnh hưởng đến đầu ra log chi tiết.

Các tùy chọn khả dụng

all (mặc định) - Bao gồm cả các tệp được xử lý thành công và các tệp thất bại.
failure - Chỉ bao gồm các tệp thất bại.
success - Chỉ bao gồm các tệp được xử lý thành công.
none - Tắt hoàn toàn đầu ra bản tóm tắt.

Đối số --summary-path có thể được dùng để ghi bản tóm tắt ra đĩa dưới dạng tệp JSON thay vì chỉ hiển thị nó trong terminal.

Ví dụ chỉ bao gồm các tệp thất bại trong đầu ra tóm tắt:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --summary-verbosity failure --summary-path /home/azureuser/conform_summary.json

Ví dụ tắt hoàn toàn đầu ra tóm tắt:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --summary-verbosity none --summary-path /home/azureuser/conform_summary.json

Ví dụ đầu ra JSON tóm tắt (Windows):

{
    "conform_version": "0.10.1",
    "operating_system": "Windows",
    "summary_verbosity": "all",
    "processing_rates": {
        "success": 50.0,
        "failure": 50.0
    },
    "processing_counts": {
        "success": 2,
        "failure": 2,
        "total": 4
    },
    "processing_time": {
        "elapsed_seconds": 43.61,
        "files_per_sec": 0.09,
        "secs_per_file": 10.9
    },
    "processing_arguments": {
        "mode": "engine",
        "input_directory": "C:\\conform\\input",
        "output_directory": "C:\\conform\\output",
        "library_directory": "C:\\azure\\sdk.editor\\2.1394.0",
        "cautious_mode": false,
        "max_workers": 3,
        "timeout_seconds": 180,
        "memory_limit_gib": 4.35,
        "function_name": "protect_file",
        "content_management_policy": null,
        "include_files": null,
        "exclude_files": null,
        "output_structure": "categorised"
    },
    "processing_success": [
        {
            "input_file": "C:\\conform\\input\\pal1.bmp",
            "output_file": "C:\\conform\\output\\01_engine_success\\pal1.bmp",
            "engine_status": "OK(0)",
            "max_memory_used_in_gib": 0.11124420166015625,
            "elapsed_time": 0.9149298667907715,
            "success": true
        },
        {
            "input_file": "C:\\conform\\input\\Set-08-016599.pdf",
            "output_file": "C:\\conform\\output\\02_conform_engine_success\\Set-08-016599.pdf",
            "engine_status": "GeneralFail(-1)",
            "engine_GW2FileErrorMsg": "[FAILURE_LOG_SEM_FONTS_0021897368] Key /FirstChar must be present in a Type 1 Font dictionary other than for standard 14. fonts.",
            "engine_conform_fast_status": "GeneralFail(-1)",
            "engine_conform_fast_GW2FileErrorMsg": "[FAILURE_LOG_SEM_FONTS_0021897368] Key /FirstChar must be present in a Type 1 Font dictionary other than for standard 14. fonts.",
            "engine_conform_cautious_status": "OK(0)",
            "max_memory_used_in_gib": 0.22198104858398438,
            "elapsed_time": 1.8940067291259766,
            "success": true
        }
    ],
    "processing_failure": [
        {
            "input_file": "C:\\conform\\input\\pal1_corrupt.bmp",
            "engine_status": "FileTypeUnknown(-7)",
            "engine_GW2FileErrorMsg": "Unable to determine file type",
            "engine_conform_fast_status": "PdfFastProcessError()",
            "engine_conform_cautious_status": "PdfExtractionError(Unable to extract content from PDF: 'C:\\conform\\input\\pal1_corrupt.bmp')",
            "exit_code": 0,
            "timed_out": false,
            "out_of_memory": false,
            "max_memory_used_in_gib": 0.13513565063476562,
            "elapsed_time": 0.8690056800842285,
            "success": false
        },
        {
            "input_file": "C:\\conform\\input\\Straw120556398.pdf",
            "timed_out": false,
            "out_of_memory": true,
            "max_memory_used_in_gib": 4.3571624755859375,
            "elapsed_time": 41.976775884628296,
            "exception": "MemoryError()",
            "success": false
        }
    ]
}

Cài đặt​

Windows​

Linux​

RPM (ví dụ: Rocky 9, Rocky 8)​

DEB (ví dụ: Ubuntu 24.04, Ubuntu 22.04)​

Thiết lập​

Linux​

Ubuntu​

Windows​

Cấp phép​

Các chế độ xử lý​

engine​

conform_only​

engine_memory​

conform_only_memory​

Kiểm thử​

Ví dụ​

Bảo vệ đầu cuối đến đầu cuối​

Tái tạo tệp mà không có bảo vệ CDR​

Xử lý tệp trong bộ nhớ mà không đọc từ hoặc ghi ra đĩa​

Chế độ nhanh và chế độ thận trọng​

Chức năng của Glasswall Python Wrapper​

Đa xử lý​

Ghi log​

Tùy chỉnh tỷ lệ xử lý nội dung​

Đóng dấu bản quyền​

Ẩn CID​

Thay thế phông chữ​

Lọc bao gồm và loại trừ tệp​

Các lưu ý về phân biệt chữ hoa chữ thường​

Xử lý việc bao gồm một tệp đơn​

Bao gồm các tệp PDF cụ thể​

Loại trừ các tệp PDF cụ thể​

Loại trừ toàn bộ một thư mục​

Kết hợp include và exclude​

Sử dụng tệp cho danh sách lớn​

Cấu trúc tệp đầu ra và phân loại​

Ví dụ về cấu trúc đầu ra categorised​

Ví dụ về cấu trúc đầu ra mirrored​

Tóm tắt sau xử lý​

Cài đặt

Windows

Linux

RPM (ví dụ: Rocky 9, Rocky 8)

DEB (ví dụ: Ubuntu 24.04, Ubuntu 22.04)

Thiết lập

Linux

Ubuntu

Windows

Cấp phép

Các chế độ xử lý

engine

conform_only

engine_memory

conform_only_memory

Kiểm thử

Ví dụ

Bảo vệ đầu cuối đến đầu cuối

Tái tạo tệp mà không có bảo vệ CDR

Xử lý tệp trong bộ nhớ mà không đọc từ hoặc ghi ra đĩa

Chế độ nhanh và chế độ thận trọng

Chức năng của Glasswall Python Wrapper

Đa xử lý

Ghi log

Tùy chỉnh tỷ lệ xử lý nội dung

Đóng dấu bản quyền

Ẩn CID

Thay thế phông chữ

Lọc bao gồm và loại trừ tệp

Các lưu ý về phân biệt chữ hoa chữ thường

Xử lý việc bao gồm một tệp đơn

Bao gồm các tệp PDF cụ thể

Loại trừ các tệp PDF cụ thể

Loại trừ toàn bộ một thư mục

Kết hợp include và exclude

Sử dụng tệp cho danh sách lớn

Cấu trúc tệp đầu ra và phân loại

Ví dụ về cấu trúc đầu ra `categorised`

Ví dụ về cấu trúc đầu ra `mirrored`

Tóm tắt sau xử lý