Modifying Records (records/modify)
Apply multiple types of operations—such as creating, updating, replacing, and deleting records— to different records in a single request.
Path
POST [path]/database/[version]/[container]/[environment]/[database]/records/modify
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. The possible values are:
public
The database that is accessible to all users of the app.
private
The database that contains private data that is visible only to the current user.
shared
The database that contains records shared with the current user.
Request
The POST request is a JSON dictionary containing the following keys:
Key |
Description |
---|---|
|
An array of dictionaries defining the operations to apply to records in the database. The dictionary keys are described in Record Operation Dictionary. See Data Size Limits for maximum number of operations allowed. This key is required. |
|
A dictionary that identifies a record zone in the database, described in Zone ID Dictionary. |
|
A Boolean value indicating whether the entire operation fails when one or more operations fail.
If Note this property only applies to custom zones. |
|
An array of strings containing record field names that limit the amount of data returned in the enclosing operation dictionaries. Only the fields specified in the array are returned. The default is |
|
A Boolean value indicating whether number fields should be represented by strings. The default value is |
Record Operation Dictionary
The operation dictionary keys are:
Key |
Description |
---|---|
|
The type of operation. Possible values are described in Operation Type Values. This key is required. |
|
A dictionary representing the record to modify, as described in Record Dictionary. This key is required. |
|
An array of strings containing record field names that limits the amount of data returned in this operation. Only the fields specified in the array are returned. The default is
This |
Operation Type Values
The possible values for the operationType
key are:
Value |
Description |
---|---|
|
Create a new record. This operation fails if a record with the same record name already exists. |
|
Update an existing record. Only the fields you specify are changed. |
|
Update an existing record regardless of conflicts. Creates a record if it doesn’t exist. |
|
Replace a record with the specified record. The fields whose values you do not specify are set to |
|
Replace a record with the specified record regardless of conflicts. Creates a record if it doesn’t exist. |
|
Delete the specified record. |
|
Delete the specified record regardless of conflicts. |
Response
The response is an array of dictionaries describing the results of the operation. The dictionary contains a single key:
Key |
Description |
---|---|
|
An array containing a result dictionary for each operation in the request. If successful, the result dictionary contains the keys described in Record Dictionary. If unsuccessful, the result dictionary contains the keys described in Record Fetch Error Dictionary. |
Record Fetch Error Dictionary
The error dictionary describing a failed operation with the following keys:
Key |
Description |
---|---|
|
The name of the record that the operation failed on. |
|
A string indicating the reason for the error. |
|
A string containing the code for the error that occurred. For possible values, see Error Codes. |
|
The suggested time to wait before trying this operation again. If this key is not set, the operation can’t be retried. |
|
A unique identifier for this error. |
|
A redirect URL for the user to securely sign in using their Apple ID. This key is present when |
Discussion
A request to modify records applies multiple types of operations to different types of records in a single request. Changes are saved to the database in a single operation. If the atomic
key is true
and one operation fails, the entire request fails. If the atomic
key is false
, some of the operations may succeed even when others fail. The operations are applied in the order in which they appear in the operations
dictionary. One operation per record is allowed in the operations
dictionary. The contents of an operation dictionary depends on the type of operation.
For example, to modify records in the Gallery app’s public database in the development environment, compose the URL as follows:
https://apple-cloudkit.com/database/1/iCloud.com.example.gkumar.Gallery/development/public/records/modify
Then, construct the request depending on the types of operations you want to apply.
Creating the JSON Dictionary
Create a JSON dictionary representing the changes you want to make to multiple records in a database. For example, if you want to modify records in the default zone, simply include the operations key and insert the appropriate operation dictionary for the type of operation, described below.
{
"operations" : [
// Insert Operation dictionaries in this array
],
}
Creating Records
To create a single record in the specified database, use the create
operation type.
Create an operation dictionary with these key-value pairs:
Set the
operationType
key tocreate
.Set the
record
key to a record dictionary describing the new record.
Create a record dictionary with these key-value pairs:
Set the
recordType
key to the record’s type.Set the
recordName
key to the record’s name.If you don’t provide a record name, CloudKit assigns one for you.
Set the
fields
key to a dictionary of key-value pairs used to set the record’s fields, as described in Record Field Dictionary.The keys are the field names and the values are the initial values for the fields.
Add the operation dictionary to the
operations
array.
For example, this operation dictionary creates an Artist
record with the first name “Mei” and last name “Chen”:
{
"operationType" : "create",
"record" : {
"recordType" : "Artist",
"fields" : {
"firstName" : {"value" : "Mei"},
"lastName" : {"value" : "Chen"}
}
"recordName" : "Mei Chen"
},
}
Updating Records
To update the specified fields of an existing record, use the update
or forceUpdate
operation type.
Create an operation dictionary with these key-value pairs:
Set the
operationType
key toupdate
orforceUpdate
.If you want the operation to fail when there is a conflict, use
update
; otherwise, useforceUpdate
. TheforceUpdate
operation updates the record regardless of a conflict.Set the
record
key to a record dictionary describing the new field values.
Create a record dictionary with these key-value pairs:
If
operationType
isforceUpdate
, set therecordType
key to the record’s type.Set the
recordName
key to the record’s name.Set the
fields
key to a dictionary of key-value pairs used to set the record’s fields.The keys are the field names and the values are the new values for the fields.
If
operationType
isupdate
, set therecordChangeTag
key to the value of the existing record.
Add the operation dictionary to the
operations
array in the JSON dictionary.
For example, this operation dictionary changes the width
and height
fields of an existing Artwork
record:
{
"operationType" : "update",
"record" : {
"fields" : {
"width": {"value": 18},
"height": {"value": 24}
}
"recordName" : "101",
"recordChangeTag" : "e"
},
}
Replacing Records
To replace an entire record, use the replace
or forceReplace
operation type.
Create an operation dictionary with these key-value pairs:
Set the
operationType
key toreplace
orforceReplace
.If you want the operation to fail when there is a conflict, use
replace
; otherwise, useforceReplace
.Set the
record
key to a record dictionary identifying the record to replace and containing the replacement record field values.
Create a record dictionary with these key-value pairs:
Set the
recordName
key to the name of the record you want to replace.Set the
fields
key to a dictionary of key-value pairs used to set the replacement record’s fields. Fields that you omit from the dictionary are set tonull
.The keys are the field names and the values are the new values for the fields.
If
operationType
isreplace
, set therecordChangeTag
key to the value of the existing record.
Add the operation dictionary to the
operations
array.
Deleting Records
To delete a record, use the delete
or forceDelete
operation type.
Create an operation dictionary with these key-value pairs:
Set the
operationType
key todelete
orforceDelete
.If you want the operation to fail when there is a conflict, use
delete
; otherwise, useforceDelete
.Set the
record
key to a record dictionary identifying the record to delete.
Create a record dictionary with a single key-value pair, whose key is
recordName
.Add the operation dictionary to the
operations
array.
Sharing Records
Shared records must have a short GUID. To create a record that will be shared, add the createShortGUID
key to the record dictionary in the request when you create the record as in:
{
"operations": [{
"operationType": "create",
"record": {
"recordName": "RecordA",
"recordType": "myType",
"createShortGUID": true
}
}],
"zoneID": {
"zoneName": "myCustomZone"
}
}
In the response, the shortGUID
key will be set in the record dictionary.
To share this record, create a record of type cloudKit.share
. If the original record has no shortGUID
key, one will be created for you. In the request, specify the public permissions and participants as in:
{
"operations": [{
"operationType": "create",
"record": {
"recordType": "cloudKit.share",
"fields": {},
"forRecord": {
"recordName": "RecordA",
"recordChangeTag": "2"
},
"publicPermission": "NONE",
"participants": [{
"type": "USER",
"permission": "READ_WRITE",
"acceptanceStatus": "INVITED",
"userIdentity": {
"lookupInfo": {
"emailAddress": "gkumar@mac.com"
}
}
}]
}
}],
"zoneID": {
"zoneName": "myCustomZone"
}
}
In the response, the record will have these keys set that are present only in a share, described in Record Dictionary:
shortGUID
share
publicPermission
participants
owner
currentUserParticipant
Related Framework API
This request is similar to using the CKModifyRecordsOperation
class in the CloudKit framework.
Composing Web Service Requests
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-06-13