INTEGRITY Документация

← Cloudflare R2 / r2 / api / s3

Расширения

R2 реализует ряд расширений поверх базового S3 API. На этой странице описаны эти дополнительные доступные возможности. Для части функциональности, описанной здесь, требуется указать пользовательский заголовок. Примеры того, как это сделать, приведены в Настройка пользовательских заголовков.

Расширенные метаданные с использованием Unicode

Workers R2 API изначально поддерживает Unicode в ключах и значениях без необходимости дополнительного кодирования или декодирования для customMetadata поле. Эти поля соответствуют x-amz-meta--заголовки, используемые в S3-совместимой конечной точке API R2.

Имена и значения HTTP-заголовков могут содержать только символы ASCII, что является небольшим подмножеством библиотеки символов Unicode. Чтобы упростить работу пользователям, R2 придерживается RFC 2047 ↗ и автоматически декодирует все x-amz-meta-* значения заголовков перед сохранением. При получении любые значения метаданных, содержащие символы Unicode, кодируются по RFC 2047 перед формированием ответа. Ограничение длины для значений метаданных применяется к декодированному значению Unicode.

Эти заголовки соответствуют httpMetadata поле в Привязки R2:

HTTP-заголовок Имя свойства
Content-Encoding httpMetadata.contentEncoding
Content-Type httpMetadata.contentType
Content-Language httpMetadata.contentLanguage
Content-Disposition httpMetadata.contentDisposition
Cache-Control httpMetadata.cacheControl
Expires httpMetadata.expires

При использовании Unicode в именах ключей объектов см. Совместимость Unicode.

Автоматическое создание бакетов при загрузке

Если вы создаёте бакеты по требованию, вы можете начать загрузку, предполагая, что целевой бакет уже существует. В этом случае при получении NoSuchBucket ошибку, вы, вероятно, выполните CreateBucket операцию. Однако такой подход может вызвать проблемы: если тело запроса уже частично считано, загрузку придётся прервать. Распространённым решением этой проблемы, которое применяют и другие поставщики объектного хранилища, является использование HTTP 100 ↗ ответ, чтобы определить, следует ли отправлять тело запроса, или бакет необходимо создать перед повторной попыткой загрузки. Однако Cloudflare не поддерживает HTTP 100 ответ. Даже если HTTP 100 ответ поддерживался, дополнительная задержка из-за требуемых циклов обмена данными все равно сохранялась бы.

Чтобы можно было отправлять загрузку с потоковым телом в бакет, который может еще не существовать, такие операции загрузки, как PutObject или CreateMultipartUpload позволяют указать заголовок, который обеспечит NoSuchBucket ошибка не возвращается. Если bucket не существует на момент загрузки, он неявно создаётся со следующими CreateBucket запрос:

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

Это полезно только в том случае, если вы создаёте бакеты по запросу, потому что заранее не знаете ни имени бакета, ни предпочтительного места доступа. Например, у вас есть отдельный бакет для каждого клиента, и он создаётся при первой загрузке в него, а не при регистрации аккаунта. В таких случаях ListBuckets расширение, который поддерживает аккаунты с более чем 1,000 бакетов, также может быть полезен.

PutObject и CreateMultipartUpload

cf-create-bucket-if-missing

Добавьте cf-create-bucket-if-missing заголовок со значением true чтобы неявно создать бакет, если он ещё не существует. См. Автоматическое создание бакетов при загрузке для более подробного объяснения того, когда следует добавлять этот заголовок.

CopyObject

Директива метаданных MERGE

x-amz-metadata-directive позволяет MERGE значение, в дополнение к стандартному COPY и REPLACE параметры. При использовании MERGE представляет собой сочетание COPY и REPLACE, который будет COPY любые ключи метаданных из исходного объекта и REPLACE те, что указаны в запросе, новым значением. Вы не можете использовать MERGE чтобы удалить существующие ключи метаданных из источника: используйте REPLACE взамен.

ListBuckets

ListBuckets поддерживает все те же параметры поиска, что и ListObjectsV2 в R2, поскольку у некоторых клиентов может быть более 1,000 бакетов. Поскольку инструменты, например существующие S3-библиотеки, могут не предоставлять способа задать эти параметры поиска, эти значения также можно передавать через заголовки. Значения в заголовках имеют приоритет над параметрами поиска.

Параметр поиска HTTP-заголовок Значение
prefix cf-prefix Отображать только бакеты с этим префиксом.
start-after cf-start-after Отображение бакетов, имена которых лексикографически упорядочены в пределах аккаунта.
continuation-token cf-continuation-token Возобновляет получение списка с ранее возвращённого токена продолжения.
max-keys cf-max-keys Возвращает не более указанного количества бакетов. Значение по умолчанию и максимум: 1000.

Ответ в формате XML содержит NextContinuationToken и IsTruncated элементы, где это уместно. Поскольку они могут быть недоступны через существующие S3 API, они также доступны в заголовках ответа:

Элемент XML-ответа HTTP-заголовок ответа Значение
IsTruncated cf-is-truncated Это установлено на true если возвращённый список бакетов включает не все бакеты аккаунта.
NextContinuationToken cf-next-continuation-token Это устанавливается в токен продолжения, который передается в следующем ListBuckets чтобы возобновить листинг.
StartAfter Это значение start-after, которое было передано в запросе.
KeyCount Количество возвращённых бакетов.
ContinuationToken Токен продолжения, переданный в запросе.
MaxKeys Максимальное количество ключей, указанное в запросе.

Условные операции в CopyObject для целевого объекта

CopyObject уже поддерживает условия, связанные с исходным объектом, через x-amz-copy-source-if-... заголовки в рамках нашей совместимости с S3 API. Кроме того, R2 поддерживает набор специфичных для R2 заголовков, которые позволяют CopyObject операцию условной по отношению к целевому объекту:

Эти заголовки работают аналогично одноимённым условным заголовкам, поддерживаемым в PutObject. Если предыдущее состояние целевого объекта не соответствует указанным условиям, CopyObject операция будет отклонена с 412 PreconditionFailed (код ошибки).

Неатомарность относительно x-amz-copy-source-if

x-amz-copy-source-if-... заголовки гарантированно проверяются в момент выбора исходного объекта для операции копирования, а cf-copy-destination-if-... заголовки гарантированно проверяются в момент фиксации объекта в состоянии бакета. Однако момент выбора исходного объекта для копирования и момент фиксации объекта назначения в состоянии бакета не обязательно совпадают. Это означает, что cf-copy-destination-if-... заголовки не атомарны по отношению к x-amz-copy-source-if... заголовки.