Descripción general de la API de etiquetas de Drive

Las etiquetas son metadatos que defines para ayudar a los usuarios a organizar, encontrar y aplicar políticas en los archivos de Google Drive. La API de Drive Labels es una API de RESTful que admite procesos empresariales mediante la conexión de metadatos a tus archivos de Drive. Los siguientes son los usos comunes de esta API:

  • Clasifica contenido para seguir una estrategia de administración de la información: crea una etiqueta que te permita identificar contenido sensible o datos que requieran un manejo especial. Por ejemplo, puedes crear una etiqueta con insignia (una etiqueta con valores de opción codificados por color) titulada “Sensibilidad” con los valores “Secreto secreto”, “Confidencial” y “Público”.

  • Aplica políticas a elementos en Drive: Crea etiquetas para administrar el contenido de Drive durante todo su ciclo de vida y asegúrate de que cumpla con las prácticas de conservación de registros de tu organización. Por ejemplo, usa etiquetas para administrar una política de pérdida de datos (DLP) en la que los archivos con la etiqueta “Sensibilidad” configurada como “Secreto secreto” no se puedan descargar en una computadora.

  • Selecciona y busca archivos: Para aumentar la capacidad de búsqueda del contenido de tu empresa, permite que los miembros de tu organización encuentren elementos basados en etiquetas y en sus campos. Por ejemplo, un miembro de tu organización podría usar las opciones de búsqueda de Drive para buscar todos los contratos que esperan la firma antes de una fecha específica.

A continuación, se muestra una lista de términos comunes que se usan en la API de etiquetas de Drive:

Etiqueta

Metadatos estructurados ubicados en un archivo de Drive Los usuarios de Drive pueden asignar etiquetas y establecer valores de campo de etiqueta para los archivos. Las etiquetas contienen lo siguiente:

Nombre de la etiqueta
El nombre del recurso de la etiqueta. El ID de etiqueta forma parte del nombre de la etiqueta. Según la solicitud, el nombre puede tener el formato labels/{id} o labels/{id}@{revisionId}. Para obtener más información, consulta Revisión de la etiqueta a continuación.
ID de etiqueta
Un identificador único 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 codificadas por colores para indicar la importancia Para ello, se debe configurar badgeConfig a través de Properties de un Choice.

Drive muestra el color de la opción elegida para cada archivo a fin de que los usuarios comprendan con claridad el estado del archivo, su clasificación y demás. Por ejemplo, la opción “Secreto” (Top Secret) de la etiqueta con la insignia “Confidencialidad” (Sensitivity) puede mostrarse en rojo. Solo puedes tener una etiqueta a la vez.

Etiqueta estándar

Una etiqueta que contiene cero o más tipos de campo Una etiqueta estándar puede tener un título de etiqueta, como “Project Moonshot”, y también 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” puede contener los campos “Empresa”, “Fecha de vencimiento”, “Estado” y “Firmantes”. Cada campo sería de un tipo específico (texto, fecha, selección o usuario).

Diagrama de etiqueta con distintivo.
Figura 1: Etiqueta con distintivo
Diagrama de etiquetas estándar
Figura 2: Etiqueta estándar
Campo

Un componente individual configurable de una etiqueta. Una etiqueta puede tener cero o más campos asociados.

Tipo de campo
El tipo de datos del valor asociado con el campo. Se puede configurar como texto, número entero, fecha, usuario o selección. Si configuras el campo con ListOptions, puedes configurar el usuario y los campos de selección con varios valores. El tipo elegido afecta a los valores válidos aplicables a los elementos de Drive y las opciones de búsqueda disponibles.
Opción

Una de las varias opciones que un usuario puede elegir en un campo SelectionOptions

Tipo de etiqueta

Todas las etiquetas incluyen un LabelType. Existen 2 tipos de etiquetas:

Administrador

Para crear y editar etiquetas que son propiedad del administrador, debes ser administrador de la cuenta con el privilegio Administrar etiquetas.

Los administradores pueden compartir etiquetas de administrador con cualquier usuario para otorgarle la capacidad de ver y aplicar elementos a Drive. Modificar o leer valores de etiquetas en elementos de Drive requiere los siguientes permisos:

  • Modificación: para que un usuario modifique los metadatos de los elementos 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 elementos 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 otras personas pueden aplicar a los 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

Los campos de etiqueta configurados actualmente, disponibles para los usuarios y que se envíen a los archivos de Drive. También conocido como esquema de etiqueta.

Ejemplo de taxonomías de etiquetas:

  • Sensibilidad: rojo, naranja, amarillo, verde
  • Estado: No iniciado, Borrador, En revisión, Final
  • Tipo de contenido: Contrato, Documento de diseño, Simulación
  • Departamento: Marketing, Finanzas, Recursos Humanos, Ventas
Ciclo de vida de las etiquetas

Las etiquetas pasan por un ciclo de vida en el que se crean, publican, actualizan, etcétera. A medida que pasa el tiempo de la etiqueta, la revisión de la etiqueta aumenta. Para obtener más información, consulta Ciclo de vida de las etiquetas a continuación.

Revisión de la etiqueta

Una instancia de la etiqueta. Cada vez que se crea, actualiza, publica o deja de estar disponible una etiqueta, la revisión se incrementa.

Revisión en borrador
Es el número de revisión de la instancia de borrador actual de la etiqueta. Puedes realizar varias actualizaciones en una etiqueta, y cada una aumentará el número de borrador de la revisión, sin afectar la revisión publicada. La capacidad de tener etiquetas de borrador te permite probar las actualizaciones de las etiquetas antes de publicarlas.
Revisión publicada
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 actualmente para los usuarios.

Ciclo de vida de las etiquetas

Las etiquetas, los campos y las opciones pasan por estados específicos a lo largo de sus vidas. Además, las etiquetas pueden tener diferentes revisiones. En el siguiente diagrama, se muestra el ciclo de vida de la etiqueta, incluida la revisión:

Diagrama del ciclo de vida de las etiquetas
Figura 3: Ciclo de vida de una etiqueta
  1. Crear una etiqueta (create()): la etiqueta se crea y almacena en una base de datos como revision_id=1. La etiqueta tiene el estado UNPUBLISHED_DRAFT. En este estado:
    • Los usuarios no pueden ver la etiqueta
    • Los usuarios no pueden aplicar la etiqueta a elementos de Drive.
  2. (Opcional) Actualiza una etiqueta, un campo o una opción (delta()): Cada actualización, incluso antes de publicarla, se almacena en una base de datos y se incrementa la revisión de la etiqueta.
  3. Publica una etiqueta (publish()): la etiqueta tiene el estado PUBLISHED y los usuarios pueden aplicarla. Publicar la etiqueta aumenta su revisión.
  4. (Opcional) Actualiza una etiqueta, un campo o una opción (delta()): La etiqueta, el campo o la elección se actualizan y se almacenan en una base de datos como una etiqueta de borrador. La etiqueta tiene el estado PUBLISHED con hasUnpublishedChanges=true, lo que significa que hay cambios en borrador, pero no están disponibles para los usuarios. Cada actualización aumenta la revisión de la etiqueta.
  5. (Opcional) Publica una etiqueta (publish()): Si está disponible, se publica el borrador más actual. La etiqueta tiene el estado PUBLISHED, y los usuarios pueden aplicarla. La publicación de la etiqueta aumenta su versión.
  6. Inhabilitar una etiqueta (disable()): la etiqueta tiene el estado DISABLED, aunque los usuarios pueden aplicarla mediante la API. Sin embargo, no se muestra una etiqueta inhabilitada en una IU, a menos que esté configurada para mostrarse. Dar de baja la etiqueta aumenta su revisión.
  7. Habilitar una etiqueta (enable()): la etiqueta vuelve al estado PUBLISHED y los usuarios pueden aplicarla. Publicar la etiqueta aumenta su revisión.
  8. Borra una etiqueta (delete()): la etiqueta tiene un estado DELETED y no se puede aplicar. Las etiquetas borradas se borran definitivamente.

Es importante hacer hincapié en que cada actualización a una etiqueta aumenta la revisión de la etiqueta. Si la etiqueta ya se publicó, vuelve a publicarla después de n actualizaciones, lo que significa que su número de revisión publicado es revisión + n + 1 cantidad de actualizaciones sucesivas.

Próximos pasos