Bytedance TOS 文档处理技能

该技能通过doc-preview功能，为Bytedance TOS中的文件提供文档处理功能，实现方式为使用火山引擎TOS SDK生成预签名URL。

注意：之所以采用此方法，是因为SDK的getobject方法不直接支持doc*关键字参数。所有文档处理参数必须作为查询参数传递到预签名URL中。

快速开始

1. 客户端初始化

python
import os
import tos
from tos.enum import HttpMethodType
from urllib.request import urlopen

def create_client() -> tos.TosClientV2:
从环境变量初始化TosClientV2。
try:
# ...（完整实现在脚本中）
return tos.TosClientV2(
ak=os.getenv(TOSACCESSKEY),
sk=os.getenv(TOSSECRETKEY),
endpoint=os.getenv(TOS_ENDPOINT),
region=os.getenv(TOS_REGION),
securitytoken=os.getenv(TOSSECURITY_TOKEN),
)
except Exception as e:
print(f初始化客户端时出错：{e})
return None

client = create_client()

2. 基本工作流程（预签名URL）

python

（假设client已初始化，bucketname和objectkey已设置）

1. 将文档预览为PDF并保存到本地

try: # 构建doc-preview的查询参数 pdf_params = { x-tos-process: doc-preview, x-tos-doc-dst-type: pdf } presignedpdf = client.presigned_url( HttpMethodType.HttpMethodGet, bucket_name, object_key, query=pdf_params )

# 从预签名URL下载内容
with urlopen(presignedpdf.signedurl) as response, open(localpreview.pdf, wb) as fout:
f_out.write(response.read())
print(PDF预览已保存到local_preview.pdf)

except Exception as e:
print(f转换为PDF时出错：{e})

2. 将第3页预览为PNG图片

try: png_params = { x-tos-process: doc-preview, x-tos-doc-dst-type: png, x-tos-doc-page: 3, x-tos-doc-image-dpi: 150 } presignedpng = client.presigned_url( HttpMethodType.HttpMethodGet, bucket_name, object_key, query=png_params ) with urlopen(presignedpng.signedurl) as response, open(page3.png, wb) as fout: f_out.write(response.read()) print(第3页已保存为page_3.png)

except Exception as e:
print(f转换为PNG时出错：{e})

3. 从响应头获取总页数

try: presignedhead = client.presigned_url( HttpMethodType.HttpMethodGet, bucket_name, object_key, query={x-tos-process: doc-preview, x-tos-doc-dst-type: pdf} ) with urlopen(presignedhead.signedurl) as response: total_pages = response.headers.get(x-tos-total-page) print(f文档共有{total_pages}页。) except Exception as e: print(f获取页数时出错：{e})

核心操作

所有文档处理均通过生成包含process=doc-preview及其他x-tos-doc-*参数的预签名URL来实现。

1. 转换为PDF（x-tos-doc-dst-type=pdf）

将整个文档转换为单个PDF文件。

python

参见快速开始示例

2. 转换为图片（x-tos-doc-dst-type=png 或 jpg）

将文档的特定页面转换为图片。

python

参见快速开始示例

使用查询参数如x-tos-doc-page、x-tos-doc-image-dpi等

3. 转换为HTML（x-tos-doc-dst-type=html）

获取包含最终预览URL令牌的临时HTML页面。这需要第二步来解析HTML并解码令牌。

python

步骤1：通过预签名URL获取HTML内容

html_params = {x-tos-process: doc-preview, x-tos-doc-dst-type: html}
presignedhtml = client.presignedurl(HttpMethodType.HttpMethodGet, bucketname, objectkey, query=htmlparams)

with urlopen(presignedhtml.signedurl) as response:
html_content = response.read().decode(utf-8)

步骤2：解析并解码（完整逻辑参见scripts/docpreviewhtml_url.py）

... 提取并base64解码令牌的逻辑 ...

finalurl = decodepreview_url(token)

4. 批量导出页面（image-mode=1）

将指定范围的页面作为图片直接导出到TOS存储桶。

python

使用查询参数：image-mode、start-page、end-page、x-tos-save-bucket、x-tos-save-object

batch_params = {
x-tos-process: doc-preview,
x-tos-doc-dst-type: jpg,
image-mode: 1,
start-page: 2,
end-page: 5,
x-tos-save-bucket: output-bucket,
x-tos-save-object: exported/page_{Page}.jpg # {Page} 是占位符
}
presignedbatch = client.presignedurl(HttpMethodType.HttpMethodGet, bucketname, objectkey, query=batchparams)

响应体（来自urlopen）包含批量任务的JSON元数据

授权

认证由tos.TosClientV2处理。通过环境变量提供凭证。

必需的环境变量

• - TOSACCESSKEY
• TOSSECRETKEY
• TOSENDPOINT
• TOSREGION

STS可选

• - TOSSECURITYTOKEN

最佳实践

• - 错误处理：始终使用try...except块包裹HTTP请求，以捕获HTTPError和URLError。
• 参数参考：参见REFERENCE.md了解docpreviewparams.py参数到x-tos-*查询键的映射，并参考官方TOS文档获取权威详细信息。
• HTML预览：注意两步流程以及新存储桶的自定义域名要求。
• 总页数头：x-tos-total-page头是获取页数的便捷方式。

其他资源

• - 详细参数请参见REFERENCE.md。
• 端到端示例请参见WORKFLOWS.md。
• 可执行的Python示例请参见scripts/目录。
• 所有处理参数的权威列表，请始终参考火山引擎TOS文档预览官方文档。