jojochuang commented on code in PR #582: URL: https://github.com/apache/ozone-site/pull/582#discussion_r4351478110
########## docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md: ########## @@ -74,30 +94,58 @@ The Ozone S3 Gateway implements a substantial subset of the Amazon S3 REST API. | ✅ [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html) | Retrieves the tag set of an object. | Returns the tag set as defined by the S3 API. | | ✅ [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | Removes the tag set from an object. | Clears all tags associated with the object. | +### Object Attributes Operations + +| **API Name** | **Feature** | **Note** | +| ------------ | ----------- | -------- | +| ✅ [GetObjectAttributes](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectAttributes.html) | Returns selected metadata about an object without the object body. | Served as `GET /{bucket}/{key}?attributes`. Use the `x-amz-object-attributes` header to request `ETag`, `ObjectSize`, `StorageClass`, `ObjectParts`, and `Checksum`. For multipart objects, `x-amz-max-parts` and `x-amz-part-number-marker` paginate part metadata. **Non-compliant behavior:** `Checksum` is accepted in the request but not returned, because Ozone does not persist `x-amz-checksum-*` on upload. The `versionId` query parameter and SSE-C headers are ignored. On OBS and LEGACY buckets, `ObjectParts` omits per-part `Part` elements unless an additional checksum was stored at upload time; FSO buckets always return part details. | + ### Multipart Upload Operations | **API Name** | **Feature** | **Note** | | ------------ | ----------- | -------- | | ✅ [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) | Starts a multipart upload session. | Returns an UploadId for subsequent parts. | | ✅ [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) | Uploads an individual part for a multipart upload. | Part numbering and ETag computation follow AWS semantics. | +| ✅ [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) | Uploads a part by copying data from an existing object. | Uses the `x-amz-copy-source` header, and supports `x-amz-copy-source-range` to copy a byte range of the source object. | | ✅ [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) | Lists in-progress multipart uploads in a bucket. | Up to 1000 multipart uploads are returned in a batch by default. | | ✅ [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) | Lists uploaded parts for an in-progress multipart upload. | Supports pagination if many parts exist. | -| ✅ [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | Assembles all uploaded parts into a final object. | Returns an ETag that follows AWS multipart rules. | -| ✅ [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | Aborts an in-progress multipart upload. | Frees up storage used by uploaded parts. Incomplete multipart uploads older than 7 days are automatically aborted by Ozone. | +| ✅ [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | Assembles all uploaded parts into a final object. | Returns an ETag that follows AWS multipart rules. See [Conditional requests](#conditional-requests). | +| ✅ [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | Aborts an in-progress multipart upload. | Frees up storage used by uploaded parts. The OM automatically aborts incomplete multipart uploads that are older than `ozone.om.open.mpu.expire.threshold` (default 30 days). To abort them earlier for a bucket, use a lifecycle rule with `AbortIncompleteMultipartUpload`. | ### Additional Operations | **API Name** | **Feature** | **Note** | | -------------------------- | ------------- | ---------- | -| ✅ Generate Presigned URL | Generates a temporary URL for accessing an object. | Uses AWS Signature V4. **Non-compliant behavior:** The generated URL may include a fixed default region rather than dynamically reflecting the bucket’s location. Ozone now supports generating presigned URLs for all major S3 operations, including `GetObject`, `PutObject`, `DeleteObject`, `HeadObject`, `HeadBucket`, `MultipartUpload`. | +| ✅ Generate Presigned URL | Generates a temporary URL for accessing an object. | Uses AWS Signature V4. **Non-compliant behavior:** The generated URL may include a fixed default region rather than dynamically reflecting the bucket’s location. The S3 Gateway accepts presigned URLs (AWS Signature V4 query authentication) for all supported operations, such as `GetObject`, `PutObject`, `DeleteObject`, `HeadObject`, `HeadBucket`, and the multipart upload operations. | + +### Conditional Requests + +The S3 Gateway partially supports [conditional requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-requests.html): + +- **GetObject and HeadObject:** Support `If-Match`, `If-None-Match`, `If-Modified-Since`, and `If-Unmodified-Since`. A failed `If-Match` or `If-Unmodified-Since` returns `412 Precondition Failed`. A matching `If-None-Match` or a failed `If-Modified-Since` returns `304 Not Modified`. +- **CopyObject:** Supports `x-amz-copy-source-if-match`, `x-amz-copy-source-if-none-match`, `x-amz-copy-source-if-modified-since`, and `x-amz-copy-source-if-unmodified-since` on the source object. A failed condition returns `412 Precondition Failed`. +- **PutObject, CopyObject, and CompleteMultipartUpload:** Support `If-Match` with an ETag, to write only if the existing object matches, and `If-None-Match: *`, to write only if the object does not exist. `If-None-Match` with a specific ETag is not supported and returns `InvalidRequest`. `If-Match` and `If-None-Match` cannot be used together. Review Comment: If-None-Match with an Etag is supported by https://github.com/apache/ozone/pull/11366 (just added) Also note that If-None-Match with an Etag is not a AWS S3 feature. It's a Ceph S3 extension. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
