INTEGRITY Dokumentace

← Cloudflare R2 / r2 / api / workers

Použití R2 z Workers

1. Vytvořte novou aplikaci pomocí C3

C3 (create-cloudflare-cli) je nástroj příkazové řádky, který vám pomůže co nejrychleji nastavit a nasadit aplikace Workers & Pages na Cloudflare.

Pro začátek otevřete okno terminálu a spusťte:

npm create cloudflare@latest -- r2-worker

Při nastavení vyberte následující možnosti:

Poté přejděte do svého nově vytvořeného adresáře:

cd r2-worker

2. Vytvořte svůj bucket

Vytvořte bucket spuštěním:

npx wrangler r2 bucket create <YOUR_BUCKET_NAME>

Chcete-li ověřit, že byl váš bucket vytvořen, spusťte:

npx wrangler r2 bucket list

Po spuštění list uvidíte všechny názvy bucketů, včetně toho, který jste právě vytvořili.

3. Přiřaďte svůj bucket k Workeru

Bude nutné propojit váš bucket s Workerem.

Chcete-li svázat bucket R2 se svým Workerem, přidejte do souboru Wrangler následující. Aktualizujte binding vlastnost na platný identifikátor proměnné v JavaScriptu a bucket_name do <YOUR_BUCKET_NAME> kterou jste použili k vytvoření vašeho bucketu v krok 2:

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET", // <~ valid JavaScript variable name
			"bucket_name": "<YOUR_BUCKET_NAME>"
		}
	]
}
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

Podrobnější informace o konfiguraci Workeru (například pokud používáte jurisdikce), viz Dokumentace ke konfiguraci Wrangler.

4. Přistupte ke svému R2 bucketu ze svého Workeru

Ve vašem kódu Workeru je nyní bucket dostupný pod MY_BUCKET proměnná a můžete s ní začít pracovat.

Bucket R2 dokáže objekty číst, vypisovat, zapisovat a mazat (READ, LIST, WRITE, DELETE). Příklad všech těchto operací pomocí syntaxe Module Worker najdete níže. Přidejte následující úryvek do souboru projektu index.js soubor:

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint<Env> {
  async fetch(request: Request) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case "PUT": {
        await this.env.MY_BUCKET.put(key, request.body, {
          onlyIf: request.headers,
          httpMetadata: request.headers,
        });
        return new Response(`Put ${key} successfully!`);
      }
      case "GET": {
        const object = await this.env.MY_BUCKET.get(key, {
          onlyIf: request.headers,
          range: request.headers,
        });

        if (object === null) {
          return new Response("Object Not Found", { status: 404 });
        }

        const headers = new Headers();
        object.writeHttpMetadata(headers);
        headers.set("etag", object.httpEtag);

        // When no body is present, preconditions have failed
        return new Response("body" in object ? object.body : undefined, {
          status: "body" in object ? 200 : 412,
          headers,
        });
      }
      case "DELETE": {
        await this.env.MY_BUCKET.delete(key);
        return new Response("Deleted!");
      }
      default:
        return new Response("Method Not Allowed", {
          status: 405,
          headers: {
            Allow: "PUT, GET, DELETE",
          },
        });
    }
  }
};
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case "PUT": {
        await env.MY_BUCKET.put(key, request.body, {
          onlyIf: request.headers,
          httpMetadata: request.headers,
        });
        return new Response(`Put ${key} successfully!`);
      }
      case "GET": {
        const object = await env.MY_BUCKET.get(key, {
          onlyIf: request.headers,
          range: request.headers,
        });

        if (object === null) {
          return new Response("Object Not Found", { status: 404 });
        }

        const headers = new Headers();
        object.writeHttpMetadata(headers);
        headers.set("etag", object.httpEtag);

        // When no body is present, preconditions have failed
        return new Response("body" in object ? object.body : undefined, {
          status: "body" in object ? 200 : 412,
          headers,
        });
      }
      case "DELETE": {
        await env.MY_BUCKET.delete(key);
        return new Response("Deleted!");
      }
      default:
        return new Response("Method Not Allowed", {
          status: 405,
          headers: {
            Allow: "PUT, GET, DELETE",
          },
        });
    }
  }
}
from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse


class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if request.method == "PUT":
			await self.env.MY_BUCKET.put(
				key,
				request.body,
				onlyIf=request.headers,
				httpMetadata=request.headers,
			)
			return Response(f"Put {key} successfully!")
		elif request.method == "GET":
			obj = await self.env.MY_BUCKET.get(
				key,
				onlyIf=request.headers,
				range=request.headers,
			)

			if obj is None:
				return Response("Object Not Found", status=404)

			# When no body is present, preconditions have failed
			body = obj.body if hasattr(obj, "body") else None
			status = 200 if hasattr(obj, "body") else 412

			headers = {"etag": obj.httpEtag}
			return Response(body, status=status, headers=headers)
		elif request.method == "DELETE":
			await self.env.MY_BUCKET.delete(key)
			return Response("Deleted!")
		else:
			return Response(
				"Method Not Allowed",
				status=405,
				headers={"Allow": "PUT, GET, DELETE"},
			)

5. Přístup k bucketu a soukromí

Po přidání výše uvedeného kódu do vašeho Workeru může každý příchozí požadavek pracovat s vaším bucketem. To znamená, že váš bucket je veřejně přístupný a jeho obsah může být čten a upravován nežádoucími subjekty.

Nyní musíte definovat autorizační logiku, která určí, kdo může s vaším bucketem provádět jaké akce. Tato logika je součástí kódu vašeho Workeru, protože je úkolem vaší aplikace určit oprávnění uživatelů. Následuje krátký seznam zdrojů týkajících se přístupu a autorizačních postupů:

  1. Basic Authentication: Ukazuje, jak omezit přístup pomocí schématu HTTP Basic.
  2. Použití vlastních hlaviček: Povolí nebo zamítne požadavek na základě známého předsdíleného klíče v hlavičce.

Nyní, když máte nově vytvořený bucket a Worker, je třeba zabezpečit všechny operace s bucketem.

Pro PUT a DELETE požadavků využijete nový AUTH_KEY_SECRET proměnnou prostředí, kterou později definujete jako Wrangler secret.

Pro GET požadavků zajistíte, že lze vyžádat pouze konkrétní soubor. Veškerá tato vlastní logika probíhá uvnitř authorizeRequest funkce, s hasValidHeader funkce, která zpracovává logiku vlastní hlavičky. Pokud validace projde, je operace povolena.

const ALLOW_LIST = ["cat-pic.jpg"];

// Check requests for a pre-shared secret
const hasValidHeader = (request, env) => {
	return request.headers.get("X-Custom-Auth-Key") === env.AUTH_KEY_SECRET;
};

function authorizeRequest(request, env, key) {
	switch (request.method) {
		case "PUT":
		case "DELETE":
			return hasValidHeader(request, env);
		case "GET":
			return ALLOW_LIST.includes(key);
		default:
			return false;
	}
}

export default {
	async fetch(request, env, ctx) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		if (!authorizeRequest(request, env, key)) {
			return new Response("Forbidden", { status: 403 });
		}

		// ...
	},
};
from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse

ALLOW_LIST = ["cat-pic.jpg"]

# Check requests for a pre-shared secret
def has_valid_header(request, env):
	return request.headers.get("X-Custom-Auth-Key") == env.AUTH_KEY_SECRET

def authorize_request(request, env, key):
	if request.method in ["PUT", "DELETE"]:
		return has_valid_header(request, env)
	elif request.method == "GET":
		return key in ALLOW_LIST
	else:
		return False

class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if not authorize_request(request, self.env, key):
			return Response("Forbidden", status=403)

		# ...

Aby to fungovalo, musíte vytvořit tajný klíč pomocí Wrangler:

npx wrangler secret put AUTH_KEY_SECRET

Tento příkaz vás v terminálu vyzve k zadání secretu:

npx wrangler secret put AUTH_KEY_SECRET
Enter the secret text you'd like assigned to the variable AUTH_KEY_SECRET on the script named <YOUR_WORKER_NAME>:
*********
🌀  Creating the secret for script name <YOUR_WORKER_NAME>
✨  Success! Uploaded secret AUTH_KEY_SECRET.

Tento secret je nyní dostupný jako AUTH_KEY_SECRET na env parametr ve svém Workeru.

6. Nasaďte svůj Worker

Jakmile máte Worker a bucket nastavené, spusťte npx wrangler deploy příkaz k nasazení do globální sítě Cloudflare:

npx wrangler deploy

Funkčnost své autorizační logiky můžete ověřit pomocí následujících příkazů, s využitím koncového bodu nasazeného Workeru:

# Attempt to write an object without providing the "X-Custom-Auth-Key" header
curl https://your-worker.dev/cat-pic.jpg -X PUT --data-binary 'test'
#=> Forbidden
# Expected because header was missing

# Attempt to write an object with the wrong "X-Custom-Auth-Key" header value
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: hotdog" --data-binary 'test'
#=> Forbidden
# Expected because header value did not match the AUTH_KEY_SECRET value

# Attempt to write an object with the correct "X-Custom-Auth-Key" header value
# Note: Assume that "*********" is the value of your AUTH_KEY_SECRET Wrangler secret
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: *********" --data-binary 'test'
#=> Put cat-pic.jpg successfully!

# Attempt to read object called "foo"
curl https://your-worker.dev/foo
#=> Forbidden
# Expected because "foo" is not in the ALLOW_LIST

# Attempt to read an object called "cat-pic.jpg"
curl https://your-worker.dev/cat-pic.jpg
#=> test
# Note: This is the value that was successfully PUT above

Dokončením tohoto průvodce jste úspěšně nainstalovali Wrangler a nasadili svůj bucket R2 na Cloudflare.

  1. Návody pro Workers
  2. Příklady pro Workers