Pre-Authenticated Request Object URLs in Object Storage
Use a tool such as curl to read and write data using the pre-authenticated requests for an object.
- The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, isn't stored in Object Storage, and can't be retrieved later.
- The URL generated when you create a pre-authenticated request for an object with a prefix doesn't contain the prefix by default. The user must manually add the prefix to the URL to access the object.
Using the unique request URL, you can use a tool such as curl to read and write data using the pre-authenticated request. Object Storage now supports writing large files using multipart uploads with pre-authenticated requests.
Putting an Object
$ curl -X PUT --data-binary '@local_filename' unique_PAR_URL
For example:
$ curl -X PUT --data-binary '@using-dita-guide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/using-dita-guide.pdf
Putting an Object with Custom Metadata
You can also provide custom metadata for any object using opc-meta-name:value
headers.
$ curl -X PUT -H "opc-meta-name:value" --data-binary '@local_filename' unique_PAR_URL
For example:
$ curl -X PUT -H "opc-meta-version:2020May" PUT --data-binary '@CorporateTerminologyUsageGuide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/71LzRt_V8LVT7BVLbeQOB5KAx67AxzeKXwJ8mIA5dN0WheYH39a7KiY2UXnUBhaX/n/MyNamespace/b/MyParBucket/o/CorporateTerminologyUsageGuide.pdf
Putting a Large Object
Multipart uploads accommodate objects that are too large for a single upload operation. We recommend that you use multipart uploads to upload objects larger than 100 MiB. The maximum size for an uploaded object is 10 TiB. Object parts must be no larger than 50 GiB. Using multipart uploads, you have the flexibility of pausing between the uploads of individual parts, and resuming the upload when your schedule and resources allow.
Step 1: To direct Object Storage to create a multipart upload, include the header opc-multipart: true
in the PUT
command.
$ curl -X PUT -H "opc-multipart:true" unique_PAR_URL
For example:
$ curl -X PUT -H "opc-multipart:true" https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
PUT
with the opc-multipart: true
header returns an
access URI to use to upload parts and commit the multipart upload, for example:
{"namespace":"MyNamespace","bucket":"MyParBucket","object":"OCI_User_Guide.pdf","uploadId":"b5bb4079-9d50-ac59-182e-4d133a962382","timeCreated":"2021-03-05T14:48:53.738Z","storageTier":"Standard","accessUri":"/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/"}
Step 2: Use the access URI together with the Object Storage hostname for the target region to upload parts, specifying the part number at the end of the URI. For example, to upload an object in three parts, issue the following PUT
commands:
$ curl -X PUT --data-binary '@data.1' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/1
$ curl -X PUT --data-binary '@data.2' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/2
$ curl -X PUT --data-binary '@data.3' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/3
Step 3: To commit the multipart upload, use the POST
command with
the access URI. For example:
$ curl -X POST https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/
You can delete all parts of an uncommitted or failed multipart upload using the
DELETE
command with the access URI. For example:
$ curl -X DELETE https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/
You can also provide custom metadata for any object using opc-meta-
headers. The "
is only needed on the first pre-authenticated request that creates the multipart upload, not on each individual part. See Putting an Object with Custom Metadata for more information.-H opc-meta-name:value
"
Getting an Object
$ curl -X GET unique_PAR_URL
For example:
$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
'@data.1''@data.2''@data.3'
Getting a List of Objects
For pre-authenticated requests that apply to several objects, the request creator can optionally let you list objects.
$ curl -X GET unique_PAR_URL
For example:
$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"InfoWorld DeepDive - Tips for Git and GitHub Users.pdf"},{"name":"OCI_User_Guide.pdf"},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},{"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},{"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},{"name":"services.html"},{"name":"udx-1494-lifecycle-rule-glob.pdf"}]}
By default, the object list returns only the names of the objects. Optionally, you can
use the fields
query parameter to also include the
size
(object size in bytes), etag
,
md5
, timeCreated
(object creation date and time),
timeModified
(object modification date and time),
storageTier
, and archivalState
fields. Specify the
value of this parameter as a comma-separated, case-insensitive list of those field names
that you want to include in the object list. For example:
$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/?fields="name,etag,timeCreated,md5,timeModified,storageTier,archivalState"
{"objects":[{"name":"InfoWorld DeepDive - Tips for Git and GitHub Users.pdf","timeCreated":"2021-04-01T14:27:13.039Z","timeModified":"2021-04-01T14:27:27.552Z","etag":"e5032a35-07d7-476f-88aa-a95c5d07f0d9","storageTier":"Standard","md5":"3OPjerv2zKJdf9fzFeP9BQ=="},{"name":"OCI_User_Guide.pdf","timeCreated":"2021-04-01T14:27:20.359Z","timeModified":"2021-04-02T23:18:01.299Z","etag":"0dd28308-b821-47e7-9685-111eedef1c5c","storageTier":"Standard","md5":"/2+fTemSy7CsR00OnFK87Q=="},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf","timeCreated":"2021-04-01T14:27:12.228Z","timeModified":"2021-04-01T14:27:21.302Z","etag":"1948d01b-9611-4a79-a9dd-f5b24888c0bc","storageTier":"Standard","md5":"JIdR+kCzQNkl0riH08Ktpw=="},{"name":"VPN.png","timeCreated":"2021-04-01T14:27:11.943Z","timeModified":"2021-04-01T14:27:12.047Z","etag":"b4f20050-e268-42e5-8980-29f6a972b6bf","storageTier":"Standard","md5":"aWFjq5fe+hsDT/x5cWhasA=="},{"name":"eventslogreference.htm","timeCreated":"2021-04-01T14:27:10.725Z","timeModified":"2021-04-01T14:27:10.746Z","etag":"84362592-0a18-438d-8773-7dcc702103aa","storageTier":"Standard","md5":"As+3syaEbvMhPm8fM+DSAw=="},{"name":"functionslogreference.htm","timeCreated":"2021-04-01T14:27:10.865Z","timeModified":"2021-04-01T14:27:10.900Z","etag":"4d494efa-5d48-491a-84ba-254be2aa8549","storageTier":"Standard","md5":"lt28WcIiqKklMS5p2LbECQ=="},{"name":"glob.txt","timeCreated":"2021-04-05T16:12:31.925Z","timeModified":"2021-04-05T16:12:31.952Z","etag":"c330ce8c-4c61-4342-9ac5-4bc0fd846944","storageTier":"Standard","md5":"BeMbbI+uOOGzmFA/NXwwxQ=="},{"name":"loadbalancerreference.htm","timeCreated":"2021-04-01T14:27:11.480Z","timeModified":"2021-04-01T14:27:11.574Z","etag":"522a3b1d-f736-4e30-9b5d-feed3867912d","storageTier":"Standard","md5":"u2GP2ngLVEq9xUAykRg2ug=="},{"name":"objectstoragelogreference.htm","timeCreated":"2021-04-01T14:27:11.416Z","timeModified":"2021-04-01T14:27:11.479Z","etag":"fbf7a035-7b80-4c91-a932-53bf0917bef9","storageTier":"Standard","md5":"skstBGw3YcHBomI6X/YwEA=="},{"name":"servicechanges.html","timeCreated":"2021-04-01T14:27:11.702Z","timeModified":"2021-04-01T14:27:11.716Z","etag":"016df222-128d-4e7f-a191-b5c0a5dbc7e0","storageTier":"Standard","md5":"sVzYaODHww3Qw1jwbtj7SA=="},{"name":"servicediscovery.dita","timeCreated":"2021-04-02T17:16:04.134Z","timeModified":"2021-04-02T17:16:04.149Z","etag":"7997226d-e2ba-460a-be75-97436dcb30e8","storageTier":"Standard","md5":"I/ZjF5rcoaJXH6abpbDPag=="},{"name":"serviceessentials.html","timeCreated":"2021-04-01T14:27:11.700Z","timeModified":"2021-04-01T14:27:11.737Z","etag":"687d0914-19c7-4ff6-8ceb-90ab0bbd1fc1","storageTier":"Standard","md5":"HSf0uMVHxFCuVr/I5insxQ=="},{"name":"servicelogreference.htm","timeCreated":"2021-04-01T14:27:11.767Z","timeModified":"2021-04-01T14:27:11.775Z","etag":"240f2d71-da38-461c-a821-506b85b7e6e7","storageTier":"Standard","md5":"jxyWxK9z8OW0zsozadNRkQ=="},{"name":"services.html","timeCreated":"2021-04-01T14:27:11.780Z","timeModified":"2021-04-01T14:27:11.913Z","etag":"6e570928-a5b2-4e49-8e54-22186825350a","storageTier":"Standard","md5":"fDuH2Y7LDAafjlyUCQZohQ=="},{"name":"udx-1494-lifecycle-rule-glob.pdf","timeCreated":"2021-04-01T14:27:12.044Z","timeModified":"2021-04-01T14:27:12.686Z","etag":"a92174a2-cad3-4239-b4c9-48f2abd4dd8c","storageTier":"Standard","md5":"4ltcJZgQ80sNz8RHu7TJlQ=="}]}
In addition to fields
, pre-authenticated requests support all other
ListObjects query
parameters and list pagination.
Getting Metadata from an Object
$ curl --head unique_PAR_URL
For example:
$ curl --head https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
HTTP/1.1 200 OK
accept-ranges: bytes
Content-Length: 27
opc-multipart-md5: AgQlttlYM7ya/tH0Fosu9A==-3
last-modified: Fri, 05 Mar 2021 15:15:44 GMT
etag: 9b9093ab-bdc6-49af-b261-b2d1d111d952
version-id: d3346446-e1f3-46e3-97e5-ee3c8e57ee30
storage-tier: Standard
Content-Type: application/x-www-form-urlencoded
date: Thu, 18 Mar 2021 22:11:11 GMT
opc-request-id: phx-1:odm8FLV-LC7yR7sskUL955sjFjOqaKrQ-cO3JbGhSbcwYcovlRa2QtABQPfeW_Q_
x-api-id: native
access-control-allow-origin: *
access-control-allow-methods: POST,PUT,GET,HEAD,DELETE,OPTIONS
access-control-allow-credentials: true
access-control-expose-headers: accept-ranges,access-control-allow-credentials,access-control-allow-methods,access-control-allow-origin,content-length,content-type,date,etag,last-modified,opc-client-info,opc-multipart-md5,opc-request-id,storage-tier,version-id,x-api-id
Getting an Object with Custom Response Headers
You can override the response headers in the PAR GET requests by using the following query parameters:
-
httpResponseContentDisposition
-
httpResponseCacheControl
-
httpResponseContentType
-
httpResponseContentLanguage
-
httpResponseContentEncoding
-
httpResponseExpires
For example:
Default URL (shows inline) - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt
Download and save with default filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment
Download and save with custom filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment%3B%20filename%3Ddownload.txt