Descripción general de la API de Etiquetas de Drive
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
Las etiquetas son metadatos que defines para ayudar a los usuarios a organizar y encontrar archivos en Google Drive, además de aplicarles políticas. La API de Drive Labels es una API de RESTful que admite procesos comerciales adjuntando metadatos a tus archivos de Drive. Estos son algunos usos comunes de esta API:
Clasifica el contenido para seguir una estrategia de control de la información: Crea una etiqueta para identificar el contenido o los datos sensibles que requieren un control especial.
Por ejemplo, puedes crear una etiqueta con distintivo (una etiqueta con valores de opción codificados por color) titulada "Sensibilidad" con los valores "Secreto", "Confidencial" y "Público".
Aplicar política a elementos en Drive: Crea etiquetas para administrar el contenido de Drive durante todo su ciclo de vida y garantizar que cumpla con las prácticas de mantenimiento de registros de tu organización. Por ejemplo, usa etiquetas para administrar una política de prevención de pérdida de datos (DLP) en la que los archivos con una etiqueta de "Sensibilidad" establecida en "Secreto" no se puedan descargar en una computadora.
Organiza y encuentra archivos: Crea etiquetas para aumentar la capacidad de búsqueda del contenido de tu empresa, ya que permitirás que los miembros de tu organización encuentren elementos según las etiquetas y sus campos. Por ejemplo, alguien de tu organización podría usar las opciones de búsqueda de Drive para encontrar todos los contratos que esperan la firma antes de una fecha específica.
A continuación, se incluye una lista de términos comunes que se usan en la API de Drive Labels:
Son los metadatos estructurados que se colocan en un archivo de Drive.
Los usuarios de Drive pueden asignar etiquetas y establecer valores de campo de etiquetas para los archivos. Las etiquetas se componen de lo siguiente:
Nombre de la etiqueta
Es el nombre del recurso de la etiqueta. El ID de etiqueta forma parte del nombre de la etiqueta. Según la solicitud, el nombre tendrá el siguiente formato:
labels/{id} o labels/{id}@{revisionId}. Para obtener más información, consulta Revisión de etiquetas a continuación.
ID de etiqueta
Es un identificador único a nivel global para la etiqueta. El ID forma parte del nombre de la etiqueta, pero, a diferencia del nombre, es coherente entre las revisiones.
Existen 2 estilos de etiquetas:
Etiqueta con distintivo
Una etiqueta con un tipo de campo SelectionOptions que contiene opciones que se pueden codificar por colores para indicar la importancia. Para ello, se establece badgeConfig a través de Properties de un Choice.
Drive muestra el color de la opción elegida para cada archivo, de modo que los usuarios comprendan claramente el estado, la clasificación, etcétera, del archivo.
Por ejemplo, la opción "Máxima confidencialidad" de la etiqueta con distintivo "Confidencialidad" podría mostrarse en rojo. Solo puedes tener una etiqueta con insignia a la vez.
Etiqueta estándar
Es una etiqueta que contiene cero o más tipos de campo. Una etiqueta estándar puede tener un título, como "Proyecto Moonshot", y puede indicar todos los archivos relacionados con el proyecto. Una etiqueta estándar también puede tener varios campos estructurados. Por ejemplo, una etiqueta con el título "Contrato" podría contener los campos "Empresa", "Fecha de vencimiento", "Estado" y "Firmantes". Cada campo es de un tipo específico (texto, fecha, selección o usuario).
Es un componente individual con tipo y configurable de una etiqueta. Una etiqueta puede tener cero o más campos asociados.
Tipo de campo
Es el tipo de datos del valor asociado al campo. Se puede configurar como texto, número entero, fecha, usuario o selección. Si configuras el campo con ListOptions, puedes establecer los campos de usuario y selección con varios valores. El tipo elegido afecta tanto los valores válidos aplicables a los elementos de Drive como las opciones de búsqueda disponibles.
Todas las etiquetas incluyen un LabelType. Existen 2 tipos de etiquetas:
Administrador
Para crear y editar etiquetas propiedad del administrador, debes ser administrador de la cuenta y tener el privilegio Administrar etiquetas.
Los administradores pueden compartir etiquetas de administrador con cualquier usuario para otorgarle la capacidad de verlas y aplicarlas a elementos de Drive. Para modificar o leer los valores de las etiquetas en los elementos de Drive, se requieren los siguientes permisos:
Modificación: Para que un usuario modifique los metadatos de un elemento de Drive relacionados con una etiqueta determinada, debe tener los niveles de permiso adecuados:
Elemento de Drive: EDITOR
Etiqueta: APPLIER
Lectura: Para que un usuario lea o busque los metadatos de un elemento de Drive relacionados con una etiqueta determinada, debe tener los niveles de permiso adecuados:
Elemento de Drive: READER
Etiqueta: READER
Compartida
Los usuarios que no son administradores pueden crear etiquetas compartidas que otros pueden aplicar a elementos de Drive. Los equipos pueden crear y organizar sus propias etiquetas para usarlas dentro del equipo sin necesidad de un administrador.
Taxonomía de etiquetas
Son los campos de etiquetas configurados actualmente que están disponibles para que los usuarios los apliquen a los archivos de Drive. También se conoce como esquema de etiquetas.
Ejemplos de taxonomías de etiquetas:
Sensibilidad: Rojo, naranja, amarillo, verde
Estado: No se inició, Borrador, En revisión, Final
Tipo de contenido: Contrato, documento de diseño, simulación
Las etiquetas pasan por un ciclo de vida en el que se crean, publican, actualizan, etcétera. A medida que una etiqueta avanza en su ciclo de vida, se incrementa su revisión de etiqueta. Para obtener más información, consulta Ciclo de vida de las etiquetas.
Revisión de etiquetas
Es una instancia de la etiqueta. Cada vez que se crea, actualiza, publica o deja de utilizar una etiqueta, se incrementa la revisión de la etiqueta.
Revisión de borrador
Es el número de revisión de la instancia de borrador actual de la etiqueta. Puedes realizar varias actualizaciones en una etiqueta, cada una de las cuales incrementa su número de revisión de borrador, sin afectar la revisión publicada. La capacidad de tener etiquetas de borrador te permite probar las actualizaciones de etiquetas antes de publicarlas.
Revisión publicada
Es el número de revisión de la versión publicada de una etiqueta. La etiqueta publicada es la instancia de la etiqueta que está disponible para los usuarios.
[null,null,["Última actualización: 2025-08-29 (UTC)"],[],[],null,["# Drive Labels API overview\n\n*Labels* are metadata that you define to help users organize, find, and apply\npolicy to files in Google Drive. The Drive Labels API is a RESTful API that\nsupports business processes by attaching metadata to your Drive\nfiles. Common uses for this API are:\n\n- **Classify content to follow an information governance strategy**---Create a\n label to identify sensitive content or data that requires special handling.\n For example, you might create a badged label (a label with color-coded\n option values) titled \"Sensitivity\" with the values of \"Top Secret,\"\n \"Confidential,\" and \"Public.\"\n\n- **Apply policy to items in Drive**---Create labels to manage\n Drive content throughout its lifecycle and ensure it adheres\n to your organization's record keeping practices. For example, use labels to\n manage a data loss policy (DLP) whereby files with a \"Sensitivity\" label set\n to \"Top Secret\" can't be downloaded to a computer.\n\n- **Curate and find files**---Create labels to increase searchability of your\n company's content by letting people in your organization find items based on\n labels and their fields. For example, someone in your organization could use\n Drive search options to find all contracts awaiting signature\n by a specific date.\n\nBelow is a list of common terms used in the Drive Labels API:\n\n[*Label*](/workspace/drive/labels/reference/rest/v2/labels#resource:-label)\n\n: Structured metadata placed on a Drive file.\n Drive users can assign labels and set label field values for\n files. Labels are composed of:\n\n *Label name*\n : The resource name of the label. The *label ID* makes up part of the\n Label name. Depending on the request, the name is in the form of either:\n `labels/{id}` or `labels/{id}@{revisionId}`. For more information, see\n [Label revision](#revision) below.\n\n *Label ID*\n : A globally unique identifier for the label. The ID makes up part of the\n label name, but unlike the name, it's consistent between revisions.\n\n There are 2 styles of labels:\n\n *Badged label*\n\n : A label with a\n [`SelectionOptions`](/workspace/drive/labels/reference/rest/v2/labels#selectionoptions)\n field type containing *choices* that can be color-coded to indicate\n importance. This is done by setting\n [`badgeConfig`](/workspace/drive/labels/reference/rest/v2/labels#BadgeConfig)\n through the\n [`Properties`](/workspace/drive/labels/reference/rest/v2/labels#properties_1) of a\n [`Choice`](/workspace/drive/labels/reference/rest/v2/labels#choice).\n\n Drive displays the color of the chosen option for each file so users\n clearly understand the status, classification, and so on, of the file.\n For example, the \"Top Secret\" option for the \"Sensitivity\" badged label\n might display in red. You can only have one badged label at a time.\n\n *Standard label*\n\n : A label containing zero or more *field type*s. A standard label might\n have a label title, such as \"Project Moonshot,\" and indicate all files\n related to the project. A standard label might also have several\n structured fields. For example, a label with the title \"Contract\" might\n contain the fields for \"Company,\" \"Due Date,\" \"Status,\" and\n \"Signatories.\" Each field is of a specific type (text, date,\n selection, or user).\n\n|----------------------------|------------------------------|\n| **Figure 1.** Badged label | **Figure 2.** Standard label |\n\n[*Field*](/workspace/drive/labels/reference/rest/v2/labels#field)\n\n: An individual typed, settable component of a label. A label can have zero or\n more fields associated with it.\n\n *Field type*\n : The data type of the value associated with the *field* . Configurable as\n text, integer, date, user, or selection. If you configure the field with\n `ListOptions`, you can set the user and selection fields with multiple\n values. The type chosen impacts both the valid values applicable to\n Drive items and the search query options available.\n\n[*Choice*](/workspace/drive/labels/reference/rest/v2/labels#choice)\n\n: One of several options a user can choose from within a `SelectionOptions`\n field.\n\n[*Label type*](/workspace/drive/labels/reference/rest/v2/labels#labeltype)\n\n: All labels include a `LabelType`. There are 2 types of labels:\n\n *Admin*\n\n : To create and edit admin-owned labels, you must be an account\n administrator with the\n [Manage Labels](https://support.google.com/a/answer/1219251#drive_and_docs)\n privilege.\n\n Admins can share admin labels with any user to grant that user the\n ability to view and apply them to Drive items. Modifying or reading\n label values on Drive items requires the following permissions:\n\n - Modifying---For a user to modify the Drive item metadata related to a\n given label, the user must have the appropriate permission levels:\n\n - Drive item: `EDITOR`\n - Label: `APPLIER`\n - Reading---For a user to read or search for the Drive item metadata\n related to a given label, the user must have the appropriate\n permission levels:\n\n - Drive item: `READER`\n - Label: `READER`\n\n *Shared*\n\n : Non-administrator users can create shared labels that others can apply\n to Drive items. Teams can create and organize their own labels for use\n within the team without requiring an administrator.\n\n | **Note:** Shared labels are only available in a closed beta that isn't currently accepting new customers.\n\n*Label taxonomy*\n\n: The currently configured label fields available to users for application to\n Drive files. Also known as the label schema.\n\n Example label taxonomies:\n\n - Sensitivity---Red, Orange, Yellow, Green\n - Status---Not Started, Draft, In Review, Final\n - Content type---Contract, Design Doc, Mockup\n - Department---Marketing, Finance, Human Resources, Sales\n\n[*Label lifecycle*](/workspace/drive/labels/reference/rest/v2/labels#lifecycle)\n\n: Labels go through a lifecycle where they're created, published, updated, and\n so on. As a label makes it through the lifecycle, its *label revision* is\n incremented. For more information, see [Label lifecycle](/workspace/drive/labels/guides/label-lifecycle).\n\n*Label revision*\n\n: An instance of the label. Anytime a label is created, updated, published, or\n deprecated, the label revision increments.\n\n *Draft revision*\n : The revision number of the current draft instance of the label. You can\n make several updates to a label, each incrementing its draft revision\n number, without affecting the published revision. The ability to have\n draft labels lets you test label updates before publishing.\n\n *Published revision*\n : The revision number of the published version of a label. The published\n label is the instance of the label currently available to users.\n\nRelated topics\n--------------\n\n- To learn about developing with Google Workspace APIs, including handling\n authentication and authorization, refer to [Get started as a\n Google Workspace\n developer](/workspace/guides/getstarted-overview).\n\n- To learn how to configure and run a simple Labels API app, try the\n [Python quickstart](/workspace/drive/labels/quickstart/python)."]]
