Jump to

• Request
• Response
• Examples

Get object content and metadata

get

/v1/{account}/{container}/{object}

Downloads the object content and gets the object metadata.

Request

Path Parameters

• account: string
  The unique name for the account. An account is also known as the project or tenant.
• container: string
  The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
• object: string
  The unique name for the object.

Query Parameters

• multipart-manifest(optional): string
  If you include the multipart-manifest=get query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the X-Object-Manifest response header for dynamic large objects or in the response body for static large objects.
• temp_url_expires: integer(timestamp)
  Minimum Value: 0

  The date and time in UNIX Epoch time stamp format when the signature for temporary URLs expires.

  For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

• temp_url_sig: string
  Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL.

Header Parameters

• If-Match(optional): string
  For usage details, see RFC2616.
• If-Modified-Since(optional): string(date)
  For usage details, see RFC2616.
• If-None-Match(optional): string
  In combination with Expect: 100-Continue, specify an If-None-Match: * header to query whether the server already has a copy of the object before any data is sent.
• If-Unmodified-Since: string(date)
  For usage details, see RFC2616.
• Range(optional): string
  The ranges of content to get.

  You can use the Range header to get portions of data by using one or more range specifications. To specify many ranges, separate the range specifications with a comma.

  The types of range specifications are:

  • Byte range specification. Use FIRST_BYTE_OFFSET to specify the start of the data range, and LAST_BYTE_OFFSET to specify the end. You can omit the LAST_BYTE_OFFSET and if you do, the value defaults to the offset of the last byte of data.
  • Suffix byte range specification. Use LENGTH bytes to specify the length of the data range.

  The following forms of the header specify the following ranges of data:

  • Range: bytes=-5. The last five bytes.
  • Range: bytes=10-15. The five bytes of data after a 10-byte offset.
  • Range: bytes=10-15,-5. A multi-part response that contains the last five bytes and the five bytes of data after a 10-byte offset. The Content-Type response header contains multipart/byteranges.
  • Range: bytes=4-6. Bytes 4 to 6 inclusive.
  • Range: bytes=2-2. Byte 2, the third byte of the data.
  • Range: bytes=6-. Byte 6 and after.
  • Range: bytes=1-3,2-5. A multi-part response that contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The Content-Type response header contains multipart/byteranges.

• X-Auth-Token(optional): string
  Authentication token. Not specified if temp_url_sig and temp_url_expires are present. Otherwise, if you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
• X-Newest(optional): boolean
  If set to true, Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Success

Headers

• Accept-Ranges: string
  The type of ranges that the object accepts.
• Content-Disposition: string
  (Optional) If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.

  If not set, this header is not returned by this operation.

• Content-Encoding: string
  (Optional) If set, the value of the Content-Encoding metadata.

  If not set, the operation does not return this header.

• Content-Length: integer
  Minimum Value: 0

  The length of the object content in the response body, in bytes.
• Content-Type: string
  The MIME type of the object.
• Date: string(date-time)
  The transaction date and time.

  The date and time stamp format is ISO 8601:

  CCYY-MM-DDThh:mm:ss±hh:mm

  For example, 2015-08-27T09:49:58-05:00.

  The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

  A null value indicates that the token never expires.

• ETag: string
  For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted.

  For manifest objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was downloaded. Also the value is enclosed in double-quote characters.

  You are strongly recommended to compute the MD5 checksum of the response body as it is received and compare this value with the one in the ETag header. If they differ, the content was corrupted, so retry the operation.

• Last-Modified: string(date-time)
  The date and time when the object was created or its metadata was changed.

  The date and time stamp format is ISO 8601:

  CCYY-MM-DDThh:mm:ss±hh:mm

  For example, 2015-08-27T09:49:58-05:00.

  The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00

• X-Delete-At: integer(timestamp)
  Minimum Value: 0

  (Optional) If set, the date and time in UNIX Epoch time stamp format when the system deletes the object.

  For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

  If not set, this operation does not return this header.

• X-Object-Manifest: string
  (Optional) If set, to this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix.
• X-Object-Meta-{name}: string
  The custom object metadata item, where {name} is the name of the metadata item.

  One X-Object-Meta-{name} response header appears for each metadata {name} item.

• X-Static-Large-Object: boolean
  Set to True if this object is a static large object manifest object.
• X-Timestamp: string(timestamp)
  The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version.

  For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

• X-Trans-Id: string(uuid)
  A unique transaction ID for this request. Your service provider might need this value if you report a problem.
• X-Worm-Expiration-At: integer
  Minimum Value: 0

  (Optional) The Epoch time that an uploaded object must exist until it can be deleted. The value will be greater than the current Epoch time.

206 Response

Partial Content. The server is delivering only part of the resource (byte serving) due to a range header sent by the client.

Headers

• Accept-Ranges: string
  The type of ranges that the object accepts.
• Content-Disposition: string
  (Optional) If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.

  If not set, this header is not returned by this operation.

• Content-Encoding: string
  (Optional) If set, the value of the Content-Encoding metadata.

  If not set, the operation does not return this header.

• Content-Length: integer
  Minimum Value: 0

  The length of the object content in the response body, in bytes.
• Content-Type: string
  The MIME type of the object.
• Date: string(date-time)
  The transaction date and time.

  The date and time stamp format is ISO 8601:

  CCYY-MM-DDThh:mm:ss±hh:mm

  For example, 2015-08-27T09:49:58-05:00.

  The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

  A null value indicates that the token never expires.

• ETag: string
  For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted.

  For manifest objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was downloaded. Also the value is enclosed in double-quote characters.

  You are strongly recommended to compute the MD5 checksum of the response body as it is received and compare this value with the one in the ETag header. If they differ, the content was corrupted, so retry the operation.

• Last-Modified: string(date-time)
  The date and time when the object was created or its metadata was changed.

  The date and time stamp format is ISO 8601:

  CCYY-MM-DDThh:mm:ss±hh:mm

  For example, 2015-08-27T09:49:58-05:00.

  The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00

• X-Delete-At: integer(timestamp)
  Minimum Value: 0

  (Optional) If set, the date and time in UNIX Epoch time stamp format when the system deletes the object.

  For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

  If not set, this operation does not return this header.

• X-Object-Manifest: string
  (Optional) If set, to this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix.
• X-Object-Meta-{name}: string
  The custom object metadata item, where {name} is the name of the metadata item.

  One X-Object-Meta-{name} response header appears for each metadata {name} item.

• X-Static-Large-Object: boolean
  Set to True if this object is a static large object manifest object.
• X-Timestamp: string(timestamp)
  The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version.

  For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

• X-Trans-Id: string(uuid)
  A unique transaction ID for this request. Your service provider might need this value if you report a problem.
• X-Worm-Expiration-At: integer
  Minimum Value: 0

  (Optional) The Epoch time that an uploaded object must exist until it can be deleted. The value will be greater than the current Epoch time.
• X-Worm-Expiration-Days: integer
  Minimum Value: 0

  Minimum Value: > true

  (Optional) The number of days that an uploaded object must exist until it can be deleted.

400 Response

Must retrieve an archived object before downloading it.

Headers

• Content-Length: integer
  Minimum Value: 0

  The length of the error text in the response body.
• Content-Type: string
  The MIME type of the error text in the response body.

401 Response

Request does not include an authentication token, or authentication token specified in the request is not valid. It may have expired. Authentication tokens expire after 30 minutes.

Headers

• Content-Length: integer
  Minimum Value: 0

  The length of the error text in the response body.
• Content-Type: string
  The MIME type of the error text in the response body.

403 Response

Forbidden. Possible causes:

• A data center has not been selected for your service in Oracle Cloud My Services.
• The request was sent to an incorrect data center. For example, the data center for your service is Chicago (us2), but the request was sent to the URL corresponding to the Ashburn (us6) data center.
• You don't have the required permission to perform the operation on the specified container. For example, there may be a change in the roles assigned to your user or the access privileges defined for the container specified in the request.
• The specified operation is not permitted for archive objects or containers with storage class Archive
• Violating a container or object level WORM policy by trying to PUT, POST, or DELETE an object that has not expired or trying to update an existing container level WORM policy.

Headers

• Content-Length: integer
  Minimum Value: 0

  The length of the error text in the response body.
• Content-Type: string
  The MIME type of the error text in the response body.

404 Response

The object does not exist or has just been created and hasn't been replicated across all three nodes.

Headers

• Content-Length: integer
  Minimum Value: 0

  The length of the error text in the response body.
• Content-Type: string
  The MIME type of the error text in the response body.

416 Response

Returned for any ranged GET requests that specify more than:

• Fifty ranges
• Three overlapping ranges
• Eight non-increasing ranges

Headers

• Content-Length: integer
  Minimum Value: 0

  The length of the error text in the response body.
• Content-Type: string
  The MIME type of the error text in the response body.

Back to Top

Examples

cURL Command

The following example shows how to download an object from a container in your account in Oracle Cloud Infrastructure Object Storage Classic by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

curl -v -X GET \
     -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
     -o myFile.txt \
     https://foo.storage.oraclecloud.com/v1/myservice-bar/FirstContainer/myObject

Sample Response

The following is a sample response of this command:

HTTP/1.1 200 OK
Date: Mon, 09 Mar 2015 11:34:33 GMT
Content-Length: 23
Accept-Ranges: bytes
Last-Modified: Mon, 09 Mar 2015 11:26:58 GMT
Content-Type: application/octet-stream
X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
Etag: 846fa9d298be05e5f598703f0c3d6f51
X-Timestamp: 1425900417.95553
Content-Language: en

Back to Top