Renvoyer des champs spécifiques

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

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. Le masquage de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter un temps de traitement inutile.

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

Une fois qu'un serveur a traité une requête valide incluant le paramètre fields, il renvoie un 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 un code d'état HTTP 400 Bad Request, ainsi qu'un message d'erreur indiquant ce qui n'allait pas avec la sélection des champs. Par exemple, files.list(fields='files(id,capabilities,canAddChildren)') génère l'erreur "Sélection de champ non valide canAddChildren". Le paramètre de champ approprié 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 connaître les champs que vous pouvez renvoyer pour un fichier, consultez la documentation de 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 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'.

  • Incluez 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.

  • 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 de l'espace réservé 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
  }
}

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 à 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() correspond à 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() correspond à 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).

Afficher un exemple

Requête

Dans cet exemple, nous fournissons le paramètre de chemin d'accès à 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"
    }
  ]
}