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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#properties) (the
basic label description) or you can add a new
[`Field`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#field) to the label.

The label update acts as a batch update as the method takes a list of update
[`Request`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta) method on the
[`labels`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels) resource 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 `delta` method works by taking one or more
[Request](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#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 object [Label Properties](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#properties) *Update* [UpdateLabelPropertiesRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#UpdateLabelPropertiesRequest) [Field](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#field) *Create* [CreateFieldRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#createfieldrequest) *Update* [UpdateFieldPropertiesRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#updatefieldpropertiesrequest)  
[UpdateFieldTypeRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#updatefieldtyperequest) *Enable* [EnableFieldRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#enablefieldrequest) *Disable* [DisableFieldRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#disablefieldrequest) *Delete* [DeleteFieldRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#deletefieldrequest) [Selection Choice](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#choice) *Create* [CreateSelectionChoiceRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#createselectionchoicerequest) *Update* [UpdateSelectionChoicePropertiesRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#updateselectionchoicepropertiesrequest) *Enable* [EnableSelectionChoiceRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#enableselectionchoicerequest) *Disable* [DisableSelectionChoiceRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#disableselectionchoicerequest) *Delete* [DeleteSelectionChoiceRequest](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#deleteselectionchoicerequest)

### Field masks

Many of the "Update" and "Disable" type requests require a
[`FieldMask`](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask).
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.

> [!NOTE]
> **Note:** A field mask of `*` is treated like a wildcard and is shorthand for specifying every field in a message. The wildcard syntax can produce unwanted results as a field might revert to its default state if you don't specify a value for it in the update request. For production applications, always list the specific fields being updated in field masks and avoid using `*` wildcards.

## Example

To update a label, use the
[`delta`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta) method on the
[`labels`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels) resource.

You also must specify:

- The [`useAdminAccess`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#body.request_body.FIELDS.use_admin_access)
  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](https://knowledge.workspace.google.com/admin/users/administrator-privilege-definitions#data_classification)
  administrator privileges.

- A [`Request`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/delta#request)
  that specifies the applicable updates to the label.

- A label `title` through the [`Properties`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#properties)
  object.

- One or more
  [`Field`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#field) objects.

- A [`labels`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels) resource that
  represents the label. It contains a
  [`name`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#Label.FIELDS.name)
  and an
  [`id`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#Label.FIELDS.id),
  which is a globally unique identifier for the label.

- A [`LabelView`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/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:

### Python

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

### Node.js

    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:

- <var translate="no">TITLE</var>: The title of the label.
- <var translate="no">DISPLAY_NAME</var>: The display name of the field.
- <var translate="no">ID</var>: 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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#state) of `PUBLISHED`
with
[`hasUnpublishedChanges`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#Lifecycle.FIELDS.has_unpublished_changes)
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](https://developers.google.com/workspace/drive/labels/guides/label-lifecycle).