通过 TOS Browser 追踪文件下载行为--对象存储-火山引擎

文档中心

导航

通过 TOS Browser 追踪文件下载行为

最近更新时间：2025.04.01 14:31:33首次发布时间：2025.04.01 14:31:33

TOS Browser 提供了日志追踪功能，用于追踪文件被分享后的下载行为信息。本文介绍通过 TOS Browser 追踪文件下载行为的操作步骤。

功能介绍

您可以通过 TOS Browser 生成具有日志追踪功能的分享链接，当其他用户通过该分享链接登录 TOS Browser，并下载对应文件后，日志服务会采集通过该分享链接下载文件的行为信息。然后您可以在日志服务中对这些文件下载行为信息进行检索与分析，以此了解文件当前下载的状态。

前提条件

已开通日志服务，具体操作，请参见快速入门。

注意事项

TOS Browser 的日志追踪功能处于邀测状态，如需使用，请联系客户经理。
使用日志追踪功能，将产生日志存储、索引存储、写流量、索引流量、服务请求次数等费用，由日志服务收取。计费详情，请参见日志服务计费项。
日志服务仅会采集通过分享链接登录 TOS Browser 后下载文件行为信息，不会采集在浏览器通过分享链接下载文件的行为信息。

步骤一：创建日志主题

创建日志项目。
1. 登录日志服务控制台。
2. 在顶部导航栏中，选择日志服务所在的地域。
3. 在左侧导航栏中，选择资源管理 ＞ 日志项目。
4. 在日志项目页面，单击创建日志项目。
5. 在创建日志项目对话框，设置日志项目名称、描述、所属项目和标签。
  说明
  关于创建日志项目的详细参数说明，请参见创建日志项目。
6. 完成配置后，单击创建。
创建日志主题。
1. 在日志项目页面，单击上一步创建的日志项目的名称。
2. 在日志主题区域，单击创建日志主题。
3. 在创建日志主题对话框，设置主题名称、日志存储时长配置等参数。
  说明
  关于创建日志主题的详细参数说明，请参见创建日志主题。
4. 完成配置后，单击创建。
配置索引。
1. 在日志项目详情页面，单击上一步创建的日志主题的名称。
2. 在日志主题详情页面右上角，单击索引配置。
3. 在索引配置面板，启用索引功能，选择健值索引，配置字段名称，支持以下两种方式：
  - 手动配置字段
    单击添加字段，手动输入字段名称、字段类型，关于字段名称详细介绍，请参见日志参数说明。
  - 自动配置字段
    您可以先通过 TOS Browser 分享文件，生成下载日志，然后再配置键值索引。当下载行为触发日志生成后，日志服务中存在原始日志，此时，再在索引配置面板，单击自动配置，日志服务会通过采集到的日志数据，自动构建索引，然后单击覆盖，在弹出的对话框单击确定。
  说明
  关于键值索引的详细介绍，请参见键值索引配置。
4. 完成配置后，单击确定。
5. 在提示对话框，单击确定。

步骤二：分享文件

您可以通过 TOS Browser 或 Python SDK 生成具有日志追踪功能的分享链接。

通过 TOS Browser 分享文件

登录 TOS Browser。
在桶列表页面，单击目标桶的名称。
在文件列表页面，单击目标文件 ... ＞分享。

在分享对话框，设置 URL有效期，启用日志追踪，然后配置如下参数。

参数	说明
日志 AK	日志主题所属账号的 AccessKey ID 信息。
日志 SK	日志主题所属账号的 Secret AccessKey Key 信息。查看 AKSK 信息的具体步骤，请参见查看 AKSK 信息。注意为了防止密钥泄露产生安全问题，请严格管控对应 AK和 SK 的权限范围。
日志 Host	日志服务的访问域名。关于获取访问域名的具体操作，请参见服务地址。说明设置日志 Host 时，无需填写 `https://`，例如填写为 `tls-cn-beijing.ivolces.com`。
日志 Region	日志主题所属地域，TOS Browser 会根据您所填写的日志 Host 自动识别地域。
日志主题 ID	日志主题的 ID。您可以在日志项目详情页面日志主题名称/ID 列下获取日志主题的 ID。

单击测试发送日志。
待页面提示测试日志发送成功后，单击创建分享。
在分享对话框，复制链接，然后您可以将链接分享给其他用户，其他用户可以通过 TOS Browser 访问文件。

通过 Python SDK 分享文件

根据实际情况修改以下示例代码中的参数，然后运行以下代码，生成分享链接。

import base64
import os
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_v1_5
from urllib.parse import quote
from tos import TosClientV2
from tos.models2 import PolicySignatureCondition

# TOS配置，ak/sk在环境变量中赋值，需要先配置环境变量
TOS_CONFIG = {
    "ak": os.environ["VOLCENGINE_ACCESS_KEY_ID"],
    "sk": os.environ["VOLCENGINE_ACCESS_KEY_SECRET"],
    "endpoint": "tos-cn-beijing.volces.com",
    "region": "cn-beijing"
}

# TLS配置，ak/sk在环境变量中赋值，需要先配置环境变量
LOG_CONFIG = {
    "ak": os.environ["VOLCENGINE_ACCESS_KEY_ID"],
    "sk": os.environ["VOLCENGINE_ACCESS_KEY_SECRET"],
    "topic_id": "c1a58ff6-9439-4316-bb26-0f97f4f4****",
    "endpoint": "tls-cn-beijing.volces.com",
    "region": "cn-beijing"
}

LOG_TOKEN = f"https://{LOG_CONFIG['endpoint']}?AK={LOG_CONFIG['ak']}&SK={LOG_CONFIG['sk']}&TopicId={LOG_CONFIG['topic_id']}&Region={LOG_CONFIG['region']}"

# 假设的固定公钥
PUBLIC_KEY_BASE64 = "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUF0NVd0K29BYnlQMDJEWGZZSXZqaApzRThRY25BQnRkOHJSSVVIWHE3TmkxUmRiVjliRG4wQ0Zsb0syZVYvRzJwWjZsMHJ1NGZXYWhjWHFGMDREeTRoCkRrRWRJcHhzWlBLcVh0c01LaVNxSlZoTmpJZXVoVVZpN1dSeUJtWWk0cXU3V1k5RE5UU2dCSHYyNGtrNWR6NEYKYWVXdHcvRGJJVDdzOFJaSkc3NllxOHRRQ25TREkvd2ZLOEZwQlo3WW1WL1hUT0lFeVR4N2ZhcWdod3VzeVh1aApPQjA2aGRIUklyMTk0R0RGM1RaQ1U3NUE1cTVIcHM2UGtTQjJ3eW15ZEovWXE1SU1Dc3d6UEhEYTR4d3lxbzJuCnNUK1hHVmNYUzNmT1NhMFBIWWw4aC95RWhpR2hkNUJyVjhrWUlUS0dhNWdUenBMOUMwTWV2U3A5OGZyaWtDOGgKKzlBQjlHNXlFRjZ4YVdQR3JvRTJiWmtONzZyZUo5MXhOczZwWEdpeWI3Z1k4VndpU2tpVi8vczZ0ZmE2Y3B1bQpZQ0FsSksrakJta05hc21ZdW5aUkVET25kQ1VDYlVlZHJIUnFQcThQc0p2Vmw4T3JwdFo5U2dKRVJRaEtld2pJCnJNczA5djU4VC9aaUpGa0VLK2NaN3hEV2ZaeFBMOFdtQU1mdEhsdXlYRTdWSjREMXZBSnUzbWNHdkJLNE9DYVYKalJqT2ZTai9xU2xsUUVOc1ZRUTBSTWFJZHY5L0pyM29yZW5LTzdOUUVablhOV0tpVExaK1VqOVdETXdqdTN4YQpUdTcvODRFWFFmRDFVYUlXWlhDKzdvYlNjcmhkTDY5TDNUTmt0cFljNU4vY2JJRWtHWFZPVGhqQ0tnNzJJMkJECnlXUWV3KzJWYVVSa2ZOWmZJMTFHT3kwQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ=="
PUBLIC_KEY = base64.b64decode(PUBLIC_KEY_BASE64).decode('utf-8')

# 网站 URL
WEBSITE_URL = 'https://document-share.tos-cn-beijing.volces.com/v2/index.html'

# 分享配置
SHARECONFIG = {
    "bucket": "bucket-demo",   
    "conditions":
        {
            "key": "key",
            "value": "prefix/",
            "operator": "starts-with"
        },
    "expires": 3600
}


# 加密方法
def encrypt_data(data):
    key = RSA.import_key(PUBLIC_KEY)
    cipher = PKCS1_v1_5.new(key)
    encrypted = cipher.encrypt(data.encode('utf-8'))
    res = base64.b64encode(encrypted).decode('utf-8')
    return res


# 编码方法
def encode(data):
    return base64.b64encode(data.encode('utf-8')).decode('utf-8')


if __name__ == '__main__':
    # 创建客户端
    client = TosClientV2(
        ak=TOS_CONFIG["ak"],
        sk=TOS_CONFIG["sk"],
        region=TOS_CONFIG["region"],
        endpoint=TOS_CONFIG["endpoint"]
    )

    # 生成预签名策略 URL
    res = client.pre_signed_policy_url(bucket=SHARECONFIG["bucket"],
                                       conditions=[PolicySignatureCondition(key=SHARECONFIG["conditions"]["key"],
                                                                            value=SHARECONFIG["conditions"]["value"],
                                                                            operator=SHARECONFIG["conditions"][
                                                                                "operator"])],
                                       expires=SHARECONFIG["expires"])
    url = res.get_signed_url_for_list()

    # 生成分享URL
    share_url = f"{WEBSITE_URL}?token={encode(url)}"
    if LOG_TOKEN:
        share_url += f"&logToken={quote(encrypt_data(LOG_TOKEN))}"

    print('share_url:', share_url)

以下参数需要根据您的实际情况进行配置：

参数		说明
TOS_CONFIG	ak	存储桶所属火山引擎账号的 AccessKey ID、Secret AccessKey Key 信息，查看 AK、SK 信息的具体步骤，请参见查看 AKSK 信息。运行示例代码时，默认从环境变量中获取 AK、SK 信息，因此您需要在环境变量中配置 AK、SK，具体操作，请参见配置长期访问凭证。
	sk
	endpoint	TOS 的访问域名，详细介绍，请参见地域和访问域名（Endpoint）。
	region	存储桶所属地域，详细介绍，请参见地域和访问域名（Endpoint）。
LOG_CONFIG	ak	日志主题所属火山引擎账号的 AccessKey ID、Secret AccessKey Key 信息，查看 AK、SK 信息的具体步骤，请参见查看 AKSK 信息。运行示例代码时，默认从环境变量中获取 AK、SK 信息，因此您需要在环境变量中配置 AK、SK，具体操作，请参见配置长期访问凭证。
	sk
	topic_id	日志主题的 ID。您可以在日志项目详情页面日志主题名称/ID 列下获取日志主题的 ID。
	endpoint	日志服务的访问域名。关于获取访问域名的具体操作，请参见服务地址。
	region	日志服务的地域。
SHARECONFIG	bucket	存储桶的名称。
	value	被分享的文件名称。
	expires	过期时间，单位为秒。

步骤三：下载文件

在 TOS Browser 生成带有日志追踪功能的分享链接后，其他用户可以通过该分享链接登录 TOS Browser，并下载对应文件。具体操作，请参见使用分享链接登录 TOS Browser。

注意

通过带有日志追踪的分享链接登录 TOS Browser 时，TOS Browser 的版本需为 V 1.10.3 及以上，低版本不支持该登录方式。

步骤四：检索下载日志

通过分享链接下载文件后，您可以通过日志服务控制台或 Python SDK 检索对应下载日志。

日志参数说明

日志服务会采集 browserVersion、bucketName 等参数，具体参数说明如下：

参数	字段类型	说明
browserVersion	text	TOS Browser 的版本。
bucketName	text	存储桶的名称。
category	text	日志类别。
failedReason	text	日志服务采集下载日志失败的原因。
fileName	text	文件名称。
fileSize	long	文件大小，单位：Byte。
logAK	text	日志主题所属火山引擎账号的 AccessKey ID。
originShareUrl	text	分享链接。
system	text	客户端所使用的操作系统。
taskStatus	text	任务状态。
updateTime	text	日志采集的时间。
downloadSize	long	文件实际下载的大小，单位：Byte。

通过日志服务检索下载日志

登录日志服务控制台。
在顶部导航栏中，选择日志服务所在的地域。
在左侧导航栏中，选择资源管理 ＞ 日志项目。
在日志项目页面，单击目标日志项目的名称。
在日志主题区域，单击目标日志主题的名称。
在检索分析区域输入* | Select fileName,taskStatus,updateTime Where originShareUrl='<分享链接>' order by updateTime，然后单击搜索。
查询语句示例如下：
```
* | Select fileName,taskStatus,updateTime Where originShareUrl='https://document-share.tos-cn-beijing.volces.com/v2/index.html?token=****&logToken=****' order by updateTime
```
在原始日志区域会展示搜索到的对应日志。

通过 Python SDK 检索下载日志

根据实际情况修改以下示例代码中的参数，然后运行以下代码，检索下载日志。

# coding=utf-8
import os
from volcengine.tls.TLSService import TLSService
from volcengine.tls.tls_requests import *

if __name__ == "__main__":
    # 初始化客户端，推荐通过环境变量动态获取火山引擎密钥等身份认证信息，以免 AccessKey 硬编码引发数据安全风险。详细说明请参考 https://www.volcengine.com/docs/6470/1166455
    # 使用 STS 时，ak 和 sk 均使用临时密钥，且设置 VOLCENGINE_TOKEN；不使用 STS 时，VOLCENGINE_TOKEN 部分传空
    endpoint = "tls-cn-beijing.volces.com"
    region = "cn-beijing"
    access_key_id = os.environ["VOLCENGINE_ACCESS_KEY_ID"]
    access_key_secret = os.environ["VOLCENGINE_ACCESS_KEY_SECRET"]
    topic_id = "c1a58ff6-9439-4316-bb26-0f97f4f4****"
    org_share_url = "https://document-share.tos-cn-beijing.volces.com/v2/index.html?token=****&logToken=****"
    query_sql = f"* | Select fileName,taskStatus,updateTime Where originShareUrl='{org_share_url}' order by updateTime"
    query_range_seconds = 3600
    end_time = int(time.time() * 1000)
    start_time = int((time.time() - query_range_seconds) * 1000)
    limit = 1000

    # 实例化 TLS 客户端
    tls_service = TLSService(endpoint, access_key_id, access_key_secret, region)

    # 查询日志数据（SQL分析）
    search_logs_request = SearchLogsRequest(topic_id, query=query_sql, limit=limit,
                                            start_time=start_time, end_time=end_time)
    search_logs_response = tls_service.search_logs_v2(search_logs_request)
    print(json.dumps(search_logs_response.response.get("AnalysisResult").get("Data"), indent=4, ensure_ascii=False))

以下参数需要根据您的实际情况进行配置：

参数	说明
endpoint	日志服务的访问域名。关于获取访问域名的具体操作，请参见服务地址。
region	日志服务的地域。
access_key_id	日志主题所属火山引擎账号的 AccessKey ID、Secret AccessKey Key 信息，查看 AK、SK 信息的具体步骤，请参见查看 AKSK 信息。运行示例代码时，默认从环境变量中获取 AK、SK 信息，因此您需要在环境变量中配置 AK、SK，具体操作，请参见配置长期访问凭证。
access_key_secret
topic_id	日志主题的 ID。您可以在日志项目详情页面日志主题名称/ID 列下获取日志主题的 ID。
org_share_url	携带日志追踪信息的分享链接。
query_range_seconds	日志检索的时间范围，单位为秒。
limit	检索到的日志条目上限。