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 les éléments id
, name
et mimeType
de la ressource files
. La méthode permissions.get
renvoie un autre ensemble de champs par défaut pour une ressource permissions
.
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 de requête "fields" comporte une erreur ou s'il 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 avec la sélection des champs. Par exemple, files.list(fields='files(id,capabilities,canAddChildren)')
génère l'erreur "Invalid field selection canAddChildren". Le paramètre de requête "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 savoir quels champs vous pouvez renvoyer pour un fichier, consultez la documentation de la ressource files
.
Règles de format des paramètres de champ
Le format de la valeur du paramètre de requête "fields" repose globalement sur la syntaxe XPath. Voici les règles de mise en forme du paramètre fields
. Toutes ces règles utilisent des exemples liés à la méthode files.get
.
Utilisez une liste d'éléments séparés par une virgule pour sélectionner plusieurs champs, par exemple
'name, mimeType'
.Utilisez
a/b
pour sélectionner le champb
imbriqué dans le champa
, 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 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 de ce caractère générique peut avoir un impact négatif sur les performances de la requête.
Afficher un exemple
Requête
Dans cet exemple, nous fournissons le paramètre de chemin d'accès de l'ID de fichier et plusieurs champs en tant que paramètre de requête dans la requête. La réponse renvoie les valeurs des champs pour l'ID de fichier.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
Response (Réponse)
{ "name": "File1", "starred": false, "shared": true } }
Extraire 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 à extraire.
Par exemple, pour récupérer le champ role
(ressource imbriquée) de la ressource permissions
, utilisez l'une des options suivantes:
permissions.get
avecfields=role
oufields=*
.files.get
avecfields=permissions(role)
oufields=permissions/role
.files.get
parfields=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, séparez-les par une virgule. Par exemple, files.list
avec fields=files(id,name,createdTime,modifiedTime,size)
.
Afficher un exemple
Requête
Dans cet exemple, nous fournissons le paramètre de chemin de l'ID de fichier et plusieurs champs, y compris certains champs de la ressource d'autorisations imbriquées, en tant que paramètre de requête dans la requête. La réponse renvoie les valeurs des champs pour l'ID de fichier.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)
Response (Réponse)
{ "name": "File1", "starred": false, "shared": true, "permissions": [ { "kind": "drive#permission", "type": "user", "role": "owner" } ] }