Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

再開可能な大容量ファイル(tus)

最終更新 Markdown で表示Agent セットアップ

200 MB を超える動画をアップロードする場合は、tus プロトコル を使う必要があります。200 MB 未満でも、接続が不安定な可能性がある場合は、再開できるため tus プロトコルの利用を推奨します。再開可能なアップロードなら、途中で中断しても、それまでに送ったデータを再送せずに再開できます。

エンドユーザーの動画で tus プロトコルを使う場合は、tus による Direct Creator Uploads を参照してください。

動画が 200 MB 未満で接続が安定している場合は、通常の POST リクエストでも構いません。API トークンを使った直接 API アップロードは、リンクからアップロードする を参照してください。エンドユーザーのアップロードは、Direct Creator Uploads の基本 POST リクエスト を参照してください。

要件

  • 再開可能なアップロードでは、ファイル全体がこのサイズ未満でない限り、チャンクサイズの下限は 5,242,880 バイトです。クライアント接続が安定している見込みなら、性能向上のためチャンクサイズを 52,428,800 バイトに上げてください。
  • チャンクサイズの上限は 209,715,200 バイトです。
  • チャンクサイズは 256 KiB(256x1024 バイト)で割り切れる必要があります。最も近い 256 KiB の倍数に丸めてください。1 チャンクに収まるアップロードの最終チャンクは、この要件の対象外です。

前提条件

tus で動画をアップロードする前に、tus クライアントをダウンロードする必要があります。

詳細は、Python のパッケージマネージャー pip で入手できる 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 の例

始める前に、Go アプリケーションからアップロードするため、go-tus などの tus クライアントをインポートします。

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 トークンを含むリクエストヘッダー。
index.js を設定するjs
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

  • watermark

    • ウォーターマークプロファイルの UID です。

creator プロパティを設定する

Upload-Creator ヘッダーに creator 値を設定すると、動画コンテンツの作成者を識別できます。利用者やクリエイターの識別方法を、Stream アカウント内の動画に紐づけられます。

creator ID の設定と変更の例は、動画をクリエイターに関連付ける を参照してください。

tus 利用時に動画 ID を取得する

最初の tus リクエストを送ると、Stream は Location ヘッダーに URL を返します。この URL に動画 ID が含まれることはありますが、この URL を解析して ID を取る方法は推奨しません。

代わりに、レスポンスの stream-media-id HTTP ヘッダーで動画 ID を取得してください。

たとえば、tus プロトコルで https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream に送ったリクエストには、次のような HTTP ヘッダーが含まれます。

stream-media-id: cab807e0c477d01baq20f66c3d1dfc26cf

役に立ちましたか?