Update a label

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:

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.

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 is true 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 the property method.

• One or more Field.

• A Label resource which represents every label. It contains a resource Name and ID, which is a globally unique identifier for the label.

• LabelView is LABEL_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.

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()

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.