Mettre à jour un libellé

Vous pouvez mettre à jour un seul libellé en appliquant un ensemble de requêtes de mise à jour, ce qui génère une nouvelle version provisoire. Par exemple, vous pouvez mettre à jour une propriété de libellé existante (la description du libellé) ou ajouter un Field au libellé.

La mise à jour du libellé agit comme une mise à jour par lot, car la méthode prend une liste d'objets Request à mettre à jour. Il effectue les mises à jour dans le même ordre que celui spécifié dans la requête groupée. Les mises à jour de la mise à jour par lot sont appliquées de manière atomique. Autrement dit, si une requête du lot échoue, la mise à jour entière échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée. Le libellé reste inchangé.

Si la mise à jour aboutit, la version brouillon qui en résulte doit être publiée avant que les modifications ne puissent être utilisées avec un élément Drive.

Modifier les objets de libellé

Un libellé inclut de nombreux autres types d'objets pouvant être mis à jour, par exemple:

• Propriétés du libellé
• Champs et types de champs
• Choix de sélection et propriétés de choix de sélection

Voici quelques-uns des nombreux objets qui contrôlent l'apparence et le fonctionnement d'un libellé.

Catégories d'opération

Les opérations suivantes compatibles avec la méthode labels.delta peuvent être regroupées dans les grandes catégories suivantes:

Catégorie	Description
Créer	Ajoutez des objets.
Mettre à jour	Mettre à jour certaines propriétés d'un objet
Activer	Activez les objets.
Désactiver	Désactiver des objets
Supprimer	Supprimez les objets.

Ces catégories sont utilisées dans la section suivante pour décrire le comportement d'opérations spécifiques.

Demandes de mises à jour

La méthode labels.delta fonctionne en prenant un ou plusieurs objets Request, chacun spécifiant un seul type de requête à effectuer. Il existe de nombreux types de requêtes. Voici une répartition des types de requêtes, regroupées en différentes catégories.

Type de requête
Propriétés des libellés	Mettre à jour UpdateLabelPropertiesRequest
Champ	Créer CreateFieldRequest Mettre à jour UpdateFieldPropertiesRequest UpdateFieldTypeRequest Activer EnableFieldRequest Désactiver DisableFieldRequest Supprimer DeleteFieldRequest
Sélection	Créer CreateSelectionChoiceRequest Mettre à jour UpdateSelectionChoicePropertiesRequest Activer EnableSelectionChoiceRequest Désactiver DisableSelectionChoiceRequest Supprimer DeleteSelectionChoiceRequest

Masques de champ

De nombreuses requêtes de type "Mettre à jour" et "Désactiver" nécessitent un FieldMask. Il s'agit d'une liste de champs à mettre à jour, séparés par une virgule, tout en laissant les autres champs inchangés. Le masque est nécessaire pour vous assurer que seuls les champs que vous souhaitez modifier sont mis à jour. Vous devez spécifier au moins un champ.

Un masque de champ * est traité comme une étoile de remplacement et permet de spécifier tous les champs d'un message. La syntaxe d'espace réservé peut produire des résultats indésirables, car un champ peut revenir à son état par défaut si vous ne spécifiez pas de valeur pour celui-ci dans la requête de mise à jour. Pour les applications de production, listez toujours les champs spécifiques mis à jour dans les masques de champ et évitez d'utiliser des caractères génériques *.

Exemple

Pour mettre à jour un libellé, utilisez la méthode delta sur la collection labels.

Vous devez également spécifier les éléments suivants:

• useAdminAccess est true pour utiliser les identifiants administrateur de l'utilisateur. Le serveur vérifie que l'utilisateur est administrateur du libellé avant d'autoriser l'accès.

• Request qui spécifie les mises à jour applicables au libellé.

• Un libellé title via la méthode property.

• Un ou plusieurs Field.

• Ressource de libellé représentant chaque libellé. Il contient une ressource Name et ID, qui est un identifiant unique global pour le libellé.

• LabelView est LABEL_VIEW_FULL pour définir la vue de ressources appliquée aux réponses d'étiquetage. LABEL_VIEW_FULL renvoie tous les champs possibles.

Cet exemple utilise ID pour mettre à jour le libellé correct.

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);
});

Le libellé, le champ ou le choix est mis à jour, l'ID de révision du libellé est incrémenté et le libellé est stocké dans une base de données en tant que brouillon. Le libellé comporte le State de PUBLISHED avec hasUnpublishedChanges=true, ce qui signifie qu'il existe des modifications de brouillon, mais qu'elles ne sont pas disponibles pour les utilisateurs. Le libellé mis à jour doit être PUBLISHED pour que les modifications soient visibles par les utilisateurs. Pour en savoir plus, consultez la section Cycle de vie des libellés.