Guía de comparación de la API de Drive v2 y v3

La versión más reciente de la API de Google Drive es la 3. El rendimiento en la versión 3 es mejor porque las búsquedas solo muestran un subconjunto de campos. Usa la versión actual, a menos que necesites la colección v2. Si usas la versión 2, considera migrar a la versión 3. Para ello, consulta Migra a la API de Drive v3. Para obtener una lista completa de las diferencias entre las versiones, consulta la referencia de comparación de las versiones 2 y 3 de la API de Drive.

Si deseas seguir usando la versión 2, consulta la enmienda de la Guía para la versión 2 de la API de Drive para conocer cómo se deben modificar algunas instrucciones de las guías de la versión 3 para desarrolladores de la versión 2.

Si quieres obtener más información sobre las mejoras de la API de Drive v3, puedes mirar el siguiente video de ingenieros de Google en el que se analiza el nuevo diseño de la API.

Mejoras de V3

Para optimizar el rendimiento y reducir la complejidad del comportamiento de la API, v3 proporciona estas mejoras con respecto a la versión anterior de la API:

  • Las búsquedas de archivos y unidades compartidas no muestran recursos completos de forma predeterminada, solo se muestra un subconjunto de campos de uso general. Para obtener más detalles sobre fields, consulta los métodos files.list y drives.list.
  • Casi todos los métodos que muestran una respuesta ahora requieren el parámetro fields. Para obtener una lista de todos los métodos que requieren fields, consulta la referencia de la API de Drive.
  • Se quitaron los recursos con capacidades duplicadas. Estos son algunos ejemplos:
    • El método files.list logra la misma funcionalidad que las colecciones Children y Parents, por lo que se quitan de la versión 3.
    • Se quitaron los métodos Realtime.*.
  • Los datos de apps no se muestran de forma predeterminada en las búsquedas. En la versión 2, puedes configurar el alcance drive.appdata, que muestra datos de aplicación de los métodos files.list y changes.list, pero ralentiza el rendimiento. En la versión 3, configuras el alcance drive.appdata y también el parámetro de consulta spaces=appDataFolder para solicitar datos de la aplicación.
  • Todas las operaciones de actualización usan PATCH en lugar de PUT.
  • Para exportar documentos de Google, usa el método files.export.
  • El comportamiento del método changes.list es diferente. En lugar de IDs de cambio, usa tokens de página opacos. Si quieres sondear la recopilación de cambios, primero llama al método changes.getStartPageToken para obtener el valor inicial. Para consultas posteriores, el método changes.list muestra el valor newStartPageToken.
  • Los métodos de actualización ahora rechazan las solicitudes que especifican campos que no admiten escritura.
  • Los campos exportFormats y importFormats v2 del recurso about son listas de formatos de importación o exportación permitidos. En la v3, son mapas de tipos MIME de destinos posibles para todas las importaciones o exportaciones admitidas.
  • Los alias appdata y appfolder de la v2 ahora son appDataFolder en la v3.
  • Se quitó el recurso properties de la v3. El recurso files tiene el campo properties que contiene pares clave-valor verdaderos. El campo properties contiene propiedades públicas, y el campo appProperties contiene propiedades privadas, por lo que no es necesario el campo de visibilidad.
  • El campo modifiedTime en el recurso files actualiza la última vez que se modificó el archivo. En la versión 2, el campo modifiedDate solo era mutable durante la actualización si establecías el campo setModifiedDate.
  • El campo viewedByMeTime del recurso files no se actualiza automáticamente.
  • Para importar formatos de Documentos de Google, debes establecer el mimeType de destino adecuado en el cuerpo del recurso. En la versión 2, configuras ?convert=true.
  • Las operaciones de importación muestran un error 400 si el formato no es compatible.
  • Los lectores y comentaristas no pueden ver los permisos.
  • Se quitó el alias me para los permisos.
  • Algunas funciones estaban disponibles como parte del recurso de solicitud, pero están disponibles como un parámetro de solicitud. Por ejemplo:
    • En la versión 2, puedes usar children.delete para quitar un archivo secundario de una carpeta superior.
    • En la versión 3, se usa files.update en el elemento secundario con ?removeParents=parent_id en la URL.

Otras diferencias

Los campos y los nombres de los parámetros son diferentes en la v3. Estos son algunos ejemplos:

  • La propiedad name reemplaza a title en el recurso files.
  • Time es el sufijo de todos los campos de fecha y hora, en lugar de Date.
  • Las operaciones de lista no usan el campo items para contener el conjunto de resultados. El tipo de recurso proporciona un campo para los resultados (como files o changes).