云点播 如何使用 URL 迁移

这篇会介绍如何使用工具快速批量拉取并上传 URL 列表。

二、获取 API 密钥

请求云 API 需要使用开发者的 API 密钥（即 SecretId 和 SecretKey）。如果还未创建过密钥，请参见 创建密钥文档 生成新的 API 密钥；如果已创建过密钥，请参见 查看密钥文档 获取 API 密钥。

三、开通云点播

请参考 快速入门 – 步骤1 开通云点播服务。

四、获取脚本

你可以 查看此处 获取脚本。

五、脚本相关文件结构

pull_upload_list/├── batch_pull_upload_api.sh # 安装云 API Python SDK的脚本├── batch_pull_upload.py # 主脚这篇件（核心实现）├── config.json # 配置文件（腾讯云API密钥）├── test_urls.txt # URL列表示例文件└── README.md # 说明文档（这篇件）

运行脚本后，生成的文件格式如下：

·pull_upload_YYYYMMDD_HHMMSS.log ：执行日志文件。

·pull_upload_result_YYYYMMDD_HHMMSS.json ：详细结果报告。

七、权限要求

·确保腾讯云 API 密钥具有云点播服务的读写权限。

·建议使用子应用 ID 进行资源隔离（subappid 配置）。

·监控 API 配额使用，避免超出调用限制。

八、性能建议

·批量大小：建议单次处理不超过1000个 URL。

·并发数调整：根据服务器性能调整 max_workers（5-20为宜）。

·限流设置：根据 API 配额调整 max_requests_per_second。

·网络环境：稳定网络环境下运行效果最佳。

九、安全注意事项

·配置文件包含敏感信息，请妥善保管。

·建议使用临时密钥或最小权限原则。

·不要在代码中硬编码密钥信息。

·定期轮换 API 密钥。

十、实践说明

1. 测试先行：先用少量 URL（1-5个）测试配置正确性。

2. 监控日志：关注日志文件中的错误和警告信息。

3. 结果验证：检查 JSON 结果文件中的成功率统计。

4. 渐进处理：大批量任务建议分批次处理。

5. 异常处理：网络不稳定时适当增加重试次数。

十一、常见问题

·URL 格式错误：确保 URL 以 http:// 或 https:// 开头。

·文件编码：URL 列表文件必须使用 UTF-8 编码。

·权限错误：检查 config.json 文件读取权限。

·超时问题：大文件拉取可能需要调整超时时间。

十三、1. 安装云 api-python-sdk

进入到脚本所在目录，执行如下命令：

bash batch_pull_upload_api.sh

十四、2. 准备 URL 列表文件

创建一个文这篇件，支持多种格式，每行一个任务，支持注释行。

格式说明：

·列分隔符：使用英文逗号 , 分隔各列。

·第1列（必需）：URL 地址，必须以 http:// 或 https:// 开头。

·第2列（可选）：MediaName 媒体名称，支持中文，留空表示使用默认名称。

·第3列（可选）：ClassId 分类 ID，数字格式，留空表示使用默认分类。

·第4列（可选）：MediaStoragePath 自定义存储路径，以/开头，只有 FileID + Path 模式的子应用可以指定存储路径。

·第5列（可选）：SourceContext 来源上下文 ，原样透传，最长 250 个字符（拉取上传完成后通过 事件通知 /回调返回）。可用于将上传后的媒体与原始 vid / 业务侧标识做对应。值不能包含逗号；若原文含逗号，请传入 base64 编码后的值（工具不做编解码）。

URL 格式要求：

·必须以 http:// 或 https:// 开头。

·支持所有有效的 HTTP/HTTPS URL 格式。

·每行只能包含一个 URL 任务。

·文件编码必须为 UTF-8（支持中文媒体名称）。

十五、示例格式1：纯 URL 格式

# 这是注释行（以#开头，会被忽略）https://example.com/video1.mp4https://example.com/video2.mp4# 空行会被自动跳过https://example.com/video3.mp4

十六、示例格式2：URL + 媒体名称格式

https://example.com/video1.mp4,我的视频1,https://example.com/video2.mp4,测试视频,

十七、示例格式3：URL + 分类 ID 格式

https://example.com/video1.mp4,,1001https://example.com/video2.mp4,,1002

十八、示例格式4：完整五列格式

https://example.com/video1.mp4,我的视频1,1001,/custom/path/video1.mp4,ctx-001https://example.com/video2.mp4,测试视频,1002,/videos/2024/test.mp4,ctx-002

十九、示例格式5：混合使用（完全支持）

# 纯URLhttps://example.com/video1.mp4# URL + 名称https://example.com/video2.mp4,视频名称,# URL + 分类IDhttps://example.com/video3.mp4,,1003# URL + 来源上下文SourceContexthttps://example.com/video3.mp4,,,,ctx-vid# 完整格式https://example.com/video4.mp4,完整视频,1004,/archive/video4.mp4,ctx-001

20、3. 准备配置文件

脚本会自动读取脚本所在目录的配置文件：config.json

配置文件示例：

{ "secret_id": "your_secret_id_here", "secret_key": "your_secret_key_here", "region": "ap-guangzhou", "subappid": 0, "tasks_priority": 0, "procedure": "", "storage_region": "ap-shanghai", "custom_path": { "use_url_path": false, "prefix": "" }}

21、4. 运行脚本

python3 batch_pull_upload.py your_url_list.txt

22、5. 查看结果

实时监控：

·控制台实时显示进度条和任务状态。

·自动记录成功/失败任务数量。

·显示重试次数和执行时间。

结果文件：

·pull_upload_YYYYMMDD_HHMMSS.log ：详细执行日志。

·pull_upload_result_YYYYMMDD_HHMMSS.json ：完整结果报告。

23、配置说明

配置验证机制：

·自动检查配置文件是否存在。

·验证 JSON 格式是否正确。

·验证所有必需字段是否存在且非空。

·验证字段类型（subappid 和 tasks_priority 必须是数字）。

·提供详细的错误提示信息。

必需配置项：

·secret_id ：腾讯云 API 密钥 ID。

·secret_key ：腾讯云 API 密钥 Key。

·region ：云点播服务区域（如：ap-guangzhou）。

·subappid ：子应用 ID（默认为"0"）。

可选配置项：

·tasks_priority ：任务优先级（可选，默认为0）。

·数值越大优先级越高。

·范围：通常为-10到10。

·示例："tasks_priority": 5 表示高优先级。

·procedure ：任务流模板名称（可选，默认为空字符串）。

·用于指定上传后的处理流程。

·需要在腾讯云控制台预先创建任务流模板。

·示例："procedure": "MyCustomProcess" 指定自定义处理流程。

·storage_region：指定上传园区（可选，默认为空字符串，即使用账号默认地域）。

·仅适用于对上传地域有特殊需求的用户，对应 PullUpload 接口的 StorageRegion 字段。

·若指定上传园区，请先在控制台 上传存储设置 中开启相应的存储地域，否则会报错 InvalidParameter.StorageRegion。

·示例："storage_region": "ap-beijing"、"ap-chongqing"、"ap-singapore" 等。

·custom_path : 自定义存储路径配置（可选）

·use_url_path：是否使用 URL 路径（默认 false）

·prefix：路径前缀（如/videos/2024）

24、自定义路径配置详解

路径组合优先级

1. 使用 URL 路径：当 use_url_path=true 时，自动提取 URL 中的路径部分，此时忽略第四列 MediaStoragePath。

2. 自定义路径：当 use_url_path=false 并提供 MediaStoragePath 时，使用用户指定的路径。

3. 路径前缀：如果配置了 prefix，会在路径前添加此前缀。若只有前缀，use_url_path=false，第四列 MediaStoragePath 为空。则为前缀+文件名。

配置示例

#示例1：使用URL路径{ "custom_path": { "use_url_path": true, "prefix": "/videos" }}#URL：https://example.com/path/to/video.mp4 最终路径：/videos/path/to/video.mp4#示例2：自定义路径{ "custom_path": { "use_url_path": false, "prefix": "/archive" }}#URL列表：https://example.com/video.mp4,,,/custom/path/video.mp4 最终路径：/archive/custom/path/video.mp4示例3：仅使用前缀{ "custom_path": { "use_url_path": false, "prefix": "/uploads" }}#URL列表：https://example.com/video.mp4 最终路径：/uploads/video.mp4

25、SourceContext 与 PullComplete 事件通知

第5列 SourceContext 为来源上下文，会被原样透传，并在 URL 拉取视频上传完成后，通过 PullComplete 事件通知 原样返回，最长250个字符。字段定义详见 SourceContext 说明。

26、典型用途：与原始 vid 做对应

批量迁移时，可在第5列填入源站视频 ID（原始 vid）或业务侧唯一标识。上传完成后，PullComplete 事件通知会通过 SourceContext 原样带回该值，结合同一事件中的 TaskId、FileId，即可建立「源 vid ↔ 新 FileId」的映射关系，用于迁移对账。

27、前提：需提前在控制台配置回调设置

获取 SourceContext 的前提是先在云点播控制台配置回调设置（配置回调 URL 的普通回调，或使用可靠回调拉取事件；同时配置视频上传完成事件通知）。若未开启，则不会收到 PullComplete 事件，也就无法拿到 SourceContext。配置方式详见 控制台回调设置。

28、如何在回调中获取

SourceContext 位于 PullComplete 事件通知 的 MediaBasicInfo.SourceInfo 下，完整路径为：

PullCompleteEvent.MediaBasicInfo.SourceInfo.SourceContext

回调 JSON 关键片段示例：

{ "EventType": "PullComplete", "PullCompleteEvent": { "TaskId": "125xxxxxx-Pull-f5ac8127b3b6b85cdc13f237c6005d8", "FileId": "14508071098244959037", "MediaBasicInfo": { "MediaUrl": "http://xxx.vod2.myqcloud.com/xxx/xxx.mp4", "SourceInfo": { "SourceType": "Upload", "SourceContext": "your-origin-vid" // ← 拉取上传时第5列传入的值，原样返回 } }, "FileUrl": "http://xxx.vod2.myqcloud.com/xxx/xxx.mp4" }}

30、内置默认参数

# 并发控制max_workers = 10 # 最大并发线程数# 限流设置max_requests_per_second = 5 # 每秒最大请求数# 重试设置max_retries = 3 # 最大重试次数INTERNAL_TIMEOUT = 60 # 内部超时时间（秒）EXTERNAL_TIMEOUT = 70 # 外部强制超时时间（秒）

31、自定义参数

如需调整参数，可修改脚本中的对应常量或类初始化参数：

# 调整并发数uploader = BatchPullUploader(max_workers=15)# 调整限流策略rate_limiter = RateLimiter(max_requests_per_second=10)# 调整重试策略worker = PullUploadWorker(max_retries=5)

33、控制台实时输出

2024-01-15 10:30:00 – INFO – Starting batch pull upload, max concurrent workers: 102024-01-15 10:30:00 – INFO – Rate limiting: max 5 requests per second 2024-01-15 10:30:00 – INFO – Retry setting: max 3 retries with exponential backoff2024-01-15 10:30:01 – INFO – Loaded 5 tasks from test_urls.txt2024-01-15 10:30:01 – INFO – ——————————————————————————–2024-01-15 10:30:02 – INFO – [1/5] 20.0% | SUCCESS | https://example.com/video1.mp42024-01-15 10:30:04 – INFO – [2/5] 40.0% | SUCCESS | https://example.com/video2.mp4 (retry 2 times)2024-01-15 10:30:06 – INFO – [3/5] 60.0% | FAILED | https://example.com/video3.mp4…2024-01-15 10:30:30 – INFO – ================================================================================2024-01-15 10:30:30 – INFO – Batch pull upload completed2024-01-15 10:30:30 – INFO – ================================================================================2024-01-15 10:30:30 – INFO – Total tasks: 52024-01-15 10:30:30 – INFO – Successful tasks: 42024-01-15 10:30:30 – INFO – Failed tasks: 12024-01-15 10:30:30 – INFO – Total execution time: 28.45s2024-01-15 10:30:30 – INFO – Success rate: 80.00%2024-01-15 10:30:30 – INFO – Throughput: 0.18 tasks/second2024-01-15 10:30:30 – INFO – Error breakdown:2024-01-15 10:30:30 – INFO – INVALID_URL: 12024-01-15 10:30:30 – INFO – Total retry attempts: 22024-01-15 10:30:30 – INFO – Average task duration: 2.34s2024-01-15 10:30:30 – INFO – Detailed results saved to: pull_upload_result_20240115_103030.json

34、JSON 结果文件格式

{ "summary": { "total": 5, "success": 4, "failed": 1, "success_rate": 80.0, "error_breakdown": { "INVALID_URL": 1 }, "total_retries": 2, "average_duration": 2.34 }, "results": [ { "line_num": 1, "success": true, "url": "https://example.com/video1.mp4", "media_name": "我的视频1", "class_id": 1001, "response": "{\\"TaskId\\":\\"abc123\\",\\"Status\\":\\"PROCESSING\\"}", "duration": 2.5, "task_id": "abc123" }, { "line_num": 2, "success": false, "url": "https://example.com/video2.mp4", "media_name": null, "class_id": null, "error": "INVALID_URL: Invalid URL format", "error_code": "INVALID_URL", "retry_attempts": 2, "final_failure": true, "total_duration": 45.2 } ]}

35、错误处理机制

脚本采用多层错误处理策略，确保在各种异常情况下的稳定运行：

36、1. 配置层错误处理

·文件不存在：自动检测并提示配置文件路径。

·JSON 格式错误：详细的格式验证和错误定位。

·参数缺失：检查所有必需字段，提供具体缺失信息。

·参数类型错误：验证字段类型（如 subappid 必须为数字）。

37、2. URL 解析层错误处理

·文件权限：处理文件读取权限问题。

·编码问题：强制 UTF-8 编码，处理中文 URL。

·URL 格式验证：严格的 URL 格式检查。

·空行和注释：自动跳过空行和注释行。

38、3. API 调用层错误处理

·TencentCloudSDK 异常：捕获所有 SDK 异常，提取详细错误信息。

·网络超时：双层超时保护（内部检查 + 外部强制）。

·参数验证：安全的参数处理，防止参数错误导致的崩溃。

·系统异常：捕获所有未预期异常，确保程序不崩溃。

39、4. 重试机制错误处理

·智能重试判断：区分可重试错误和不可重试错误。

·可重试：网络错误、API 限流、临时服务异常。

·不可重试：URL 格式错误、参数错误、认证失败。

·指数退避：重试间隔递增（2^attempt，最大30秒）。

·总时间控制：防止无限重试，60秒总超时。

40、5. 结果保存错误处理

·保存重试：文件保存失败时自动重试3次。

·内存保护：成功保存后才清理内存数据。

·用户提示：提供手动保存建议。

41、错误代码说明