Create and publish a label

This document describes how to create and publish labels using the Google Drive Labels API.

Create a label

To create a label, use the create method on the labels resource. Labels can optionally contain one or more Field objects.

You also must specify:

The following code sample shows how to use the create method to create a standard, administrator label with a specified title and one SelectionOptions Field with two Choice objects.

Python

label_body = {
    'labelType': 'ADMIN',
    'properties': {
        'title': 'TITLE'
    },
    'fields': [{
        'properties': {
            'displayName': 'DISPLAY_NAME'
        },
        'selectionOptions': {
            'listOptions': {},
            'choices': [{
                'properties': {
                    'displayName': 'CHOICE_1'
                }
            }, {
                'properties': {
                    'displayName': 'CHOICE_2'
                }
            }]
        }
    }]
}
response = service.labels().create(
    body=label_body, useAdminAccess=True).execute()

Node.js

var label = {
  'labelType': 'ADMIN',
  'properties': {
    'title': 'TITLE'
  },
  'fields': [{
    'properties': {
      'displayName': 'DISPLAY_NAME'
    },
    'selectionOptions': {
      'listOptions': {},
      'choices': [{
        'properties': {
          'displayName': 'CHOICE_1'
        }
      }, {
        'properties': {
          'displayName': 'CHOICE_2'
        }
      }]
    }
  }]
};

service.labels.create({
  requestBody: label,
  useAdminAccess: true
}, (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.
  • CHOICE_1: The first choice in the SelectionOptions field.
  • CHOICE_2: The second choice in the SelectionOptions field.

The label is created in the UNPUBLISHED_DRAFT State. The label must be PUBLISHED to be visible to users and for use on files. For more information, see Label lifecycle.

Label limits

The following limits apply when creating and applying labels:

  • Standard labels: 150
  • Fields per label: 10

Working with fields in labels

The following table describes the types of fields you can add to a label, how users interact with them, and their format considerations and limits:

Field Type What users can do Format considerations and limits
SelectionOptions Select one or more options from a list Maximum number of options supported is 200
Maximum number of selections for a file is 10 as configured in ListOptions
IntegerOptions Enter a numerical value Only whole numbers are supported
DateOptions Select a calendar date (Optional) The DateFormat can be set to "Long: Month DD, YYYY", or "Short: MM/DD/YY"
TextOptions Enter text in a text box Maximum character count supported is 100
UserOptions Select one or more users from Google Workspace contacts. Maximum number of user entries for a file is 10 as configured in ListOptions

Publish a label

The Drive Labels API lets you publish a draft label once it's complete. The label is then visible to users and can be applied to files.

To publish a label, use the publish method on the labels resource and specify:

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

  • 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.

The following code sample shows how to use the label's id to identify and publish the correct label.

Python

service.labels().publish(
    name='labels/ID',
    body={
        'useAdminAccess': True
    }
).execute()

Node.js

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

Replace ID with the ID of the label to publish.

Once the label is published, the label moves to the PUBLISHED State and the label's revision ID is incremented. The label is then visible to users and can be applied to files. For more information, see Label lifecycle.

Constraints when publishing labels

As you prepare to publish labels, take note of these constraints:

  • Once published, a label cannot return to its original draft state. For more information, see Label lifecycle.

  • Publishing a label creates a newly published revision. All previous draft revisions are deleted. Previously published revisions are kept but are subject to automated deletion as needed.

  • Once published, some changes are no longer permitted. Generally, this means any change that invalidates or triggers new restrictions on existing metadata related to the label is rejected. For example, the following changes to a label aren't permitted after the label is published:

    • The label is directly deleted. (It must be disabled first, then deleted.)
    • The Field.FieldType is changed.
    • Updates to the Field validation options reject something previously accepted.
    • A reduction in maximum entries.