Guide comparatif des API Drive v2 et v3

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 v2 collection. 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 documentation de référence Comparaison des API Drive v2 et v3.

Si vous souhaitez continuer à utiliser la version 2, consultez le Guide de l'amendement de l'API Drive v2 pour découvrir comment certaines instructions des guides de la version 3 doivent être modifiées 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 la version 3

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 :

  • Les recherches de fichiers et de Drive partagés ne renvoient pas de ressources complètes par défaut. Seul un sous-ensemble de champs couramment utilisés est renvoyé. Pour en savoir plus sur fields, consultez la files.list méthode et la drives.list méthode.
  • 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 qui ont des fonctionnalités en double ont été supprimées. Voici quelques exemples :
    • La méthode files.list remplit la même fonction 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 drive.appdata champ d'application, qui renvoie les données d'application à partir de la files.list méthode et de la changes.list méthode, mais cela ralentit les performances. Dans la version 3, vous définissez le champ d'application drive.appdata, ainsi que le paramètre de requête spaces=appDataFolder pour demander les données d'application.
  • Toutes les opérations de mise à jour utilisent PATCH au lieu de PUT.
  • Pour exporter des documents Google, utilisez la files.export méthode.
  • 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 changes.getStartPageToken méthode pour obtenir la valeur initiale. Pour les requêtes suivantes, la méthode changes.list renvoie la valeur newStartPageToken.
  • Les méthodes de mise à jour refusent désormais les requêtes qui spécifient des champs non accessibles en écriture.
  • Les champs exportFormats et importFormats de la version 2 dans la about ressource sont des listes de formats d'importation ou d'exportation autorisés. Dans la version 3, il s'agit de mappages de types MIME des cibles possibles pour 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 properties champ 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 dernière fois que quelqu'un a modifié le fichier. Dans la version 2, le champ modifiedDate n'était mutable lors de la mise à jour que si vous définissiez le champ setModifiedDate.
  • Le champ viewedByMeTime de la ressource files n'est pas mis à jour automatiquement.
  • Pour importer des formats Google Docs, 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 compatible.
  • Les lecteurs et les commentateurs ne peuvent pas afficher 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 (tel que files ou changes).