Update a label

You can update a single label using the Google Drive Labels API by applying a set of update requests resulting in a new draft revision. For example, you can update an existing label Properties (the basic 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 Google Drive item.

Update label objects

A label includes many other object types that can be updated, such as:

• Label Properties
• Field objects and field types
• Selection Choice and Selection Choice Properties

These are some of the many objects that control the appearance and operation of a label.

Categories of operation

The following operations supported by the delta method on the labels resource 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 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 while leaving the other fields unchanged. The mask is required to make sure only the fields you want to edit are updated. You must specify at least one field.

Example

To update a label, use the delta method on the labels resource.

You also must specify:

• The useAdminAccess query parameter is set to true to use the user's administrator credentials. Before allowing access, the server verifies that the user has the required Manage Classification Labels administrator privileges.

• A Request that specifies the applicable updates to the label.

• A label title through the Properties object.

• One or more Field objects.

• A labels resource that represents the label. It contains a name and an id, which is a globally unique identifier for the label.

• A LabelView object as LABEL_VIEW_FULL to set a resource view that's applied to label responses. LABEL_VIEW_FULL returns all possible fields.

The following code sample shows how to use the label's id to update the correct label:

body = {
    'useAdminAccess': True,
    'requests': [
        {
            'updateLabel': {
                'properties': {
                    'title': 'TITLE'
                },
                'updateMask': 'title'
            }
        },
        {
            'createField': {
                'field': {
                    'properties': {
                        'displayName': 'DISPLAY_NAME'
                    },
                    'textOptions': {}
                }
            }
        }
    ],
    'view': 'LABEL_VIEW_FULL'
}

response = service.labels().delta(
    body=body,
    name='labels/ID'
).execute()

var body = {
  'useAdminAccess': true,
  'requests': [
    {
      'updateLabel': {
        'properties': {
          'title': 'TITLE'
        },
        'updateMask': 'title'
      }
    },
    {
      'createField': {
        'field': {
          'properties': {
            'displayName': 'DISPLAY_NAME'
          },
          'textOptions': {}
        }
      }
    }
  ],
  'view': 'LABEL_VIEW_FULL'
};

service.labels.delta({
  name: 'labels/ID',
  requestBody: body
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Replace the following:

• TITLE: The title of the label.
• DISPLAY_NAME: The display name of the field.
• ID: The ID of the label.

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 set to 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.