Accessing Endpoints to Manage Files in Object Storage
A Public Wrapper API over the Object Storage that has a built-in virus scanning ability is been available to perform various actions on Object Storage.
The following terms are used in Table 3-1:
-
PAR: a pre-authenticated request used to upload or download files. This is valid only for a limited duration and is set to five minutes.
-
Storage Prefix: Object Storage is a flat storage area and does not include the concept of directories. Storage prefix is a prefix for a file that imitates a directory structure.
For example, planning/incoming is prefixed to a filename to provide a more readable and distinguishable name.
Before accessing the APIs, an OCI IAM token must be generated. This token is passed in the request header for authentication.
curl -i -u "<IDCS-client-id>":"<IDCS-client-secret>" \ https://<idcs-tenant-id>.<IDCS_URL> \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Host: <idcs-tenant-id>.<IDCS_URL>' \ -d 'grant_type=client_credentials' -d 'scope=urn:opc:idm:__myscopes__'
Table 3-1 API Endpoints
Action | Endpoint | Payload | Response | Details |
---|---|---|---|---|
Get PAR (pre-authenticated requests) for upload of files |
/uploadFiles |
[ { "storagePrefix": "string", "fileName": "string" }, ...] |
PAR URI |
This endpoint is used to generate PARs, which are then used to upload files. Data: { "listOfFiles": [{ "storagePrefix": "<subnamespace>/planning/incoming/input", "fileName": "prod.csv.dat" }, { "storagePrefix": "<subnamespace>/planning/incoming/config", "fileName": "RetailHomeConfig.json" }] } Command: curl -X POST "<url>/<BucketName>/uploadFiles" \ -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \ -d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\" \<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}" |
Response 200: { "parList": [{ "id": "WhmJ1Jn6v1GufaHDVISg2sUyiOLEoDAG3rWGUp1J/yj7NgvpJtf77q6Qehsz9h9R:<subnamespace>/planning/incoming/input/prod.csv.dat", "name": "prod.csv.dat", "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/oKDbsdO0T3LsfEWgys5WMD85DOyB7W4AvNK_lYXGtVMkGobebU6NIdvuz5AqrtO4/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/input/prod.csv.dat", "objectName": "<subnamespace>/planning/incoming/input/prod.csv.dat", "accessType": "ObjectWrite", "timeExpires": 1629914865691, "timeCreated": 1629914565988 }, { "id": "I0zDNVNqpQG8KEgGoJokViRIZ6yAQNX7haWIvBfDME+UabAShOhVu7zNvmERkZLm:<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "name": "RetailHomeConfig.json", "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/Oja49u66xQqkzgOC6i5GA1PooED1XQV2bsnDwurqKbwetAnqX1RzVb4-e1mPiWWs/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "objectName": "<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "accessType": "ObjectWrite", "timeExpires": 1629914866213, "timeCreated": 1629914566301 }] } Files can then be uploaded using the generated PARs (accessURI in the response). curl --request PUT --data-binary <File> <PAR> |
||||
Get PAR for download of files |
/downloadFiles |
[ { "storagePrefix": "string", "fileName": "string" }, ...] |
PAR URI |
This endpoint is used to generate PARs, which are then used to download files. Data: { "listOfFiles": [{ "storagePrefix": "<subnamespace>/planning/incoming/input", "fileName": "prod.csv.dat" }, { "storagePrefix": "<subnamespace>/planning/incoming/config/", "fileName": "RetailHomeConfig.json" }] } Command: curl -X POST "<url>/<BucketName>/downloadFiles" \ -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \ -d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\" \<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}" |
Response 200: { "parList": [{ "id": "SMINYf9O09IQmfkIxb8gHb0oRN2VrgAD88knbvo3pcNvvrNEhG8btWlPOdnfcLRG:<subnamespace>/planning/incoming/input/prod.csv.dat", "name": "prod.csv.dat", "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/M7JSr6Jp4up_XnVgib6xXqCuc17YHoWZDVzwGmt1x76_sqIRTQGHS3X_5aMar2HV/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/input/prod.csv.dat", "objectName": "<subnamespace>/planning/incoming/input/prod.csv.dat", "accessType": "ObjectRead", "timeExpires": 1629916720360, "timeCreated": 1629916420483 }, { "id": "8Jtqp6T2g3k+1KY9RhO9D7Kftmm5OBn6PIhCzxIQAH9jbvyQmi54SNoXuEzx0eqM:<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "name": "RetailHomeConfig.json", "accessUri": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/5wvRsj2D00nRkjX7-IMZoo9xOSRkMJUM37yyy4wKL1PKwTpdgQ8BWQKlg_jHXnrh/n/oraclegbudevcorp/b/<BucketName>/o/<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "objectName": "<subnamespace>/planning/incoming/config/RetailHomeConfig.json", "accessType": "ObjectRead", "timeExpires": 1629916720632, "timeCreated": 1629916420742 }] } Files can then be downloaded using the generated PARs (accessURI in the response). curl --request GET <PAR> --output <file> |
||||
Delete Files |
/deleteFiles |
[ { "storagePrefix": "string", "fileName": "string" }, ...] |
Status: ok/error per file |
This endpoint is used to delete files from Object Storage. Data: { "listOfFiles": [{ "storagePrefix": "<subnamespace>/planning/incoming/input", "fileName": "prod.csv.dat" }, { "storagePrefix": "<subnamespace>/planning/incoming/config/", "fileName": "RetailHomeConfig.json" }] } Command: curl -X DELETE "<url>/<BucketName>/deleteFiles" \ -H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \ -d "{\"listOfFiles\":[{\"storagePrefix\":\"<subnamespace>/planning/incoming/input\",\"fileName\":\"prod.csv.dat\"},{\"storagePrefix\":\"<subnamespace>/planning/incoming/config/\",\"fileName\":\"RetailHomeConfig.json\"}]}" |
Response 200: { "filesDeleted": [{ "filePath": { "storagePrefix": "<subnamespace>/planning/incoming/input", "fileName": "prod.csv.dat" }, "responseMessage": "File successfully deleted <subnamespace>/planning/incoming/input/prod.csv.dat" }, { "filePath": { "storagePrefix": "<subnamespace>/planning/incoming/config/", "fileName": "RetailHomeConfig.json" }, "responseMessage": "File successfully deleted <subnamespace>/planning/incoming/config/RetailHomeConfig.json" }], "filesFailedDeletion": [] } |
||||
Move/Rename Files |
/moveFiles |
[ { currentPath: { "storagePrefix": "string", "fileName": "string" }, newPath: { "storagePrefix": "string", "fileName": "string" } }, ...] |
Status: ok/error per file |
This endpoint is used to move files within Object Storage. Data: { "listOfFiles": [{ "currentPath": { "storagePrefix": "<subnamespace>/planning/incoming/input2", "fileName": "prod.csv.dat" }, "newPath": { "storagePrefix": "<subnamespace>/planning/incoming/config1/", "fileName": "prod.csv.dat" } }] } Command: curl -X POST "<url>/<BucketName>/movefiles" \ -H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" -H "Content-Type: application/json" \ -d "{\"listOfFiles\":[{\"currentPath\":{\"storagePrefix\":\"<subnamespace>/planning/incoming/input2\",\"fileName\":\"prod.csv.dat\"},\"newPath\":{\"storagePrefix\":\"<subnamespace>/planning/incoming/config1/\",\"fileName\":\"prod.csv.dat\"}}]}" |
Response: { "failedMove": [], "successfulMove": [{ "moveFile": { "currentPath": { "storagePrefix": "<subnamespace>/planning/incoming/input2", "fileName": "prod.csv.dat" }, "newPath": { "storagePrefix": "<subnamespace>/planning/incoming/config1/", "fileName": "prod.csv.dat" } }, "responseMessage": "Successfully moved." }] } |
||||
List storage prefixes |
/listStoragePrefixes |
{ "storagePrefix": "string", "fileNameStartsWith": "optional_string" } |
Storage prefix name, Size, Number of files |
This endpoint is used to list Storage Prefixes in Object Storage. Allows customer to discover consumption and storage prefix names. curl -X GET "<url>/<BucketName>/listprefixes" -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" Response: 200 [ "<subnamespace>/planning/incoming/config/", "<subnamespace>/planning/incoming/input" ] |
List files within a storage prefix |
/listFiles |
{ "storagePrefix": "optional_string" } |
storage prefix name, file name, size, md5 checksum, created date, modified date, scan date, scan status |
This endpoint is used to find and list files from Object Storage. curl -X GET "<url>/<BucketName>/listfiles?prefix=<subnamespace>/planning/incoming&contains=prod&sort=size:asc" \ -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" Response: { "resultSet": [{ "name": "<subnamespace>/planning/incoming/config1/prod.csv.dat", "size": 177023, "md5": "vlN/r8gbNyQ1EdsC++Hv1w==", "version": "ca60582d-bacb-4309-bbbf-89d4a1aa2843", "etag": "7d6dde3b-5b5b-430d-8494-78e090418946", "createdDate": "2021-08-25T20:36:40Z", "modifiedDate": "2021-08-25T20:36:40Z", "scanStatus": "Passed" }], "totalResults": 1, "limit": 0, "count": 1, "offset": 0, "hasMore": false } |
Find file |
/findFileByName |
{ "stringContains": "string" } |
storage prefix name, file name, size, md5 checksum, created date, modified date, scan date, scan status |
This endpoint is used to find and list files from Object Storage. curl -X GET "<url>/<BucketName>/findFileByName?prefix=<subnamespace>/planning/incoming&contains=prod&sort=size:asc" \ -H "accept: application/json" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" Response: { "resultSet": [{ "name": "<subnamespace>/planning/incoming/config1/prod.csv.dat", "size": 177023, "md5": "vlN/r8gbNyQ1EdsC++Hv1w==", "version": "ca60582d-bacb-4309-bbbf-89d4a1aa2843", "etag": "7d6dde3b-5b5b-430d-8494-78e090418946", "createdDate": "2021-08-25T20:36:40Z", "modifiedDate": "2021-08-25T20:36:40Z", "scanStatus": "Passed" }], "totalResults": 1, "limit": 0, "count": 1, "offset": 0, "hasMore": false } |
Liveness test |
/ping |
This endpoint allows customer to check for service liveness. curl -X GET "<url>/ping" -H "accept: */*" -H "Accept-Language: en" -H "Authorization: Bearer <AccessToken>" Response: { "appStatus": 200 } |