Storing an object

Content Platform Tenant Management
Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP PUT method to store an object in a bucket. To store an object, you need write permission for the bucket.

For a request to store an object, the request body consists of the data in a specified file. This data becomes the object content.

When you store an object, you specify a name for it. The object name does not need to be the same as the name of the file containing the original data.

If versioning is enabled and you try to store an object with the same name as an existing object, HCP creates a new version of the object. If versioning is disabled and you try to store an object with the same name as an existing object, HCP returns a 409 (Conflict) status code and does not store the object.

You can add custom metadata to an object in the same request as you use to store the object. To do this, you use x-amz-meta- headers.

You can specify an ACL for an object in the same request as you use to store the object. To do this, you use an ACL header. You cannot use an ACL request body when storing an object.

If the ACL you specify in a request to store an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not store the object.

If you are an authenticated user, when you store an object, you become the object owner. If you are accessing the bucket anonymously, the new object has no owner.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to store an object has either of these formats:

  • With the bucket name included in the hostname:
    PUT /object-name HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name/object-name HTTP/1.1

Required headers

The next list describes the headers you can use in a request to store an object.

Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the data being stored.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.
Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the Date header above.

Optional headers

Content-MD5
Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.
When you store an object, you can use the Content-MD5 request header to ensure the integrity of the object data. The value you specify for this header must be the Base64-encoded MD5 hash of the original file data.
When you include the Content-MD5 header in a request to store an object, HCP calculates the Base64-encoded MD5 hash of the data it receives and compares that to the header value. If the values don’t match, HCP returns a 400 (Bad Request) status code and does not store the object.
Content-Type
Specifies the Internet media type of the data being stored. Valid values are Internet media types (for example, text/plain, application/xml, or image/jpeg).
Expect
Tells the application not to send the request body if the request headers are rejected. The only valid value is 100-continue. This value is not case sensitive.
You can use the Expect request header in a request to store an object to tell the application not to send the request body (the data) to HCP if the request headers are rejected. This prevents unnecessary network bandwidth usage.
x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.
x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.
x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.
x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.
x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.
x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.
x-amz-meta-
Adds custom metadata to the object.
x-amz-object-lock-mode
Specify the Object Lock mode status for an object. The value can be either GOVERNANCE or COMPLIANCE.
GOVERNANCE
Use for objects that are subject to retention policies that are governed by a regulatory body.
COMPLIANCE
Use for objects that are subject to strict regulatory requirements.
Example
x-amz-object-lock-mode: GOVERNANCE
x-amz-object-lock-retain-until-date
Specify the date and time until which an object must be retained. The date and time must be in YYYY-MM-DDTHH:MM:SSZ format, where YYYY represents the year, MM represents the month, DD represents the day, T represents the time separator, HH represents the hour in 24-hour format, MM represents the minute, SS represents the second and Z represents the time zone.
Example
x-amz-object-lock-retain-until-date: 2023-03-30T00:00:00Z
x-amz-object-lock-legal-hold
Specify the Legal hold status of an object version. Valid values are ON and OFF.
ON
You cannot delete the object version until you remove the legal hold status.
OFF
You can overwrite or delete the object version.
Example
x-amz-object-lock-legal-hold: ON
x-amz-server-side-encryption
Requests that the response headers include x-amz-server-side-encryption, which indicates whether objects stored in HCP are encrypted. The value of the x-amz-server-side-encryption request header can be any character string.
When you store an object, you can use the x-amz-server-side-encryption request header to determine whether objects stored in HCP are encrypted. If stored objects are encrypted, the response headers include x-amz-server-side-encryption with a value representing the encryption algorithm and key length HCP is using. If stored objects are not encrypted, the value of the x-amz-server-side-encryption response header is None.
x-hcp-labelretentionhold
Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold value pairs. This is supported only on namespaces that are configured to use the HCP retention mode.
id
Unique label name. The maximum label size is 64 characters.
hold
Either true or false.
Example
x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, 
{"id":"UniqueLabelHold-2","hold":true}]
x-hcp-retention
Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value. This is supported only on namespaces that are configured to use the HCP retention mode.
x-hcp-retentionhold
Specifies whether the object is on hold. This value can be either true or false. This is supported only on namespaces that are configured to use the HCP retention mode.

Response headers

The next list describes the headers returned in response to a successful request to store an object.

Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always 0 (zero).
Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT
ETag
Specifies the ETag for the object.
ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.
x-amz-server-side-encryption
Specifies whether objects stored in HCP are encrypted. Possible values are:
  • If objects are encrypted, AES256
  • If objects are not encrypted, None
This header is returned only if the request headers include x-amz-server-side-encryption.
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Status codes

The next table describes HTTP status codes that can be returned in response to a request to store an object.

Code Meaning Description
200 OK

Possible reasons include:

  • HCP successfully stored the object.
  • The application attempts to set a labeled hold on an object with an HCP version earlier than 9.1.
  • The application puts the same labeled hold ID on the same object multiple times.
  • The application attempts to remove a nonexistent labeled hold ID from an object.
400 Bad Request

Possible reasons include:

  • An ACL grant header specifies an invalid grantee.
  • The value specified by the Content-MD5 header does not match the Base64-encoded MD5 hash of the data HCP received.
  • The labeled hold ID length exceeds 64 characters.
  • A label hold ID must have at least one character.
  • The request contains over 100 labeled holds.
  • The active labeled hold limit exceeds 100 labels.
  • A request cannot specify the same labeled hold ID as both active and inactive.
  • The request must specify the labeled hold id and hold values.
  • To use the labeled hold feature, an online upgrade is required to HCP 9.1 or later.
403 Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to store objects in the specified bucket.
  • An object with the specified name already exists in the specified bucket, and versioning is enabled for that bucket, but the existing object is under retention or on hold.
  • The application tried to delete an object on labeled hold.
  • The S3 compatible API is currently disabled for the specified bucket.
404 Not Found

Possible reasons include:

  • The specified bucket or object does not exist.
  • The specified object ID is invalid or the object does not exist.
409 Conflict

One of these:

  • An object with the specified name already exists in the specified bucket, and versioning is disabled for the bucket.
  • A folder with the specified name already exists in the specified bucket.
411 Length Required Either the request does not include a Content-Length header, or the request includes a Content-Length header with no value.
413 Request Entity Too Large The object you are trying to store is too big for the amount of remaining space in the bucket.
500 Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.
501 Not Implemented The request includes the x-amz-acl header with an invalid value.
503 Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Storing an object

Here is a sample PUT request that stores an object named quarterly_rpts/Q4_2019.ppt in the finance bucket. In this example, the retention value of the object is set to five days past the time when the object was stored.

The example also shows the response headers HCP returns while versioning is enabled for the bucket and while versioning is disabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --put=/quarterly_rpts/Q4_2019.ppt -- -k
     "https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt"
     -H "x-hcp-retention: A+5d"

Request headers

PUT /quarterly_rpts/Q4_2019.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 20 Jan 2017 17:19:26 +0000
Authorization: AWS bGdyZWVu:HbkRBWvyO3YQO55Bm0VS3RMatvg=
Content-Length: 235813
x-hcp-retention: A+5d

Response headers with versioning enabled

HTTP/1.1 200 OK
Date: Fri, 20 Jan 2017 17:19:26 GMT
x-amz-version-id: 87288727469825
ETag: "617e8ef649d40cda1f7f3ca81c97a06a"
Content-Length: 0

Response headers with versioning disabled

HTTP/1.1 200 OK
Date: Fri, 20 Jan 2017 17:19:26 GMT
ETag: "617e8ef649d40cda1f7f3ca81c97a06a"
Content-Length: 0

Storing an object with a labeled hold

Here is a sample PUT request that stores and places a labeled hold on an object named quarterly_rpts/Q4_2019.ppt in the finance bucket.

The user ID, lgreen, has privileged data access permission.

Request with s3curl command line

./s3curl.pl --id=lgreen --put=/quarterly_rpts/Q4_2019.ppt -- -v -k
     "https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt"
      -H  'x-hcp-labelretentionhold: [{"id":"UniqueLabelHold-1","hold":true}]'

Request headers

PUT /quarterly_rpts/Q4_2019.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Date:  Fri,12 Jun 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:HbkRBWvyO3YQO55Bm0VS3RMatvg=
X-HCP-Retention: 0
X-HCP-RetentionHold: true
X-HCP-LabelRetentionHold: true
Content-Length: 235813

Response headers 

HTTP/1.1 200 OK
Date:  Fri, 12 Jun 2020 17:19:26 GMT
ETag:  "617e8ef649d40cda1f7f3ca81c97a06a"
Content-Length:  0

Example: Storing an object with custom metadata and an ACL

Here is a sample PUT request that stores an object named hum_res/budget_proposals/BudgProp-2020 in the finance bucket, for which versioning is disabled. The object is stored with custom metadata specified by three x-amz-meta- headers and a canned ACL specified by the x-amz-acl header.

Request with s3curl command line

./s3curl.pl --id=lgreen --put=/hum_res/budget_proposals/BudgProp-2020 -- -k
     "https://finance.europe.hcp.example.com/hum_res/budget_proposals/
             BudgProp-2020" -H "x-amz-meta-author: P.D. Grey"
     -H "x-amz-meta-author: Morgan White" -H "x-amz-meta-author: Paris Black"
     -H "x-amz-acl: authenticated-read"

Request headers

PUT /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Wed, 16 Nov 2016 23:29:17 +0000
Authorization: AWS bGdyZWVu:FiWxioJHDGMLyP0WkCuqUpRqr2w=
x-amz-meta-author: P .D. Grey
x-amz-meta-author: Morgan White
x-amz-meta-author: Paris Black
x-amz-acl: authenticated-read
Content-Length: 881932

Response headers

HTTP/1.1 200 OK
Date: Wed, 16 Nov 2016 23:29:17 GMT
ETag: "76216527ff2f6219f7c29251a619c8db"
Content-Length: 0