Class ObjectService

Amazon S3 Object operations service.

Inheritance

object

CrudServiceBase<AwsClient>

ObjectService

Implements

ICrudService

Inherited Members

CrudServiceBase<AwsClient>.client

CrudServiceBase<AwsClient>.ApiKey

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Glitch9.AIDevKit.AmazonAws.S3.Services

Assembly: Glitch9.AIDevKit.Provider.AmazonAws.dll

Syntax

public sealed class ObjectService : CrudServiceBase<AwsClient>, ICrudService

Remarks

Required Permissions:

s3:PutObject - To upload objects
s3:GetObject - To retrieve objects
s3:DeleteObject - To delete objects

Constructors

| Edit this page View Source

ObjectService(AwsClient)

Declaration

public ObjectService(AwsClient client)

Parameters

Type	Name	Description
AwsClient	client

Methods

| Edit this page View Source

DeleteAsync(DeleteObjectRequest, RequestOptions)

Removes an object from a bucket.

Declaration

public UniTask<DeleteObjectResponse> DeleteAsync(DeleteObjectRequest request, RequestOptions options = null)

Parameters

Type	Name	Description
DeleteObjectRequest	request	The object deletion request parameters.
RequestOptions	options	Optional REST request options.

Returns

Type	Description
UniTask<DeleteObjectResponse>	The DeleteObject response with deletion metadata.

Remarks

Versioning Behavior:

- Versioning not enabled: The operation permanently deletes the object.

- Versioning enabled: The operation inserts a delete marker, which becomes the current version. To permanently delete, include the object's versionId in the request.

- Versioning suspended: The operation removes the object with a null versionId (if exists) and inserts a delete marker. To permanently delete an object with a versionId, include it in the request.

Directory Buckets:

- S3 Versioning isn't enabled and supported for directory buckets. Only the null value of the version ID is supported.

- You must make requests to the Zonal endpoint: https://bucket-name.s3express-zone-id.region-code.amazonaws.com/key-name

- Path-style requests are not supported.

Version Deletion:

To remove a specific version, use the versionId query parameter. This permanently deletes the version. If the deleted object is a delete marker, Amazon S3 sets the x-amz-delete-marker response header to true.

MFA Delete:

If the bucket has MFA Delete enabled, you must include the x-amz-mfa request header in the DELETE versionId request. Requests with x-amz-mfa must use HTTPS.

MFA delete is not supported by directory buckets.

Deletion Methods:

You can delete objects by explicitly calling DELETE Object or by configuring PutBucketLifecycle to enable Amazon S3 to remove them automatically.

To block users from removing objects, deny them the s3:DeleteObject, s3:DeleteObjectVersion, and s3:PutLifeCycleConfiguration actions.

S3 Lifecycle is not supported by directory buckets.

Permissions:

- General purpose bucket: s3:DeleteObject permission is required. For versioned objects, s3:DeleteObjectVersion is needed. If these permissions are explicitly denied, attempts result in 403 Access Denied.

- Directory bucket: Use CreateSession API for session-based authorization with s3express:CreateSession permission.

Conditional Deletion (Directory Buckets Only):

- If-Match: Deletes the object only if ETag matches. Returns 412 Precondition Failed if not matched. Supports '*' to match any ETag.

- x-amz-if-match-last-modified-time: Deletes only if modification time matches the provided timestamp.

- x-amz-if-match-size: Deletes only if size matches the provided value in bytes.

These conditional headers can be used individually or in conjunction with each other.

| Edit this page View Source

GetAsync(GetObjectRequest, RequestOptions)

Retrieves an object from Amazon S3.

Declaration

public UniTask<S3Object> GetAsync(GetObjectRequest request, RequestOptions options = null)

Parameters

Type	Name	Description
GetObjectRequest	request	The object retrieval request parameters.
RequestOptions	options	Optional REST request options.

Returns

Type	Description
UniTask<S3Object>	The GetObject response with object data and metadata.

Remarks

Request Styles:

- General purpose buckets: Both virtual-hosted-style and path-style requests are supported.

- Directory buckets: Only virtual-hosted-style requests are supported. Requests are sent to the Zonal endpoint: https://bucket-name.s3express-zone-id.region-code.amazonaws.com/key-name

Permissions:

- General purpose bucket: s3:GetObject permission is required for READ access. For versioned objects, s3:GetObjectVersion is needed. If the object doesn't exist and you have s3:ListBucket permission, returns 404 Not Found; without it, returns 403 Access Denied.

- Directory bucket: Use CreateSession API for session-based authorization with s3express:CreateSession permission. For SSE-KMS encrypted objects, kms:GenerateDataKey and kms:Decrypt permissions are required.

Storage Classes:

Objects stored in S3 Glacier Flexible Retrieval, S3 Glacier Deep Archive, S3 Intelligent-Tiering Archive Access, or S3 Intelligent-Tiering Deep Archive Access tiers must be restored using RestoreObject before retrieval. Otherwise, returns InvalidObjectState error.

Directory buckets only support EXPRESS_ONEZONE (S3 Express One Zone) in Availability Zones and ONEZONE_IA (S3 One Zone-Infrequent Access) in Dedicated Local Zones.

Encryption:

Encryption request headers (x-amz-server-side-encryption) should NOT be sent for GetObject requests if your object uses SSE-S3, SSE-KMS, or DSSE-KMS. Including them results in HTTP 400 Bad Request.

Directory buckets only support SSE-S3 and SSE-KMS; SSE-C is not supported.

Response Header Overrides:

You can override response headers using query parameters: response-cache-control, response-content-disposition, response-content-encoding, response-content-language, response-content-type, response-expires.

These parameters require signed requests (Authorization header or presigned URL); anonymous requests cannot use them.

| Edit this page View Source

ListAsync(ListObjectsV2Request, RequestOptions)

Returns some or all (up to 1,000) of the objects in a bucket with each request.

Declaration

public UniTask<ListObjectsV2Response> ListAsync(ListObjectsV2Request request, RequestOptions options = null)

Parameters

Type	Name	Description
ListObjectsV2Request	request	The list objects request parameters.
RequestOptions	options	Optional REST request options.

Returns

Type	Description
UniTask<ListObjectsV2Response>	The ListObjectsV2 response with object metadata.

Remarks

General Purpose Bucket vs Directory Buckets:

- General purpose bucket: Doesn't return prefixes related only to in-progress multipart uploads.

- Directory bucket: Response includes prefixes related to in-progress multipart uploads.

Directory Buckets:

- You must make requests to the Zonal endpoint: https://bucket-name.s3express-zone-id.region-code.amazonaws.com/key-name

- Path-style requests are not supported.

Sorting Order:

- General purpose bucket: Returns objects in lexicographical order based on key names.

- Directory bucket: Does not return objects in lexicographical order.

Permissions:

- General purpose bucket: s3:ListBucket permission is required. Bucket owner has this permission by default and can grant to others.

- Directory bucket: Use CreateSession API for session-based authorization with s3express:CreateSession permission.

Pagination:

Use ContinuationToken from the previous response's NextContinuationToken to continue listing. Response sets IsTruncated to true if more keys are available.

Note: This is ListObjectsV2 (latest revision). For backward compatibility, Amazon S3 continues to support ListObjects (prior version).

| Edit this page View Source

PutAsync(PutObjectRequest, RequestOptions)

Adds an object to a bucket.

Declaration

public UniTask<S3Object> PutAsync(PutObjectRequest request, RequestOptions options = null)

Parameters

Type	Name	Description
PutObjectRequest	request	The object upload request parameters.
RequestOptions	options	Optional REST request options.

Returns

Type	Description
UniTask<S3Object>	The PutObject response with ETag and metadata.

Remarks

Important: Amazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the entire object to the bucket.

You cannot use PutObject to only update a single piece of metadata for an existing object. You must put the entire object with updated metadata if you want to update some values.

Object Ownership:

If your bucket uses the bucket owner enforced setting for Object Ownership, ACLs are disabled and no longer affect permissions. All objects written to the bucket by any account will be owned by the bucket owner.

Directory Buckets:

- You must make requests for this API operation to the Zonal endpoint.

- These endpoints support virtual-hosted-style requests in the format: https://bucket-name.s3express-zone-id.region-code.amazonaws.com/key-name

- Path-style requests are not supported.

Concurrent Writes:

Amazon S3 is a distributed system. If it receives multiple write requests for the same object simultaneously, it overwrites all but the last object written.

Write Protection Options:

- S3 Object Lock: To prevent objects from being deleted or overwritten (not supported for directory buckets).

- If-None-Match: Uploads the object only if the object key name does not already exist in the specified bucket. Expects the * character. Returns 412 Precondition Failed if object exists, 409 ConditionalRequestConflict on conflict.

- S3 Versioning: When enabled, Amazon S3 stores all versions of objects written simultaneously (not supported for directory buckets).

Permissions:

- General purpose bucket: s3:PutObject is required. Additional permissions may be needed for ACLs (s3:PutObjectAcl), Object Lock (s3:PutObjectObjectLockConfiguration, s3:PutBucketVersioning), Object Ownership (s3:PutBucketOwnershipControls), and Block Public Access (s3:PutBucketPublicAccessBlock).

- Directory bucket: Use CreateSession API for session-based authorization with s3express:CreateSession permission. For SSE-KMS encryption, kms:GenerateDataKey and kms:Decrypt permissions are required.

Data Integrity:

- General purpose bucket: Use Content-MD5 header to ensure data is not corrupted traversing the network. Amazon S3 checks the object against the provided MD5 value.

- Directory bucket: Content-MD5 functionality is not supported.

Server-Side Encryption:

- General purpose buckets: Four options - SSE-S3 (Amazon S3 managed keys), SSE-KMS/DSSE-KMS (AWS KMS keys), SSE-C (customer-provided keys), or no encryption.

- Directory buckets: Only SSE-S3 (AES256) and SSE-KMS (aws:kms) are supported. Encryption settings must match the bucket's default encryption and CreateSession request.

Implements

ICrudService

Extension Methods

ArrayExtensions.ToArrayOrEmpty<T>(T)

ArrayExtensions.ToArrayOrNull<T>(T)

EventExtensions.ToDelta<T>(T, string, int, string, bool)

EventExtensions.ToDone<T>(T, string, int, string)

EventExtensions.ToEvent<T>(T)

EventExtensions.UpcastDelta<T1, T2>(T1, string, int, string, bool)

FallbackExtensions.IsOr<TParent, TChild>(TParent, TChild)

ResponseCastingExtensions.GetResult<T>(T)

SystemExtensions.GetName(object)