Create an App-Managed Bucket and Upload a File
This walkthrough explains how to create a bucket managed by your app and upload a file to that bucket.
Before You Begin
Make sure that you have registered an app and successfully acquired an OAuth token with scopes bucket:create
, bucket:read
, and data:write
. This will allow you to create a bucket, get bucket details, and upload a file.
Step 1: Create a bucket
Before uploading a file, create a bucket and set a retention policy using the POST buckets endpoint. In our example, we’re going to create a transient
bucket, meaning that anything uploaded to it will be deleted after 24 hours.
Example
curl -v 'https://developer.api.autodesk.com/oss/v2/buckets'
-X 'POST'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i'
-d '
{
"bucketKey":"mybucket",
"policyKey":"transient"
}
'
Once the bucket is created, verify that it exists using the GET buckets/:bucketKey/details endpoint:
curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/details'
-X 'GET'
-H 'Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i'
If successful, the response body should look something like this:
{
"bucketKey": "mybucket",
"bucketOwner": "obQDn8P0GanGFQha4ngKKVWcxwyvFAGE",
"createdDate": 1401735235495,
"permissions": [
{
"authId": "obQDn8P0GanGFQha4ngKKVWcxwyvFAGE",
"access": "full"
}
],
"policyKey": "transient"
}
Step 2: Initiate a direct to s3 multipart upload
Choose a name for your object. This can be the actual filename or something like a GUID generated by a data management system, but maintain the file extension. For this example we will assume a 20Mb file named skyscpr1.3ds
The GET buckets/:bucketKey/objects/:objectKey/signeds3upload requests one or multiple S3 signed URL with which to upload an object based on how many ‘parts’ you specify. These URLs will directly transmit the file to S3 and will be registered in OSS once POST buckets/:bucketKey/objects/:objectKey/signeds3upload is called.
Example
curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds/signeds3upload?parts=2'
-X GET
-H 'Authorization: Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi'
-H 'Content-Type: application/json'
If successful, the response body should look something like this:
{
"uploadKey": "{UPLOAD_KEY}",
"uploadExpiration": "2022-01-25T00:00:00Z",
"urlExpiration": "2022-01-23T21:48:42Z",
"urls": [
"https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=1&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=269cde4288e380ce720b2a8a039b5e311cb9d4276ccf5e59582b32676a8f378b",
"https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=2&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=e5e4edcf819856f4a689c8a90975a64395df7fb33d60e3ab351e39ad0fe2585c"
]
}
Step 3: Split the file, and upload.
If using CURL you will have to have the object as distinct files. At this point you should split the file into those chunks (minimum 5Mb filesize)
split -b 10m -d skyscpr1.3ds part
The upload can then be performed to the URLs received from Step 2.
Note: These uploads do not use an ‘Authorization’ header.
curl -v 'https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=1&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=269cde4288e380ce720b2a8a039b5e311cb9d4276ccf5e59582b32676a8f378b'
-X 'PUT'
-H 'Content-Type: application/octet-stream'
-H 'Content-Length: 10485760'
-T 'part00'
curl -v 'https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=2&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=e5e4edcf819856f4a689c8a90975a64395df7fb33d60e3ab351e39ad0fe2585c'
-X 'PUT'
-H 'Content-Type: application/octet-stream'
-H 'Content-Length: 10485760'
-T 'part01'
Step 4: Complete the upload
Call the POST buckets/:bucketKey/objects/:objectKey/signeds3upload endpoint to complete the multipart upload and register the item with OSS.
curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds/signeds3upload'
-X POST
-H 'Authorization: Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi'
-H 'Content-Type: application/json'
-H 'x-ads-meta-Content-Type: application/octet-stream'
--data-raw '{
"uploadKey": "{UPLOAD_KEY}"
}'
If successful, the response body should look like this:
{
"bucketKey" : "mybucket",
"objectId" : "urn:adsk.objects:os.object:mybucket/skyscpr1.3ds",
"objectKey" : "skyscpr1.3ds",
"sha1" : "e84021849a9f5d1842bf792bbcbc6445c280e15b",
"size" : 20971520,
"content-type": "application/octet-stream",
"location": "https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds"
}