跳转到内容
搜索文档

可恢复和大文件 (tus)

最后更新 查看 MarkdownAgent 设置

如果您需要上传超过 200 MB 的视频,必须使用 tus 协议。即使视频小于 200 MB,如果连接可能不稳定,Cloudflare 也建议使用 tus 协议,因为它支持断点续传。可恢复上传确保上传可以中断并恢复,而无需重新上传之前的数据。

要在终端用户视频中使用 tus 协议,请参阅使用 tus 的 Direct Creator Uploads

如果您的视频小于 200 MB 且连接稳定,可以使用基本的 POST 请求。对于使用 API token 的直接 API 上传,请参阅通过链接上传。对于终端用户上传,请参阅Direct Creator Uploads 的基本 POST 请求

要求

  • 可恢复上传要求最小分块大小为 5,242,880 字节,除非整个文件小于此大小。当客户端连接预期稳定时,为提高性能,可将分块大小增加到 52,428,800 字节。
  • 最大分块大小为 209,715,200 字节。
  • 分块大小必须能被 256 KiB(256x1024 字节)整除。将分块大小四舍五入到最接近的 256 KiB 倍数。注意,适合单个分块的最终上传分块不受此要求限制。

所需条件

在使用 tus 上传视频之前,您需要下载 tus 客户端。

更多信息请参阅可通过 pip(Python 包管理器)获取的 tus Python 客户端

安装 Python 客户端python
pip install -U tus.py

使用 tus 上传视频

使用 tus 上传sh
tus-upload --chunk-size 52428800 --header \
Authorization "Bearer <API_TOKEN>"
<PATH_TO_VIDEO> https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream
tus 响应sh
INFO Creating file endpoint
INFO Created: https://api.cloudflare.com/client/v4/accounts/d467d4f0fcbcd9791b613bc3a9599cdc/stream/dd5d531a12de0c724bd1275a3b2bc9c6
...

Golang 示例

开始之前,导入 tus 客户端(如 go-tus)以从 Go 应用程序上传。

go-tus 库不会将响应头返回给调用函数,因此难以从 stream-media-id 头读取视频 ID。作为变通方法,创建 Direct Creator Upload 链接。该 API 响应将包含 TUS 端点和视频 ID。设置 Creator ID 不是必需的。

使用 Golang 上传go
package main

import (
	"net/http"
	"os"

	tus "github.com/eventials/go-tus"
)

func main() {
	accountID := "<ACCOUNT_ID>"

	f, err := os.Open("videofile.mp4")

	if err != nil {
		panic(err)
	}

	defer f.Close()

	headers := make(http.Header)
	headers.Add("Authorization", "Bearer <API_TOKEN>")

	config := &tus.Config{
		ChunkSize:           50 * 1024 * 1024, // Required a minimum chunk size of 5 MB, here we use 50 MB.
		Resume:              false,
		OverridePatchMethod: false,
		Store:               nil,
		Header:              headers,
		HttpClient:          nil,
	}

	client, _ := tus.NewClient("https://api.cloudflare.com/client/v4/accounts/"+ accountID +"/stream", config)

	upload, _ := tus.NewUploadFromFile(f)

	uploader, _ := client.CreateUpload(upload)

	uploader.Upload()
}

如果在 goroutine 中运行上传,您还可以获取上传进度。

获取上传进度go
// returns the progress percentage.
upload.Progress()

// returns whether or not the upload is complete.
upload.Finished()

有关恢复上传等功能,请参阅 go-tus

Node.js 示例

开始之前,安装 tus-js-client。

npm i tus-js-client

创建 index.js 文件并配置:

  • 带有 Cloudflare Account ID 的 API 端点。
  • 包含 API token 的请求头。
配置 index.jsjs
var fs = require("fs");
var tus = require("tus-js-client");

// Specify location of file you would like to upload below
var path = __dirname + "/test.mp4";
var file = fs.createReadStream(path);
var size = fs.statSync(path).size;
var mediaId = "";

var options = {
	endpoint: "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream",
	headers: {
		Authorization: "Bearer <API_TOKEN>",
	},
	chunkSize: 50 * 1024 * 1024, // Required a minimum chunk size of 5 MB. Here we use 50 MB.
	retryDelays: [0, 3000, 5000, 10000, 20000], // Indicates to tus-js-client the delays after which it will retry if the upload fails.
	metadata: {
		name: "test.mp4",
		filetype: "video/mp4",
		// Optional if you want to include a watermark
		// watermark: '<WATERMARK_UID>',
	},
	uploadSize: size,
	onError: function (error) {
		throw error;
	},
	onProgress: function (bytesUploaded, bytesTotal) {
		var percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
		console.log(bytesUploaded, bytesTotal, percentage + "%");
	},
	onSuccess: function () {
		console.log("Upload finished");
	},
	onAfterResponse: function (req, res) {
		return new Promise((resolve) => {
			var mediaIdHeader = res.getHeader("stream-media-id");
			if (mediaIdHeader) {
				mediaId = mediaIdHeader;
			}
			resolve();
		});
	},
};

var upload = new tus.Upload(file, options);
upload.start();

指定上传选项

tus 协议允许您在 Upload-Metadata中添加可选参数。

Upload-Metadata 中支持的选项

Upload-Metadata 头中设置任意元数据值会在 Stream API 中的 meta 键中设置相应值。

  • name

    • 设置此键将在 API 中设置 meta.name,并在仪表板中将该值显示为视频名称。
  • requiresignedurls

    • 如果存在此键,上传后此视频的播放将需要使用签名 URL。
  • scheduleddeletion

    • 指定视频将被删除的日期和时间。视频删除后,将无法再观看,也不再计入计费存储。指定的日期和时间不能早于视频创建时间戳 30 天,也不能晚于 1,096 天。
  • allowedorigins

    • 字符串数组,列出允许显示视频的来源。这将设置视频的允许来源设置
  • thumbnailtimestamppct

    • 指定默认缩略图时间戳百分比。注意,百分比是 0.0 到 1.0 之间的浮点值。
  • watermark

    • 水印配置文件 UID。

设置 creator 属性

Upload-Creator 头中设置 creator 值可用于标识视频内容的创作者,将您识别用户或创作者的方式与 Stream 账户中的视频关联。

有关如何设置和修改 creator ID 的示例,请参阅将视频与创作者关联

使用 tus 时获取视频 ID

进行初始 tus 请求时,Stream 会在 Location 头中返回 URL。虽然此 URL 可能包含视频 ID,但不建议解析此 URL 来获取 ID。

相反,您应使用响应中的 stream-media-id HTTP 头来检索视频 ID。

例如,向 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream 发送 tus 协议请求时,响应将包含类似以下的 HTTP 头:

stream-media-id: cab807e0c477d01baq20f66c3d1dfc26cf

这篇文档对您有帮助吗?