byted-tos-doc-process

Volcengine TOS ドキュメント処理

Volcengine TOS に保存されたオフィスドキュメントをプレビューして変換します。PDF／PNG／JPG への変換、ページ数の取得、HTML プレビュー URL の取得、ページ範囲のエクスポートに対応しています。

セットアップ（環境ごとに初回のみ）

初回利用時に依存関係をインストールします。

cd {baseDir}
pip install -r {baseDir}/requirements.txt

次に、Python 3.7 以降でスクリプトを実行します。

python3 {baseDir}/scripts/<script>.py <args>

tos の ModuleNotFoundError が表示された場合は、依存関係を再インストールしてください。

環境変数

このスキルでは、metadata ブロックで宣言された TOS ID を使用します。一般的な実行時変数は次のとおりです。

環境変数	必須	説明
TOS_ACCESS_KEY	はい	TOS アクセスキー ID
TOS_SECRET_KEY	はい	TOS シークレットアクセスキー
TOS_ENDPOINT	はい	TOS エンドポイント URL
TOS_REGION	はい	TOS リージョン
TOS_BUCKET	はい	ドキュメントを保存するソースバケット
TOS_OBJECT_KEY	いいえ	ドキュメントのソースオブジェクトキー。--key で上書きできます
TOS_SECURITY_TOKEN	いいえ	一時的な認証情報を使用する場合の STS セッショントークン

クイックスタート（一般的なタスク）

# Convert document to PDF
python3 {baseDir}/scripts/doc_preview_pdf.py --key report.docx --output preview.pdf

# Preview page 2 as PNG
python3 {baseDir}/scripts/doc_preview_png.py --key report.docx --page 2 --output page_2.png

# Preview page 2 as JPG
python3 {baseDir}/scripts/doc_preview_jpg.py --key report.docx --page 2 --output page_2.jpg

# Get total page count
python3 {baseDir}/scripts/doc_total_page.py --key report.docx --dest-type pdf

# Resolve HTML preview URL
python3 {baseDir}/scripts/doc_preview_html_url.py --key report.docx

# Batch export page range to TOS
python3 {baseDir}/scripts/doc_preview_process.py --key report.docx \
  --dest-type jpg --img-mode 1 --start-page 1 --end-page 3 \
  --saveas-bucket "output-bucket" --saveas-object "export/page_{Page}.jpg"

# Batch screenshot a PDF page range
python3 {baseDir}/scripts/doc_batch_screenshot.py --key test.pdf \
  --format png --start-page 1 --end-page 3 \
  --saveas-object "skill-test/doc/{Page}.png"

利用可能なスクリプト

スクリプト	目的
scripts/doc_preview_pdf.py	ドキュメントを PDF に変換してローカルに保存します。
scripts/doc_preview_png.py	単一ページを PNG としてレンダリングします。
scripts/doc_preview_jpg.py	単一ページを JPG としてレンダリングします。
scripts/doc_total_page.py	x-tos-total-page ヘッダーから総ページ数を読み取ります。
scripts/doc_preview_html_url.py	最終的な HTML プレビュー URL を解決します（リダイレクトをたどり、トークンを抽出します）。
scripts/doc_preview_process.py	パラメーターを完全に制御できる汎用のドキュメントプレビューです。TOS から TOS へのエクスポートにも対応しています。
scripts/doc_preview_params.py	x-tos-doc-* クエリパラメーターを一貫して構築するためのヘルパーライブラリです。
scripts/doc_batch_screenshot.py	ドキュメントプレビューのバッチモードで PDF ページを画像として一括エクスポートします。

すべてのスクリプトで、--key を指定して TOS_OBJECT_KEY を上書きできます。構造化出力に対応するスクリプトでは、機械可読な出力を得るために --json も使用できます。また、doc_preview_process.py と doc_total_page.py では、解決されたリクエストをプレビューするために --dry-run を使用できます。各スクリプトに -h を指定すると、使用方法の全容を確認できます。

対象外

• ドキュメントの内容の編集（このスキルは読み取り専用のプレビュー／変換です）。
• ドキュメントプレビューに関連しない一般的なオブジェクトストレージタスク。
• TOS を使用しないローカルのオフィスドキュメント変換ワークフロー。

ルール

• 認証：認証には、上記の metadata ブロックで宣言された TOS ID を使用します。各スクリプトで --key を指定すると、対象オブジェクトを上書きできます。
• 署名付き URL のパターン：ドキュメントプレビューでは、get_object の直接的な process キーワードではなく、x-tos-process=doc-preview と x-tos-doc-* クエリパラメーターを含む署名付き URL を使用します。パラメーターを一貫して構築するには、doc_preview_params.py を使用してください。
• 一括スクリーンショットの制約：doc_batch_screenshot.py では現在、ソースオブジェクトが PDF である必要があり、結果は {Page} プレースホルダーを使用して TOS に保存されます。
• 保存先のエンコード：doc-preview クエリベースの保存先指定では、バックエンドの要件に合わせて、ヘルパースクリプトが x-tos-save-bucket と x-tos-save-object を自動的に URL セーフな Base64 形式でエンコードします。
• カスタムドメインに関する注意：2024 年 1 月 3 日以降に作成されたバケットでは、オンライン HTML プレビューにデフォルトの TOS ドメインではなく、カスタムドメインが必要な場合があります。
• パラメーターの正確な情報源：doc-preview パラメーターの全容については、Volcengine TOS の公式ドキュメントが正確な情報源です。不明な点がある場合は、REFERENCE.md を確認してください。
• 言語：ユーザーの希望する言語で返信してください。

関連情報

• セットアップと環境：README.md
• パラメーターリファレンス：REFERENCE.md
• エンドツーエンドのワークフロー：WORKFLOWS.md