Aktualisieren Sie ein Label

Sie können ein einzelnes Label aktualisieren, indem Sie eine Reihe von Aktualisierungsanfragen stellen, die zu einer neuen Draft-Version führen. Sie können beispielsweise ein vorhandenes Labelattribut (die Labelbeschreibung) aktualisieren oder dem Label ein neues Field hinzufügen.

Die Label-Aktualisierung erfolgt als Batch-Aktualisierung, da die Methode eine Liste von Request-Objekten für die Aktualisierung akzeptiert. Die Aktualisierungen erfolgen in der gleichen Reihenfolge wie in der Batch-Anfrage angegeben. Die Updates im Batch-Update werden in kleinstmöglichen Schritten angewendet. Wenn also eine Anfrage im Batch fehlschlägt, schlägt die gesamte Aktualisierung fehl und keine der (möglicherweise abhängigen) Änderungen wird angewendet. Das Label bleibt unverändert.

Wenn die Aktualisierung erfolgreich ist, muss die resultierende Draft-Revision veröffentlicht werden, bevor die Änderungen für ein Drive-Element verwendet werden können.

Label-Objekte aktualisieren

Ein Label umfasst viele andere Objekttypen, die aktualisiert werden können, z. B.:

• Label-Eigenschaften
• Felder und Feldtypen
• Auswahlmöglichkeiten und Auswahlmöglichkeiten-Properties

Dies sind nur einige der vielen Objekte, mit denen die Darstellung und Funktionsweise eines Labels gesteuert werden kann.

Vorgangskategorien

Die folgenden von der Methode labels.delta unterstützten Vorgänge können in die folgenden Kategorien eingeteilt werden:

Kategorie	Beschreibung
Erstellen	Objekte hinzufügen
Aktualisieren	Bestimmte Attribute eines Objekts aktualisieren
Aktivieren	Objekte aktivieren
Deaktivieren	Objekte deaktivieren
Löschen	Objekte entfernen

Diese Kategorien werden im nächsten Abschnitt verwendet, um das Verhalten bestimmter Vorgänge zu beschreiben.

Aktualisierungs-Anfragen

Die Methode labels.delta verwendet ein oder mehrere Request-Objekte, die jeweils einen einzelnen auszuführenden Anforderungstyp angeben. Es gibt viele verschiedene Arten von Anfragen. Im Folgenden finden Sie eine Aufschlüsselung der Anfragetypen, gruppiert in verschiedene Kategorien.

Art der Anfrage
Label Properties	Aktualisieren UpdateLabelPropertiesRequest
Feld	Erstellen CreateFieldRequest Aktualisieren UpdateFieldPropertiesRequest UpdateFieldTypeRequest Aktivieren EnableFieldRequest Deaktivieren DisableFieldRequest Löschen DeleteFieldRequest
Auswahl	Erstellen CreateSelectionChoiceRequest Aktualisieren UpdateSelectionChoicePropertiesRequest Aktivieren EnableSelectionChoiceRequest Deaktivieren DisableSelectionChoiceRequest Löschen DeleteSelectionChoiceRequest

Feldmasken

Für viele Anfragen vom Typ „Aktualisieren“ und „Deaktivieren“ ist eine FieldMask erforderlich. Dies ist eine durch Kommas getrennte Liste von Feldern, die Sie aktualisieren möchten, während die anderen Felder unverändert bleiben. Die Maske ist erforderlich, damit nur die Felder aktualisiert werden, die Sie bearbeiten möchten. Sie müssen mindestens ein Feld angeben.

Eine Feldmaske von * wird wie ein Platzhalter behandelt und ist eine Kurzform für die Angabe jedes Felds in einer Nachricht. Die Platzhaltersyntax kann zu unerwünschten Ergebnissen führen, da ein Feld möglicherweise in den Standardzustand zurückkehrt, wenn Sie in der Aktualisierungsanfrage keinen Wert dafür angeben. Bei Produktionsanwendungen sollten Sie immer die spezifischen Felder auflisten, die in Feldmasken aktualisiert werden, und die Verwendung von *-Wildcards vermeiden.

Beispiel

Verwenden Sie zum Aktualisieren eines Labels die Methode delta in der Sammlung labels.

Außerdem müssen Sie Folgendes angeben:

• useAdminAccess ist true, um die Administratoranmeldedaten des Nutzers zu verwenden. Der Server prüft, ob der Nutzer Administrator für das Label ist, bevor er den Zugriff zulässt.

• Ein Request, das die anwendbaren Aktualisierungen des Labels angibt.

• Ein Label title über die Methode property.

• Mindestens eine Field.

• Eine Label-Ressource, die jedes Label darstellt. Sie enthält eine Ressource Name und ID, eine global eindeutige Kennung für das Label.

• LabelView ist LABEL_VIEW_FULL, um die Ressourcenansicht für Labelantworten festzulegen. LABEL_VIEW_FULL gibt alle möglichen Felder zurück.

In diesem Beispiel wird das ID verwendet, um das richtige Label zu aktualisieren.

Python

body = {
'use_admin_access': True,
'requests': [{
  'update_label': {
    'properties': {
      'title': 'TITLE'
    },
    'update_mask': {
      'paths': ['title']
    }
  },
}, {
  'create_field': {
    'field': {
      'properties': {
        'display_name': 'DISPLAY_NAME'
      },
      'text_options': {}
    }
  }
}],
'view': 'LABEL_VIEW_FULL'
}
response = service.labels().delta(
  body=body,
  name='labels/ID').execute()

Node.js

var body = {
  'use_admin_access': true,
  'requests': [{
    'update_label': {
      'properties': {
        'title': 'TITLE'
      },
      'update_mask': {
        'paths': ['title']
      }
    },
  }, {
    'create_field': {
      'field': {
        'properties': {
          'display_name': 'DISPLAY_NAME'
        },
        'text_options': {}
      }
    }
  }],
  'view': 'LABEL_VIEW_FULL'
};
service.labels.delta({
  'resource': body,
  'name': 'labels/ID'
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Das Label, Feld oder die Auswahl wird aktualisiert, die Revisions-ID des Labels wird erhöht und das Label wird als Entwurf in einer Datenbank gespeichert. Das Label hat den State-Status von PUBLISHED mit hasUnpublishedChanges=true. Das bedeutet, dass es Änderungen am Entwurf gibt, die aber für Nutzer nicht verfügbar sind. Das aktualisierte Label muss PUBLISHED sein, bevor die Änderungen für Nutzer sichtbar werden. Weitere Informationen finden Sie unter Label-Lebenszyklus.