跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

可恢复和大文件 (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 bytes)整除。只有可由单个分块容纳的上传中的最后一个分块不受此要求限制。

所需条件

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

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

Install Python clientpython
pip install -U tus.py

使用 tus 上传视频

Upload using tussh
tus-upload --chunk-size 52428800 --header \
Authorization "Bearer <API_TOKEN>"
<PATH_TO_VIDEO> https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream
tus responsesh
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 不是必需的。

Upload with Golanggo
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 中运行上传,您还可以获取上传进度。

Get progress of uploadgo
// 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 的请求头。
Configure 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

这篇文档对您有帮助吗?