Afficher des champs spécifiques pour un fichier

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

Par défaut, le serveur renvoie un ensemble de champs spécifiques à la ressource interrogée. Par exemple, la méthode files.get peut ne renvoyer que id, name et mimeType pour la ressource files. La méthode permissions.get renvoie un ensemble différent de champs par défaut pour une ressource permissions.

Une fois qu'un serveur a traité une requête valide incluant le paramètre de requête fields, il renvoie le code d'état HTTP 200 OK ainsi que les données demandées. Si le paramètre de requête des champs comporte une erreur ou n'est pas valide pour une autre raison, le serveur renvoie un code d'état HTTP 400 Bad Request, ainsi qu'un message d'erreur indiquant le problème lié à la sélection des champs. Par exemple, files.list(fields='files(id,capabilities,canAddChildren)') génère une erreur de type "Sélection de champ non valide canAddChildren". Le paramètre de requête des champs 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 quels champs vous pouvez renvoyer pour un fichier, reportez-vous à la documentation sur la ressource files.

Règles de mise en forme des paramètres de champ

Le format de la valeur du paramètre de requête des champs est globalement basé sur la syntaxe XPath. Vous trouverez ci-dessous des règles de mise en forme pour le paramètre fields. Toutes ces règles utilisent des exemples liés à la méthode files.get.

• Utilisez une liste séparée par des virgules pour sélectionner plusieurs champs, par exemple 'name, mimeType'.

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

• Utilisez 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 afficher 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 de ce 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 quels champs de la ressource imbriquée doivent être extraits.

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

• permissions.get par fields=role ou fields=*.
• files.get par fields=permissions(role) ou fields=permissions/role.
• files.get par fields=permissions pour impliquer tous les champs de la ressource imbriquée.
• changes.list correspond à fields=changes(file(permissions(role))).

Pour récupérer plusieurs champs, utilisez une liste séparée par des virgules. 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"
    }
  ]
}