You can update a single label by applying a set of update requests resulting in
a new draft revision. For example, you can update an existing label
property (the label
description) or you can add a new
Field
to the label.
The label update acts as a batch update as the method takes a list of update
Request
objects.
It makes updates according to the same order specified in the batch request. The
updates in the batch update are applied atomically. That is, if any request in
the batch is unsuccessful, then the entire update is unsuccessful and none of
the (potentially dependent) changes are applied. The label is left unchanged.
If the update is successful, the resulting draft revision must be published before the changes can be used with any Drive item.
Update label objects
A label includes many other object types that can be updated, such as:
- Label Properties
- Fields and Field Types
- Selection Choices and Selection Choice Properties
These are just some of the many objects that control the appearance and operation of a label.
Categories of operation
The following operations supported by the
labels.delta
method can be
grouped into the following broad categories:
Category | Description |
---|---|
Create | Add objects. |
Update | Update certain properties of an object. |
Enable | Enable objects. |
Disable | Disable objects. |
Delete | Remove objects. |
These categories are used in the next section to describe the behavior of specific operations.
Update requests
The labels.delta
method
works by taking one or more
Request objects,
each one specifying a single type of request to perform. There are many
different kinds of requests. Here's a breakdown on the types of requests,
grouped into different categories.
Request type | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Label Properties |
|
||||||||||
Field |
|
||||||||||
Selection Choice |
|
Field masks
Many of the "Update" and "Disable" type requests require a
FieldMask
.
This is a comma-delimited list of fields you want to update. At least one field
must be specified.
The mask is required to make sure only the fields you want to edit are updated. You can use a single * as short-hand for updating every field (which means a field might revert to its default state if you don't specify a value for it in the request).
Example
To update a label, use the
delta
method on the
labels
collection.
You also need to specify:
useAdminAccess
istrue
to use the user's administrator credentials. The server verifies the user is an admin for the label before allowing access.A
Request
that specifies the applicable updates to the label.A label
title
through theproperty
method.One or more
Field
.A Label resource which represents every label. It contains a resource
Name
andID
, which is a globally unique identifier for the label.LabelView
isLABEL_VIEW_FULL
to set the Resource view applied to label responses.LABEL_VIEW_FULL
returns all possible fields.
This example uses the ID
to update the correct label.
Python
body = {
'use_admin_access': True,
'requests': [{
'update_label': {
'properties': {
'title': 'TITLE'
},
'update_mask': {
'paths': ['title']
}
},
}, {
'create_field': {
'field': {
'properties': {
'display_name': 'DISPLAY_NAME'
},
'text_options': {}
}
}
}],
'view': 'LABEL_VIEW_FULL'
}
response = service.labels().delta(
body=body,
name='labels/ID').execute()
Node.js
var body = {
'use_admin_access': true,
'requests': [{
'update_label': {
'properties': {
'title': 'TITLE'
},
'update_mask': {
'paths': ['title']
}
},
}, {
'create_field': {
'field': {
'properties': {
'display_name': 'DISPLAY_NAME'
},
'text_options': {}
}
}
}],
'view': 'LABEL_VIEW_FULL'
};
service.labels.delta({
'resource': body,
'name': 'labels/ID'
}, (err, res) => {
if (err) return console.error('The API returned an error: ' + err);
console.log(res);
});
The label, field, or choice is updated, the label's revision ID is incremented,
and the label is stored in a database as a draft label. The label has the
State
of PUBLISHED
with
hasUnpublishedChanges=true
meaning there are draft changes, but they aren't
available to users. The updated label must be PUBLISHED
before the changes
become visible to users. For more information, see
Label lifecycle.