← Cloudflare Stream / stream / uploading-videos

Direct Creator Uploads

Direct Creator Uploads позволяют конечным пользователям загружать видео напрямую в Cloudflare Stream, не раскрывая ваш API-токен на стороне клиента. Реализовать Direct Creator Uploads можно с помощью простой POST-запрос или протокол tus. Используйте эту таблицу, чтобы выбрать подходящий метод:

flowchart LR
accTitle: Direct creator uploads decision flow
accDescr: Decision flow for choosing between basic POST uploads and tus protocol based on file size and connection reliability

A{Is the video over 200 MB?}
A -->|Yes| B[You must use the tus protocol]:::link
A -->|No| C{Does the end user have a reliable connection?}
C -->|Yes| D[Basic POST is recommended]:::link
C -->|No| E[The tus protocol is optional, but recommended]:::link

classDef link text-decoration:underline,color:#F38020

click B "#direct-creator-uploads-with-tus-protocol" "Learn about tus protocol"
click D "#basic-post-request" "See basic POST instructions"
click E "#direct-creator-uploads-with-tus-protocol" "Learn about tus protocol"

Если видео конечного пользователя меньше 200 МБ, а соединение стабильно, рекомендуем использовать этот способ. Если соединение пользователя нестабильно, рекомендуем использовать протокол tus взамен.

Чтобы включить прямую загрузку создателем контента с POST запрос:

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/direct_upload \
--header 'Authorization: Bearer <API_TOKEN>' \
 --data '{
    "maxDurationSeconds": 3600
 }'

{
	"result": {
		"uploadURL": "https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22",
		"uid": "f65014bc6ff5419ea86e7972a047ba22"
	},
	"success": true,
	"errors": [],
	"messages": []
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 3600,
		});

		return new Response(JSON.stringify(directUpload));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "$today",
	"observability": {
		"enabled": true
	},
	"stream": {
		"binding": "STREAM"
	}
}

С uploadURL из предыдущего шага пользователи могут загружать видеофайлы размером не более 200 МБ. См. пример запроса ниже.

curl --request POST \
  --form file=@/Users/mickie/Downloads/example_video.mp4 \
  https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22

При успешной загрузке возвращается 200 код состояния HTTP. Если загрузка не соответствует ограничениям, заданным при создании, или превышает 200 МБ, в ответе возвращается 4xx код статуса HTTP.

Если видео конечного пользователя весит более 200 МБ, необходимо использовать протокол tus. Даже если файл меньше 200 МБ, но соединение пользователя может быть нестабильным, Cloudflare рекомендует использовать протокол tus, так как он поддерживает возобновление загрузки. Подробнее о требованиях протокола tus, дополнительных примерах для клиентов и параметрах загрузки см. Возобновляемая загрузка больших файлов (tus).

Диаграмма ниже показывает, как взаимодействуют два этапа этого процесса:

sequenceDiagram
accTitle: Direct Creator Uploads with tus sequence diagram
accDescr: Shows the two-step flow where a backend provisions a tus upload URL and the end user uploads directly to Stream

participant U as End user
participant B as Your backend
participant S as Cloudflare Stream

U->>B: Initiates upload request
B->>S: Requests tus upload URL (authenticated)
S->>B: Returns one-time upload URL
B->>U: Returns one-time upload URL
U->>S: Uploads video directly using tus

Пример ниже показывает, как создать Worker, который возвращает конечным пользователям одноразовый URL для загрузки. Для загрузок по протоколу tus ваш backend должен передавать Tus-Resumable, Upload-Length, а также Upload-Metadata заголовков. Одноразовый URL-адрес для загрузки возвращается в Location заголовке ответа, а не в теле ответа.

export async function onRequest(context) {
	const { request, env } = context;
	const { CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN } = env;
	const endpoint = `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/stream?direct_user=true`;

	const response = await fetch(endpoint, {
		method: "POST",
		headers: {
			Authorization: `bearer ${CLOUDFLARE_API_TOKEN}`,
			"Tus-Resumable": "1.0.0",
			"Upload-Length": request.headers.get("Upload-Length"),
			"Upload-Metadata": request.headers.get("Upload-Metadata"),
		},
	});

	const destination = response.headers.get("Location");

	return new Response(null, {
		headers: {
			"Access-Control-Expose-Headers": "Location",
			"Access-Control-Allow-Headers": "*",
			"Access-Control-Allow-Origin": "*",
			Location: destination,
		},
	});
}

Используйте свой backend-эндпоинт напрямую в клиенте tus. Полный пример использования backend из шага 1 с клиентом uppy tus приведён ниже.

<html>
	<head>
		<link
			href="https://releases.transloadit.com/uppy/v3.0.1/uppy.min.css"
			rel="stylesheet"
		/>
	</head>
	<body>
		<div id="drag-drop-area" style="height: 300px"></div>
		<div class="for-ProgressBar"></div>
		<button class="upload-button" style="font-size: 30px; margin: 20px">
			Upload
		</button>
		<div class="uploaded-files" style="margin-top: 50px">
			<ol></ol>
		</div>
		<script type="module">
			import {
				Uppy,
				Tus,
				DragDrop,
				ProgressBar,
			} from "https://releases.transloadit.com/uppy/v3.0.1/uppy.min.mjs";

			const uppy = new Uppy({ debug: true, autoProceed: true });

			const onUploadSuccess = (el) => (file, response) => {
				const li = document.createElement("li");
				const a = document.createElement("a");
				a.href = response.uploadURL;
				a.target = "_blank";
				a.appendChild(document.createTextNode(file.name));
				li.appendChild(a);

				document.querySelector(el).appendChild(li);
			};

			uppy
				.use(DragDrop, { target: "#drag-drop-area" })
				.use(Tus, {
					endpoint: "/api/get-upload-url",
					chunkSize: 150 * 1024 * 1024,
				})
				.use(ProgressBar, {
					target: ".for-ProgressBar",
					hideAfterFinish: false,
				})
				.on("upload-success", onUploadSuccess(".uploaded-files ol"));

			const uploadBtn = document.querySelector("button.upload-button");
			uploadBtn.addEventListener("click", () => uppy.upload());
		</script>
	</body>
</html>

Подробнее об использовании tus и примерах клиентского кода см. в Возобновляемая загрузка больших файлов (tus).

Вы можете применить те же ограничения как Direct Creator Upload через basic upload при использовании tus. Для этого необходимо передать expiry и maxDurationSeconds в рамках Upload-Metadata заголовок запроса как часть первого запроса (сделанного Worker в примере выше.) Upload-Metadata значения игнорируются в последующих запросах, выполняющих непосредственную загрузку файла.

Upload-Metadata заголовок должен содержать пары «ключ-значение». Ключи представляют собой текст, а значения должны быть закодированы в base64. Разделяйте ключ и значение пробелом, не знак равенства. Чтобы объединить несколько пар ключ-значение, используйте запятую без дополнительных пробелов.

В примере ниже Upload-Metadata заголовок указывает Stream принимать только загрузки с максимальной длительностью видео 10 минут, отправленные до истечения времени, указанного в метке, и сделать это видео закрытым:

'Upload-Metadata: maxDurationSeconds NjAw,requiresignedurls,expiry MjAyNC0wMi0yN1QwNzoyMDo1MFo='

NjAw это значение, закодированное в base64, для «600» (то есть 10 минут).

MjAyNC0wMi0yN1QwNzoyMDo1MFo= это значение, закодированное в base64, для «2024-02-27T07:20:50Z» (временная метка в формате RFC3339)

После создания уникального одноразового URL-адреса для загрузки сохраните уникальный идентификатор (uid) возвращаемый в ответе для отслеживания прогресса загрузки пользователя.

Вы можете отслеживать прогресс загрузки следующими способами:

• Используйте эндпоинт API получения сведений о видео на uid.

• Создание подписки на webhook чтобы получать уведомления о статусе видео. Эти уведомления включают uid.