Renvoyer des champs spécifiques

Ce document explique comment utiliser le paramètre fields dans Google Drive.

Pour renvoyer les champs exacts dont vous avez besoin et améliorer les performances, utilisez le fields paramètre système dans votre appel de méthode.

Pour en savoir plus sur les autres paramètres système qui s'appliquent à l'API Drive, consultez Paramètres système alternatifs.

Fonctionnement du paramètre fields

Le paramètre fields utilise un FieldMask pour le filtrage des réponses. Les masques de champ permettent de spécifier un sous-ensemble de champs qu'une requête doit renvoyer. L'utilisation d'un masque de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles, ce qui permet de réduire le temps de traitement.

Si vous ne spécifiez pas le paramètre fields, le serveur renvoie un ensemble de champs par défaut spécifique à la méthode. Par exemple, la list méthode de la files méthode ne renvoie que les champs kind, id, name, et mimeType. La méthode get de la ressource permissions renvoie un ensemble différent de champs par défaut.

Pour toutes les méthodes des ressources about, comments (à l'exception de delete) et replies (à l'exception de delete), vous devez définir le paramètre fields. Ces méthodes ne renvoient pas d'ensemble de champs par défaut.

Une fois qu'un serveur a traité une requête valide incluant le paramètre fields, il renvoie le code d'état HTTP 200 OK ainsi que les données demandées. Si le paramètre fields comporte une erreur ou s'il n'est pas valide pour une autre raison, le serveur renvoie le code d'état HTTP 400 Bad Request, ainsi qu'un message d'erreur indiquant la raison pour laquelle votre sélection de champs est incorrecte. Par exemple, files.list(fields='files(id,capabilities,canAddChildren)') génère l'erreur "Invalid field selection canAddChildren." Le paramètre fields correct pour cet exemple est files.list(fields='files(id,capabilities/canAddChildren)').

Pour déterminer les champs que vous pouvez renvoyer à l'aide du paramètre fields, consultez la page de documentation de la ressource que vous interrogez. Par exemple, pour voir les champs que vous pouvez renvoyer pour un fichier, consultez la documentation de la ressource files. Pour en savoir plus sur les termes de requête spécifiques aux fichiers, consultez Termes de requête et opérateurs de recherche.

Règles de format du paramètre fields

Le format de la valeur du paramètre de requête fields repose globalement sur la syntaxe XPath. Voici les règles de format pour le paramètre fields. Toutes ces règles utilisent des exemples liés à la méthode files.get.

• Incluez une liste dont les éléments sont séparés par une virgule pour sélectionner plusieurs champs, par exemple 'name, mimeType'.

• Utilisez a/b pour sélectionner un champ b imbriqué dans le champ a, par exemple 'capabilities/canDownload'. Pour en savoir plus, consultez Récupérer les champs d' une ressource imbriquée.

• Incluez un sous-sélecteur pour demander un ensemble de sous-champs spécifiques de tableaux ou d' objets en plaçant des expressions entre parenthèses : "()". Par exemple, 'permissions(id)' ne renvoie que l'ID d'autorisation pour chaque élément du tableau d'autorisations.

• Pour renvoyer tous les champs d'un objet, utilisez un astérisque (*) comme caractère générique dans les sélections de champs. Par exemple, 'permissions/permissionDetails/*' sélectionne tous les champs de détails d'autorisation disponibles par autorisation. Notez que l'utilisation du caractère générique peut avoir un impact négatif sur les performances de la requête.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Récupérer les champs d'une ressource imbriquée

Lorsqu'un champ fait référence à une autre ressource, vous pouvez spécifier les champs de la ressource imbriquée à récupérer.

Par exemple, pour récupérer le champ role (ressource imbriquée) de la ressource permissions, utilisez l'une des options suivantes :

• permissions.get avec fields=role.
• permissions.get avec fields=* pour afficher tous les champs permissions.
• files.get avec fields=permissions(role) ou fields=permissions/role.
• files.get avec fields=permissions pour afficher tous les champs permissions.
• changes.list avec fields=changes(file(permissions(role))).

Pour récupérer plusieurs champs, utilisez une liste d'éléments séparés par une virgule. Par exemple, files.list avec fields=files(id,name,createdTime,modifiedTime,size).

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

Paramètres système alternatifs

Les paramètres de requête qui s'appliquent à toutes les opérations de l'API Google Drive sont répertoriés sur la page Paramètres système.

Articles associés

• Corriger les erreurs
• Résoudre les problèmes d'authentification et d'autorisation
• Amélioration des performances