Créer et publier un libellé

Ce document explique comment créer et publier des libellés à l'aide de l'API Google Drive Labels.

Créer un libellé

Pour créer un libellé, utilisez la méthode create sur la ressource labels. Les libellés peuvent éventuellement contenir un ou plusieurs objets Field.

Vous devez également spécifier :

L'exemple de code suivant montre comment utiliser la méthode create pour créer un libellé administrateur standard avec un titre spécifié et un SelectionOptions Field avec deux objets Choice.

Python

label_body = {
    'labelType': 'ADMIN',
    'properties': {
        'title': 'TITLE'
    },
    'fields': [{
        'properties': {
            'displayName': 'DISPLAY_NAME'
        },
        'selectionOptions': {
            'listOptions': {},
            'choices': [{
                'properties': {
                    'displayName': 'CHOICE_1'
                }
            }, {
                'properties': {
                    'displayName': 'CHOICE_2'
                }
            }]
        }
    }]
}
response = service.labels().create(
    body=label_body, useAdminAccess=True).execute()

Node.js

var label = {
  'labelType': 'ADMIN',
  'properties': {
    'title': 'TITLE'
  },
  'fields': [{
    'properties': {
      'displayName': 'DISPLAY_NAME'
    },
    'selectionOptions': {
      'listOptions': {},
      'choices': [{
        'properties': {
          'displayName': 'CHOICE_1'
        }
      }, {
        'properties': {
          'displayName': 'CHOICE_2'
        }
      }]
    }
  }]
};

service.labels.create({
  requestBody: label,
  useAdminAccess: true
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Remplacez les éléments suivants :

  • TITLE : titre du libellé.
  • DISPLAY_NAME : nom à afficher du champ.
  • CHOICE_1 : premier choix dans le champ SelectionOptions.
  • CHOICE_2 : deuxième choix dans le champ SelectionOptions.

Le libellé est créé dans UNPUBLISHED_DRAFT State. Le libellé doit être PUBLISHED pour être visible par les utilisateurs et utilisable sur les fichiers. Pour en savoir plus, consultez Cycle de vie des libellés.

Limites des libellés

Les limites suivantes s'appliquent lorsque vous créez et appliquez des libellés :

  • Libellés standards : 150
  • Champs par libellé : 10

Utiliser des champs dans les libellés

Le tableau suivant décrit les types de champs que vous pouvez ajouter à un libellé, la façon dont les utilisateurs interagissent avec eux, ainsi que les considérations et limites concernant leur format :

Field Type Actions possibles Remarques sur le format et limites
SelectionOptions Sélectionner une ou plusieurs options dans une liste Nombre maximal d'options acceptées : 200
Nombre maximal de sélections pour un fichier : 10, comme configuré dans ListOptions
IntegerOptions Saisir une valeur numérique Seuls les nombres entiers sont acceptés.
DateOptions Sélectionner une date de calendrier (Facultatif) Vous pouvez définir DateFormat sur "Long : Mois JJ, AAAA" ou "Court : MM/JJ/AA".
TextOptions Saisir du texte dans une zone de texte Le nombre maximal de caractères est de 100.
UserOptions Sélectionnez un ou plusieurs utilisateurs dans les contacts Google Workspace. Le nombre maximal d'entrées utilisateur pour un fichier est de 10, comme configuré dans ListOptions.

Publier un libellé

L'API Drive Labels vous permet de publier un brouillon de libellé une fois qu'il est terminé. L'étiquette est alors visible par les utilisateurs et peut être appliquée aux fichiers.

Pour publier un libellé, utilisez la méthode publish sur la ressource labels et spécifiez :

  • Ressource labels représentant chaque libellé. Il contient une ressource name et un id, qui est un identifiant unique global pour le libellé.

  • Le paramètre de requête useAdminAccess est défini sur true pour utiliser les identifiants d'administrateur de l'utilisateur. Avant d'autoriser l'accès, le serveur vérifie que l'utilisateur dispose des droits d'administrateur Gérer les libellés de classification requis.

L'exemple de code suivant montre comment utiliser id du libellé pour identifier et publier le libellé correct.

Python

service.labels().publish(
    name='labels/ID',
    body={
        'useAdminAccess': True
    }
).execute()

Node.js

service.labels.publish({
  name: 'labels/ID',
  requestBody: {
    useAdminAccess: true
  }
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Remplacez ID par l'ID du libellé à publier.

Une fois le libellé publié, il est déplacé vers PUBLISHED State et l'ID de révision du libellé est incrémenté. Le libellé est alors visible par les utilisateurs et peut être appliqué aux fichiers. Pour en savoir plus, consultez Cycle de vie des libellés.

Contraintes lors de la publication de libellés

Lorsque vous vous préparez à publier des libellés, tenez compte des contraintes suivantes :

  • Une fois publié, un libellé ne peut plus revenir à son état de brouillon d'origine. Pour en savoir plus, consultez Cycle de vie des libellés.

  • La publication d'un libellé crée une révision nouvellement publiée. Toutes les révisions de brouillon précédentes sont supprimées. Les révisions précédemment publiées sont conservées, mais peuvent être supprimées automatiquement si nécessaire.

  • Une fois la fiche publiée, certaines modifications ne sont plus autorisées. En règle générale, cela signifie que toute modification qui invalide ou déclenche de nouvelles restrictions sur les métadonnées existantes associées au label est refusée. Par exemple, les modifications suivantes apportées à une étiquette ne sont pas autorisées une fois l'étiquette publiée :

    • Le libellé est directement supprimé. (Vous devez d'abord le désactiver, puis le supprimer.)
    • La valeur Field.FieldType a été modifiée.
    • Les mises à jour apportées aux options de validation Field refusent ce qui était auparavant accepté.
    • Une réduction du nombre maximal d'entrées.