← Cloudflare Stream / stream / uploading-videos

Direct creator uploads

Direct Creator Uploads umožňují vašim koncovým uživatelům nahrávat videa přímo do Cloudflare Stream, aniž byste klientům vystavili svůj API token. Direct creator uploads můžete implementovat pomocí buď základní POST požadavek nebo protokol tus. Podle této tabulky zvolíte, kterou metodu použít:

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"

Pokud je video koncového uživatele menší než 200 MB a jeho připojení je spolehlivé, doporučujeme použít tuto metodu. Pokud je připojení koncového uživatele nespolehlivé, doporučujeme použít protokol tus místo toho.

Chcete-li povolit přímé nahrávání tvůrcem pomocí POST požadavek:

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"
	}
}

S uploadURL z předchozího kroku mohou uživatelé nahrávat video soubory o velikosti maximálně 200 MB. Viz ukázkový požadavek níže.

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

Úspěšné nahrání vrátí 200 HTTP stavový kód odpovědi. Pokud nahrávání nesplňuje omezení nahrávání definovaná při vytvoření nebo je soubor větší než 200 MB, odpověď vrátí 4xx stavový kód HTTP.

Pokud je video koncového uživatele větší než 200 MB, musíte použít protokol tus. I když je soubor menší než 200 MB, pokud může být připojení koncového uživatele nespolehlivé, Cloudflare doporučuje použít protokol tus, protože umožňuje obnovení přenosu. Podrobné informace o požadavcích protokolu tus, další příklady klientů a možnosti nahrávání najdete v Obnovitelné nahrávání a velké soubory (tus).

Následující diagram znázorňuje, jak spolu tyto dva kroky procesu souvisejí:

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

Níže uvedený příklad ukazuje, jak vytvořit Worker, který vrátí koncovým uživatelům jednorázovou URL adresu pro nahrání. Pro nahrávání pomocí protokolu tus musí váš backend předat Tus-Resumable, Upload-Length, a Upload-Metadata hlaviček. Jednorázová adresa URL pro nahrání se vrací v Location hlavičce odpovědi, nikoli v těle odpovědi.

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,
		},
	});
}

Koncový bod backendu použijte přímo ve svém tus klientovi. Kompletní ukázku, jak použít backend z kroku 1 s tus klientem uppy, najdete v příkladu níže.

<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>

Další podrobnosti o používání tus a ukázkový kód klienta najdete v Obnovitelné nahrávání a velké soubory (tus).

Můžete použít stejná omezení jako Direct Creator Upload prostřednictvím základního nahrávání při použití tus. Za tímto účelem musíte předat expiry a maxDurationSeconds jako součást Upload-Metadata hlavičku požadavku jako součást prvního požadavku (odeslaného Workerem ve výše uvedeném příkladu). Upload-Metadata hodnoty jsou u následných požadavků, které provádějí samotné nahrání souboru, ignorovány.

Upload-Metadata hlavička by měla obsahovat dvojice klíč-hodnota. Klíče jsou text a hodnoty by měly být zakódované v base64. Klíč a hodnotu oddělte mezerou, ne znaménko rovná se. Pro spojení více dvojic klíč-hodnota použijte čárku bez dalších mezer.

V následujícím příkladu Upload-Metadata hlavička instruuje Stream, aby přijímal pouze nahrávky s maximální délkou videa 10 minut, nahrané před uplynutím časového razítka platnosti, a aby toto video nastavil jako soukromé:

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

NjAw je hodnota zakódovaná v base64 pro „600“ (neboli 10 minut).

MjAyNC0wMi0yN1QwNzoyMDo1MFo= je hodnota zakódovaná v base64 pro „2024-02-27T07:20:50Z“ (časové razítko ve formátu RFC3339)

Po vytvoření jedinečné jednorázové URL adresy pro nahrání byste si měli uchovat jedinečný identifikátor (uid) vrácené v odpovědi, sloužící ke sledování průběhu nahrávání souboru uživatelem.

Průběh nahrávání můžete sledovat následujícími způsoby:

• Použijte koncový bod API pro získání podrobností o videu hodnotou uid.

• Vytvoření odběru webhooku k přijímání oznámení o stavu videa. Tato oznámení obsahují uid.