Guide comparatif des API Drive v2 et v3
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
La dernière version de l'API Google Drive est la version 3. Les performances de la version 3 sont meilleures, car les recherches ne renvoient qu'un sous-ensemble de champs. Utilisez la version actuelle, sauf si vous avez besoin de la collection v2. Si vous utilisez la version 2, envisagez de migrer vers la version 3. Pour migrer, consultez Migrer vers l'API Drive v3. Pour obtenir la liste complète des différences entre les versions, consultez la comparaison des API Drive v2 et v3.
Si vous souhaitez continuer à utiliser la version 2, consultez l'avenant au Guide de l'API Drive v2 pour savoir comment modifier certaines instructions des guides de la version 3 pour les développeurs de la version 2.
Pour en savoir plus sur les améliorations apportées à l'API Drive v3, vous pouvez regarder la vidéo suivante dans laquelle des ingénieurs Google présentent la nouvelle conception de l'API.
Améliorations de V3
Pour optimiser les performances et réduire la complexité du comportement de l'API, la version 3 apporte les améliorations suivantes par rapport à la version précédente de l'API :
- Par défaut, les recherches de fichiers et de Drive partagés ne renvoient pas de ressources complètes, mais uniquement un sous-ensemble de champs couramment utilisés. Pour en savoir plus sur
fields, consultez les méthodes files.list et drives.list.
- Presque toutes les méthodes qui renvoient une réponse nécessitent désormais le paramètre
fields. Pour obtenir la liste de toutes les méthodes nécessitant fields, consultez la
documentation de référence de l'API Drive.
- Les ressources dont les capacités étaient en double ont été supprimées. Voici quelques exemples :
- La méthode
files.list offre les mêmes fonctionnalités que les collections Children et Parents. Elles sont donc supprimées de la version 3.
- Les méthodes
Realtime.* ont été supprimées.
- Les données d'application ne sont pas renvoyées par défaut dans les recherches. Dans la version 2, vous pouvez définir le champ d'application
drive.appdata. Il renvoie les données d'application à partir de la méthode files.list et de la méthode changes.list, mais cela ralentit les performances. Dans la version 3, vous définissez le champ d'application drive.appdata et le paramètre de requête spaces=appDataFolder pour demander des données d'application.
- Toutes les opérations de mise à jour utilisent PATCH au lieu de PUT.
- Pour exporter des documents Google Docs, utilisez la méthode
files.export.
- Le comportement de la méthode
changes.list est différent. Au lieu d'utiliser des ID de modification, utilisez des jetons de page opaques. Pour interroger la collection de modifications, appelez d'abord la méthode changes.getStartPageToken pour la valeur initiale. Pour les requêtes suivantes, la méthode changes.list renvoie la valeur newStartPageToken.
- Les méthodes de mise à jour rejettent désormais les requêtes qui spécifient des champs non modifiables.
- Les champs
exportFormats et importFormats de la ressource about sont des listes de formats d'importation ou d'exportation autorisés. Dans la version 3, il s'agit de mappages de type MIME des cibles possibles vers toutes les importations ou exportations compatibles.
- Les alias
appdata et appfolder de la version 2 sont désormais appDataFolder dans la version 3.
- La ressource
properties est supprimée de la version 3. La ressource files comporte le champ properties qui contient de véritables paires clé/valeur. Le champ properties contient des propriétés publiques et le champ appProperties contient des propriétés privées. Le champ de visibilité n'est donc pas nécessaire.
- Le champ
modifiedTime de la ressource files indique la date et l'heure de la dernière modification du fichier. Dans la version 2, le champ modifiedDate n'était modifiable lors de la mise à jour que si vous définissiez le champ setModifiedDate.
- Le champ
viewedByMeTime de la ressource files ne se met pas à jour automatiquement.
- Pour importer des formats Google Docs, vous définissez le
mimeType cible approprié dans le corps de la ressource. Dans la version 2, vous définissez ?convert=true.
- Les opérations d'importation renvoient une erreur 400 si le format n'est pas accepté.
- Les lecteurs et les commentateurs ne peuvent pas consulter les autorisations.
- L'alias
me pour les autorisations est supprimé.
- Certaines fonctionnalités étaient disponibles dans la ressource de requête, mais sont désormais disponibles en tant que paramètre de requête. Exemple :
- Dans la version 2, vous pouvez utiliser
children.delete pour supprimer un fichier enfant d'un dossier parent.
- Dans la version 3, vous utilisez
files.update sur l'enfant avec?removeParents=parent_id dans l'URL.
Autres différences
Les noms des champs et des paramètres sont différents dans la version 3. Voici quelques exemples :
- La propriété
name remplace title dans la ressource files.
Time est le suffixe de tous les champs de date et d'heure au lieu de Date.- Les opérations de liste n'utilisent pas le champ
items pour contenir l'ensemble de résultats. Le type de ressource fournit un champ pour les résultats (par exemple, files ou changes).
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/29 (UTC).
[null,null,["Dernière mise à jour le 2025/08/29 (UTC)."],[],[],null,["# Drive API v2 and v3 comparison guide\n\nThe latest Google Drive API version is v3. The performance in v3 is better because\nsearches only return a subset of fields. Use the current version unless you need\nthe [v2](/workspace/drive/api/v2/reference) collection. If you're using v2, consider\nmigrating to v3. To migrate, see [Migrate to Drive API v3](/workspace/drive/api/guides/migrate-to-v3). For a complete list of version differences, see\nthe [Drive API v2 and v3 comparison\nreference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nIf you want to continue to use v2, see the [Guide to Drive API v2](/workspace/drive/api/guides/v2-guide) amendment to learn how some instructions in the v3\nguides must be amended for v2 developers.\n\nTo learn more about Drive API v3 improvements, you can watch the\nfollowing video by Google engineers discussing the new API design. \n\nV3 improvements\n---------------\n\nTo optimize performance and reduce API behavior complexity, v3 provides these\nimprovements over the previous API version:\n\n- Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details on `fields`, see the [`files.list`](/workspace/drive/api/v3/reference/files/list) method and the [`drives.list`](/workspace/drive/api/v3/reference/drives/list) method.\n- Almost all methods that return a response now require the `fields` parameter. For a list of all methods requiring `fields`, see the [Drive API reference](/workspace/drive/api/v3/reference).\n- Resources that have duplicate capabilities were removed. Some examples:\n - The `files.list` method accomplishes the same functionality as the `Children` and `Parents` collections, so they're removed from v3.\n - The `Realtime.*` methods have been removed.\n- App Data isn't returned by default in searches. In v2, you can set the `drive.appdata` scope, and it returns application data from the `files.list` method and the [`changes.list`](/workspace/drive/api/v2/reference/changes/list) method, but it slows performance. In v3, you set the `drive.appdata` scope, and also set the query parameter `spaces=appDataFolder` to request application data.\n- All update operations use PATCH instead of PUT.\n- To export Google Documents, use the [`files.export`](/workspace/drive/api/v2/reference/files/export) method.\n- The `changes.list` method behavior is different. Instead of change IDs, use opaque page tokens. To poll the change collection, first call the [`changes.getStartPageToken`](/workspace/drive/api/v2/reference/changes/getStartPageToken) method for the initial value. For subsequent queries, the `changes.list` method returns the `newStartPageToken` value.\n- Update methods now reject requests that specify non-writable fields.\n- The v2 `exportFormats` and `importFormats` fields in the [`about`](/workspace/drive/api/reference/rest/v3/about) resource are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.\n- The v2 `appdata` and `appfolder` aliases are now `appDataFolder` in v3.\n- The `properties` resource is removed from v3. The [`files`](/workspace/drive/api/v3/reference/files) resource has the `properties` field that contains true key-value pairs. The `properties` field contains public properties, and the `appProperties` field contains private properties, so the visibility field isn't needed.\n- The `modifiedTime` field in the `files` resource updates the last time anyone modified the file. In v2, the `modifiedDate` field was only mutable on update if you set the `setModifiedDate` field.\n- The `viewedByMeTime` field in the `files` resource doesn't automatically update.\n- To import Google Docs formats, you set the appropriate target `mimeType` in the resource body. In v2, you set `?convert=true`.\n- Import operations return a 400 error if the format isn't supported.\n- Readers and commenters can't view permissions.\n- The `me` alias for permissions is removed.\n- Some functionality was available as part of the request resource but is instead available as a request parameter. For example:\n - In v2, you can use `children.delete` to remove a child file from a parent folder.\n - In v3, you use`files.update` on the child with `?removeParents=parent_id` in the URL.\n\nOther differences\n-----------------\n\nFields and parameter names are different in v3. Some examples include:\n\n- The `name` property replaces `title` in the `files` resource.\n- `Time` is the suffix for all date and time fields instead of `Date`.\n- List operations don't use the `items` field to contain the result set. The resource type provides a field for the results (such as `files` or `changes`)."]]
