Drive Labels API – Übersicht

Labels sind Metadaten, die Sie definieren, um Nutzern beim Organisieren, Suchen und Anwenden von Richtlinien auf Dateien in Google Drive zu helfen. Die Drive Labels API ist eine REST API, die Geschäftsprozesse unterstützt, indem Metadaten an Ihre Drive-Dateien angehängt werden. Diese API wird häufig für Folgendes verwendet:

  • Inhalte gemäß einer Strategie zur Informationssteuerung klassifizieren: Erstellen Sie ein Label, um sensible Inhalte oder Daten zu identifizieren, die eine besondere Behandlung erfordern. Sie können beispielsweise ein Badge-Label (ein Label mit farbcodierten Optionswerte) mit dem Titel „Sensitivity“ (Vertraulichkeit) mit den Werten „Streng geheim“, „Vertraulich“ und „Öffentlich“ erstellen.

  • Richtlinien auf Elemente in Drive anwenden: Erstellen Sie Labels, um Drive-Inhalte während ihres gesamten Lebenszyklus zu verwalten und dafür zu sorgen, dass sie den Aufbewahrungsrichtlinien Ihrer Organisation entsprechen. Sie können beispielsweise Labels zum Verwalten einer Richtlinie für den Datenverlust (DLP) verwenden, bei der Dateien mit dem Label „Vertraulichkeit“ auf „Streng geheim“ nicht auf einen Computer heruntergeladen werden können.

  • Dateien auswählen und suchen: Erstellen Sie Labels, um die Suche nach den Inhalten Ihres Unternehmens zu verbessern. Personen in Ihrer Organisation können Elemente anhand von Labels und Feldern suchen. Beispielsweise kann eine Person in Ihrer Organisation die Drive-Suchoptionen verwenden, um alle Verträge zu finden, die bis zu einem bestimmten Datum unterschrieben sind.

Die folgende Liste enthält gängige Begriffe, die in der Drive Labels API verwendet werden:

Label

Strukturierte Metadaten in einer Drive-Datei. Drive-Nutzer können Labels zuweisen und Labelfeldwerte für Dateien festlegen. Labels bestehen aus:

Label name
Der Ressourcenname des Labels. Die Label-ID ist Teil des Labelnamens. Je nach Anfrage hat der Name das Format labels/{id} oder labels/{id}@{revisionId}. Weitere Informationen finden Sie unter Labelüberarbeitung unten.
Label-ID
Eine global eindeutige Kennung für das Label. Die ID gehört zum Labelnamen, unterscheidet sich aber im Namen zwischen den Überarbeitungen.

Es gibt zwei Arten von Labels:

Badge-Label

Ein Label mit dem Feldtyp SelectionOptions, der choices enthält und farblich gekennzeichnet werden kann, um die Wichtigkeit anzugeben. Legen Sie dazu badgeConfig über Properties einer Choice fest.

In Google Drive wird für jede Datei die Farbe der ausgewählten Option angezeigt, damit Nutzer den Status, die Klassifizierung usw. der Datei deutlich verstehen können. Die Option „Streng geheim“ für das Label „Vertraulichkeit“ kann beispielsweise rot angezeigt werden. Sie können jeweils nur ein Badge-Label haben.

Standard label

Ein Label, das null oder mehr Feldtypen enthält. Ein Standardlabel kann einen Labeltitel wie „Project Moonshot“ haben und alle Dateien enthalten, die sich auf das Projekt beziehen. Ein Standardlabel kann auch mehrere strukturierte Felder haben. Ein Label mit dem Titel „Vertrag“ kann beispielsweise die Felder für „Unternehmen“, „Fälligkeitsdatum“, „Status“ und „Unterzeichner“ enthalten. Jedes Feld hat einen bestimmten Typ (Text, Datum, Auswahl oder Nutzer).

Diagramm mit Badge-Label
Abbildung 1: Badge-Label
Diagramm mit Standardlabels
Abbildung 2: Standard label
Feld

Eine einzelne typisierte, einstellbare Komponente eines Labels. Einem Label können null oder mehr Felder zugeordnet sein.

Feldtyp
Der Datentyp des Werts, der mit dem Feld verknüpft ist. Kann als Text, Ganzzahl, Datum, Nutzer oder Auswahl konfiguriert werden. Wenn Sie das Feld mit ListOptions konfigurieren, können Sie die Nutzer- und Auswahlfelder mit mehreren Werten festlegen. Der ausgewählte Typ wirkt sich sowohl auf die gültigen Werte für Drive-Elemente als auch auf die verfügbaren Abfrageoptionen aus.
Auswahl

Eine von mehreren Optionen, die Nutzer in einem SelectionOptions-Feld auswählen können.

Labeltyp

Alle Labels enthalten ein LabelType. Es gibt zwei Arten von Labels:

Administrator

Zum Erstellen und Bearbeiten von Administratorlabels müssen Sie ein Kontoadministrator mit der Berechtigung Labels verwalten sein.

Administratoren können Administratorlabels für beliebige Nutzer freigeben, um ihnen die Möglichkeit zu geben, sie anzusehen und auf Drive-Elemente anzuwenden. Zum Ändern oder Lesen von Labelwerten für Drive-Elemente sind folgende Berechtigungen erforderlich:

  • Ändern: Damit ein Nutzer die Metadaten von Drive-Elementen eines bestimmten Labels ändern kann, muss er die entsprechenden Berechtigungsstufen haben:

    • Drive-Element: EDITOR
    • Label: APPLIER

  • Lesen: Damit ein Nutzer die Metadaten eines Drive-Elements lesen oder danach suchen kann, die sich auf ein bestimmtes Label beziehen, muss er die entsprechenden Berechtigungsstufen haben:

    • Drive-Element: READER
    • Label: READER
Freigegeben

Nutzer ohne Administratorberechtigung können gemeinsame Labels erstellen, die andere auf Drive-Elemente anwenden können. Teams können ihre eigenen Labels für die Verwendung im Team erstellen und organisieren, ohne dass ein Administrator erforderlich ist.

Taxonomie der Labels

Die aktuell konfigurierten Labelfelder, die Nutzern für die Anwendung auf Drive-Dateien zur Verfügung stehen. Auch als Labelschema bezeichnet.

Beispiele für Labeltaxonomien:

  • Empfindlichkeit – rot, orange, gelb, grün
  • Status: Nicht begonnen, Entwurf, Wird überprüft, Abgeschlossen
  • Inhaltstyp: Vertrag, Designdokument, Modell
  • Abteilung – Marketing, Finanzen, Personalwesen, Vertrieb
Labellebenszyklus

Labels durchlaufen einen Lebenszyklus, in dem sie erstellt, veröffentlicht, aktualisiert usw. werden. Wenn ein Label den gesamten Lebenszyklus durchläuft, erhöht sich seine Labelüberarbeitung. Weitere Informationen finden Sie unten im Abschnitt Labellebenszyklus.

Labelüberarbeitung

Eine Instanz des Labels. Jedes Mal, wenn ein Label erstellt, aktualisiert, veröffentlicht oder verworfen wird, erhöht sich die Label-Überarbeitung.

Überarbeitungsentwurf
Die Überarbeitungsnummer der aktuellen Entwurfsinstanz des Labels. Sie können ein Label mehrmals aktualisieren, ohne dass sich dies auf die veröffentlichte Überarbeitung auswirkt. Mit Labelentwürfen lassen sich Labels vor der Veröffentlichung testen.
Veröffentlichte Überarbeitung
Die Überarbeitungsnummer der veröffentlichten Version eines Labels. Das veröffentlichte Label ist die Instanz des Labels, das Nutzern derzeit zur Verfügung steht.

Labellebenszyklus

Labels, Felder und Auswahlen haben während ihres gesamten Lebens bestimmte Status. Außerdem können Labels verschiedene Überarbeitungen haben. Das folgende Diagramm zeigt den Labellebenszyklus, einschließlich Überarbeitung:

Diagramm zum Lebenszyklus von Labels
Abbildung 3: Lebenszyklus eines Labels
  1. Label erstellen (create()): Das Label wird in einer Datenbank als revision_id=1 erstellt und gespeichert. Das Label hat den Status UNPUBLISHED_DRAFT. In diesem Status gilt:
    • Nutzer können das Label nicht sehen
    • Nutzer können das Label nicht auf Drive-Elemente anwenden.
  2. (Optional) Label, Feld oder Auswahl aktualisieren (delta()) – Jede Aktualisierung wird in einer Datenbank gespeichert, auch wenn sie noch nicht veröffentlicht wurde, auch wenn sie noch nicht veröffentlicht wurde.
  3. Label veröffentlichen (publish()): Das Label hat den Status PUBLISHED und Nutzer können das Label anwenden. Durch die Veröffentlichung des Labels erhöht sich seine Überarbeitung.
  4. (Optional) Label, Feld oder Auswahl aktualisieren (delta()): Das Label, Feld oder die Auswahl wird aktualisiert und in einer Datenbank als Entwurfs-Label gespeichert. Das Label PUBLISHED hat den Status hasUnpublishedChanges=true. Dies bedeutet, dass es Entwurfsänderungen gibt, die Nutzern aber nicht zur Verfügung stehen. Jede Aktualisierung erhöht die Überarbeitung des Labels.
  5. Optional: Label veröffentlichen (publish()): Der aktuelle Entwurf wird veröffentlicht, sofern verfügbar. Das Label hat den Status PUBLISHED und Nutzer können das Label anwenden. Durch das Veröffentlichen des Labels erhöht sich seine Version.
  6. Label deaktivieren (disable()): Das Label hat den Status DISABLED, aber Nutzer können das Label über die API anwenden. Ein deaktiviertes Label wird jedoch in der Benutzeroberfläche nur angezeigt, wenn es konfiguriert ist. Durch das Verwerfen eines Labels erhöht sich seine Überarbeitung.
  7. Label aktivieren (enable()): Das Label wird auf den Status PUBLISHED zurückgesetzt und Nutzer können das Label anwenden. Durch die Veröffentlichung des Labels erhöht sich seine Überarbeitung.
  8. Label löschen (delete()): Das Label hat den Status DELETED und kann nicht angewendet werden. Gelöschte Labels werden schließlich dauerhaft gelöscht.

Es ist wichtig zu betonen, dass jede Aktualisierung eines Labels die Überarbeitung des Labels erhöht. Wenn das Label bereits veröffentlicht wurde und Sie es nach n Updates noch einmal veröffentlichen, bedeutet dies, dass die veröffentlichte Überarbeitungsnummer eine Überarbeitung + n + 1 von aufeinanderfolgenden Aktualisierungen ist.

Nächste Schritte

  • Informationen zum Entwickeln mit Google Workspace APIs, einschließlich der Authentifizierung und Autorisierung, finden Sie unter Erste Schritte als Workspace-Entwickler.

  • Informationen zum Konfigurieren und Ausführen einer einfachen Labels API-App finden Sie in der Kurzanleitung.