Mettre à jour un libellé

Vous pouvez mettre à jour un seul libellé en appliquant un ensemble de requêtes de mise à jour qui génèrent une nouvelle révision brouillon. 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 accepte une liste d'objets Request de mise à jour. Il effectue les mises à jour dans le même ordre que celui spécifié dans la requête par lot. Les mises à jour du lot sont appliquées de manière atomique. En d'autres termes, 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 réussit, la révision brouillon résultante doit être publiée avant que les modifications puissent être utilisées avec un élément Drive.

Mettre à jour les objets de libellé

Un libellé inclut de nombreux autres types d'objets qui peuvent être mis à jour, tels que :

• Propriétés des libellés
• Champs et types de champs
• Choix de sélection et propriétés des 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érations

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

Catégorie	Description
Créer	Ajoutez des objets.
Update	Mettez à jour certaines propriétés d'un objet.
Activer	Activez les objets.
Désactiver	Désactiver des objets
Supprimer	Supprimer des 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 demandes. Voici une répartition des types de demandes, regroupées dans différentes catégories.

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

Masques de champ

De nombreuses demandes de type "Mettre à jour" et "Désactiver" nécessitent un FieldMask. Il s'agit d'une liste de champs séparés par une virgule que vous souhaitez mettre à jour, en laissant les autres champs inchangés. Le masque est obligatoire pour s'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 un caractère générique et est une abréviation pour spécifier chaque champ d'un message. La syntaxe générique 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 demande 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 un administrateur du libellé avant d'autoriser l'accès.

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

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

• Un ou plusieurs Field.

• Une ressource Label qui représente chaque libellé. Il contient une ressource Name et ID, qui est un identifiant unique global pour le libellé.

• LabelView est défini sur LABEL_VIEW_FULL pour définir la vue des ressources appliquée aux réponses des libellés. LABEL_VIEW_FULL renvoie tous les champs possibles.

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

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 sont 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 libellé brouillon. Le libellé State de PUBLISHED avec hasUnpublishedChanges=true signifie qu'il existe des modifications en brouillon, mais qu'elles ne sont pas disponibles pour les utilisateurs. Le libellé modifié doit être PUBLISHED pour que les modifications soient visibles par les utilisateurs. Pour en savoir plus, consultez Cycle de vie des libellés.