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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/create) method on the [`labels`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels) resource. Labels can optionally contain one or more [`Field`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#field) objects. You also must specify: - A [`LabelType`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#labeltype) object. - A label `title` through the [`Properties`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#properties) object. - The [`useAdminAccess`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/create#body.QUERY_PARAMETERS.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. The following code sample shows how to use the `create` method to create a standard, administrator label with a specified title and one [`SelectionOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#selectionoptions) `Field` with two [`Choice`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#state). The label must be `PUBLISHED` to be visible to users and for use on files. For more information, see [Label lifecycle](https://developers.google.com/workspace/drive/labels/guides/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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#listoptions) | | [`IntegerOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#integeroptions) | Enter a numerical value | Only whole numbers are supported | | [`DateOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#dateoptions) | Select a calendar date | (Optional) The [`DateFormat`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#dateformat) can be set to "Long: Month DD, YYYY", or "Short: MM/DD/YY" | | [`TextOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#textoptions) | Enter text in a text box | Maximum character count supported is 100 | | [`UserOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#UserOptions) | Select one or more users from Google Workspace contacts. | Maximum number of user entries for a file is 10 as configured in [`ListOptions`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/publish) method on the [`labels`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels) resource and specify: - A `labels` resource that represents every label. It contains a resource [`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. - The [`useAdminAccess`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels/publish#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. 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`](https://developers.google.com/workspace/drive/labels/reference/rest/v2/labels#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](https://developers.google.com/workspace/drive/labels/guides/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](https://developers.google.com/workspace/drive/labels/guides/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.