Uploading Assets (assets/upload)
Request tokens for asset fields in new or existing records used in another request to upload asset data.
Path
POST [path]/database/[version]/[container]/[environment]/[database]/assets/upload
Parameters
- path
The URL to the CloudKit web service, which is
https://api.apple-cloudkit.com
.- version
The protocol version—currently, 1.
- container
A unique identifier for the app’s container. The container ID begins with
iCloud.
.- environment
The version of the app’s container. Pass
development
to use the environment that is not accessible by apps available on the store. Passproduction
to use the environment that is accessible by development apps and apps available on the store.- database
The database to store the data within the container. Pass
public
to use the database that is accessible to all users of the app. Passprivate
to use the database that is visible only to the currently signed-in user.
Request
The POST request is a JSON dictionary containing the following keys:
Key |
Description |
---|---|
|
Dictionary that identifies a record zone in the database, described in Zone ID Dictionary. The default is the default zone. |
|
An array of asset fields, described in Asset Field Dictionary. See Data Size Limits for the maximum number of tokens allowed in this request. This key is required. |
Asset Field Dictionary
Dictionary that identifies a field of type Asset in a record.
Key |
Description |
---|---|
|
The unique name used to identify the record within a zone. The default is a random UUID. |
|
The name of the record type. |
|
The name of an Asset or Asset list field belonging to the record type. This key is required. |
Response
An array of tokens containing the upload URLs. There’s one token dictionary, described in Token Response Dictionary, for each asset field specified in the request.
Token Response Dictionary
Provides a URL for uploading an asset.
Key |
Description |
---|---|
|
The unique name used to identify the record within a zone. The default value is a random UUID. |
|
The name of a field belonging to the record type. |
|
The location to upload the asset data. |
Discussion
To set asset values, you request upload URLs for the asset fields of new and existing records. Upload URLs are valid for a limited time (15 minutes), and the maximum file size is 15 MB.
Setting Asset Values in Records
Requesting URLs to upload asset data is just one step in the workflow to set asset values in records. The steps to set asset values are:
Request URLs for uploading asset data.
Upload the asset data.
Set the asset fields in records to the uploaded data.
Request URLs
To request URLs to upload asset data, compose a request similar to:
curl -X POST '[path]/database/[version]/[container]/[environment]/[database]/assets/upload' -H 'content-type: application/json' -d '{
"tokens":[{
"recordType":"Artwork",
"fieldName":"image"
}]
}'
The response is:
{
"tokens":[{
"recordName":"4c016e24-c397-4c9d-81d6-dee3e3a48bb0",
"fieldName":"image",
"url":[ASSET_UPLOAD_URL]
}]
}
Upload Asset Data
For each token dictionary in the response, upload the asset using a curl
command similar to:
curl -X POST $[ASSET_UPLOAD_URL] -d@[ASSET_FILE]
The response is an asset dictionary, describe in Asset Dictionary, that you pass in a modify request.
{
"singleFile" :{
"wrappingKey" : [WRAPPING_KEY],
"fileChecksum" : [SIGNATURE],
"receipt" : [RECEIPT],
"referenceChecksum" : [REFERENCE_CHECKSUM],
"size" : [SIZE]
}
}
Modify Records with Asset Fields
Modify the records, described in Modifying Records (records/modify), setting the asset fields to the asset value dictionaries returned in the previous step. For example, create an Artist record setting the image asset to the uploaded file:
curl -X POST '[path]/database/[version]/[container]/[environment]/[database]/records/modify' -H 'content-type: application/json' -d '{
"operations" :[{
"operationType" : "create",
"record" :{
"recordType" : "Artist",
"fields" :{
"title" : {"value" : "MacKerricher State Park"},
"artist" : {"value" : "Mei Chen"},
"image" : {
"value" : {
"wrappingKey" : [WRAPPING_KEY],
"fileChecksum" : [FILE_CHECKSUM],
"receipt" : [RECEIPT],
"referenceChecksum" : [REFERENCE_CHECKSUM],
"size": [SIZE]
}
}
},
"recordName": "4c016e24-c397-4c9d-81d6-dee3e3a48bb0",
"desiredKeys": []
}
}]
}'
If successful, the response is:
{
"records": [{
"recordName" : "4c016e24-c397-4c9d-81d6-dee3e3a48bb0",
"recordChangeTag" : "1e",
"created" : {
"timestamp" : 1422312944104,
"userRecordName" : "_9a065b60313a5937e75e03ed8e8f383d",
"deviceID" : "iCloud"
},
"modified" : {
"timestamp" : 1422312944104,
"userRecordName" : "_9a065b60313a5937e75e03ed8e8f383d",
"deviceID" : "iCloud"
}
}]
}
Accepting Share Records (records/accept)
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-06-13