CloudKit Web Services Reference: 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. Pass production 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. Pass private 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
`zoneID`	Dictionary that identifies a record zone in the database, described in Zone ID Dictionary. The default is the default zone.
`tokens`	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
`recordName`	The unique name used to identify the record within a zone. The default is a random UUID.
`recordType`	The name of the record type.
`fieldName`	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
`recordName`	The unique name used to identify the record within a zone. The default value is a random UUID.
`fieldName`	The name of a field belonging to the record type.
`url`	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"
      }
  }]
}

      