INTEGRITY Dokumentace

← Cloudflare R2 / r2 / api / s3

Rozšíření

R2 implementuje některá rozšíření nad rámec základního rozhraní S3 API. Tato stránka popisuje tyto dostupné doplňkové funkce. Některé z nich vyžadují nastavení vlastní hlavičky. Příklady, jak to provést, najdete v Konfigurace vlastních hlaviček.

Rozšířená metadata pomocí Unicode

Workers R2 API nativně podporuje Unicode v klíčích i hodnotách, aniž by bylo potřeba další kódování nebo dekódování pro customMetadata pole. Tato pole odpovídají x-amz-meta--prefixed hlaviček používaných v koncovém bodu rozhraní API R2 kompatibilního s S3.

Názvy a hodnoty hlaviček HTTP mohou obsahovat pouze znaky ASCII, což je malá podmnožina znakové sady Unicode. Aby to uživatelům usnadnilo, R2 dodržuje RFC 2047 ↗ a automaticky dekóduje všechny x-amz-meta-* hlavičky před uložením. Při načítání se všechny hodnoty metadat obsahující unicode kódují pomocí RFC 2047 před vykreslením odpovědi. Limit délky pro hodnoty metadat se uplatňuje na dekódovanou hodnotu Unicode.

Tyto hlavičky odpovídají httpMetadata v Vazby R2:

Hlavička HTTP Název vlastnosti
Content-Encoding httpMetadata.contentEncoding
Content-Type httpMetadata.contentType
Content-Language httpMetadata.contentLanguage
Content-Disposition httpMetadata.contentDisposition
Cache-Control httpMetadata.cacheControl
Expires httpMetadata.expires

Pokud v názvech klíčů objektů používáte Unicode, přečtěte si Interoperabilita Unicode.

Automatické vytváření bucketů při nahrávání

Pokud buckety vytváříte na vyžádání, můžete zahájit nahrávání s předpokladem, že cílový bucket existuje. V takové situaci, pokud obdržíte NoSuchBucket chybu, pravděpodobně byste vydali CreateBucket operaci. Tento postup však může způsobit problémy: pokud již bylo tělo požadavku částečně zpracováno, bude nutné nahrávání přerušit. Běžným řešením tohoto problému, které používají i další poskytovatelé úložiště objektů, je použití HTTP 100 ↗ odpověď a zjistit, zda by se mělo odeslat tělo, nebo zda je nutné bucket nejprve vytvořit a nahrávání zopakovat. Cloudflare však nepodporuje HTTP 100 odpověď. I kdyby HTTP 100 odpověď byla podporována, stále by docházelo k dodatečné latenci kvůli souvisejícím zpátečním cestám (round trips).

Aby bylo možné odesílat nahrávání se streamovaným tělem do bucketu, který ještě nemusí existovat, operace nahrávání jako PutObject nebo CreateMultipartUpload umožňují zadat hlavičku, která zajistí NoSuchBucket chyba se nevrací. Pokud bucket v době nahrávání neexistuje, je implicitně vytvořen s následujícím CreateBucket požadavek:

PUT / HTTP/1.1
Host: bucket.account.r2.cloudflarestorage.com
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <LocationConstraint>auto</LocationConstraint>
</CreateBucketConfiguration>

Toto je užitečné pouze v případě, že buckety vytváříte na vyžádání, protože předem neznáte název bucketu ani preferované umístění přístupu. Můžete mít například jeden bucket pro každého zákazníka, přičemž bucket se vytvoří až při prvním nahrání do něj, nikoli při registraci účtu. V takových případech ListBuckets přípona, který podporuje účty s více než 1 000 buckety, může být rovněž užitečný.

PutObject a CreateMultipartUpload

cf-create-bucket-if-missing

Přidejte cf-create-bucket-if-missing hlavičku s hodnotou true k implicitnímu vytvoření bucketu, pokud ještě neexistuje. Více informací najdete v Automatické vytváření bucketů při nahrávání pro podrobnější vysvětlení, kdy tuto hlavičku přidat.

CopyObject

Direktiva metadat MERGE

x-amz-metadata-directive umožňuje MERGE hodnotu, kromě standardní COPY a REPLACE možnosti. Při použití MERGE je kombinací COPY a REPLACE, což COPY veškeré klíče metadat ze zdrojového objektu a REPLACE ty, které jsou v požadavku uvedeny, novou hodnotou. Nelze použít MERGE k odstranění stávajících klíčů metadat ze zdroje, použijte REPLACE místo toho.

ListBuckets

ListBuckets podporuje stejné parametry vyhledávání jako ListObjectsV2 v R2, protože někteří zákazníci mohou mít více než 1 000 bucketů. Vzhledem k tomu, že nástroje, jako jsou existující knihovny S3, nemusí nabízet způsob, jak tyto vyhledávací parametry nastavit, lze tyto hodnoty odeslat také v hlavičkách. Hodnoty v hlavičkách mají přednost před vyhledávacími parametry.

Parametr vyhledávání Hlavička HTTP Význam
prefix cf-prefix Zobrazí pouze buckety s tímto prefixem.
start-after cf-start-after Zobrazí buckety, jejichž název se v účtu řadí lexikograficky.
continuation-token cf-continuation-token Pokračujte ve výpisu od dříve vráceného continuation tokenu.
max-keys cf-max-keys Vrátí nejvýše tento počet bucketů. Výchozí a maximální hodnota je 1000.

Odpověď XML obsahuje NextContinuationToken a IsTruncated prvky podle potřeby. Jelikož nemusí být dostupné ze stávajících S3 API, jsou k dispozici i v hlavičkách odpovědi:

Prvek odpovědi XML Hlavička odpovědi HTTP Význam
IsTruncated cf-is-truncated Toto je nastaveno na true pokud vrácený seznam bucketů neobsahuje všechny buckety v účtu.
NextContinuationToken cf-next-continuation-token Toto je nastaveno na continuation token, který se předá v následujícím ListBuckets pro pokračování ve výpisu.
StartAfter Toto je hodnota start-after, která byla předána v požadavku.
KeyCount Počet vrácených bucketů.
ContinuationToken Token pro pokračování, který byl uveden v požadavku.
MaxKeys Maximální počet klíčů uvedený v požadavku.

Podmíněné operace v CopyObject pro cílový objekt

CopyObject již podporuje podmínky týkající se zdrojového objektu prostřednictvím x-amz-copy-source-if-... hlavičky jako součást naší kompatibility s S3 API. Kromě toho R2 podporuje sadu hlaviček specifických pro R2, které umožňují CopyObject operaci podmíněnou cílovým objektem:

Tyto hlavičky fungují obdobně jako stejnojmenné podmíněné hlavičky podporované u PutObject. Pokud předchozí stav cílového objektu neodpovídá zadaným podmínkám, CopyObject operace bude odmítnuta s 412 PreconditionFailed signalizuje právě takový případ.

Neatomičnost vzhledem k x-amz-copy-source-if

x-amz-copy-source-if-... hlavičky jsou vždy zkontrolovány ve chvíli, kdy je vybrán zdrojový objekt pro operaci kopírování, a cf-copy-destination-if-... hlavičky jsou vždy zkontrolovány, když je objekt zapsán do stavu bucketu. Čas, kdy je zdrojový objekt vybrán ke kopírování, a okamžik, kdy je cílový objekt zapsán do stavu bucketu, se však nemusí shodovat. To znamená, že cf-copy-destination-if-... hlavičky nejsou atomické ve vztahu k x-amz-copy-source-if... hlaviček.