Guia de comparação da API Drive v2 e v3

A versão mais recente da API Google Drive é a v3. O desempenho na v3 é melhor porque as pesquisas só retornam um subconjunto de campos. Use a versão atual, a menos que você precise da coleção v2. Se você estiver usando a v2, considere migrar para a v3. Para migrar, consulte Migrar para a API Drive v3. Para uma lista completa de diferenças entre as versões, consulte a referência de comparação da API Drive v2 e v3.

Se você quiser continuar usando a v2, consulte a alteração do Guia da API Drive v2 para saber como algumas instruções nos guias da v3 precisam ser alteradas para os desenvolvedores da v2.

Para saber mais sobre as melhorias da API Drive v3, assista o vídeo abaixo com engenheiros do Google falando sobre o novo design da API.

Melhorias na V3

Para otimizar o desempenho e reduzir a complexidade do comportamento da API, a v3 oferece estas melhorias em relação à versão anterior da API:

  • As pesquisas de arquivos e drives compartilhados não retornam recursos completos por padrão. Apenas um subconjunto de campos usados com frequência é retornado. Para mais detalhes sobre fields, consulte o método files.list e o método drives.list.
  • Quase todos os métodos que retornam uma resposta agora exigem o parâmetro fields. Para conferir uma lista de todos os métodos que exigem fields, consulte a referência da API Drive.
  • Os recursos com recursos duplicados foram removidos. Alguns exemplos:
    • O método files.list tem a mesma funcionalidade que as coleções Children e Parents. Por isso, elas foram removidas da v3.
    • Os métodos Realtime.* foram removidos.
  • Os dados do app não são retornados por padrão nas pesquisas. Na v2, é possível definir o escopo drive.appdata, que retorna dados do aplicativo do método files.list e do método changes.list, mas diminui a performance. Na v3, você define o escopo drive.appdata e também define o parâmetro de consulta spaces=appDataFolder para solicitar dados do aplicativo.
  • Todas as operações de atualização usam PATCH em vez de PUT.
  • Para exportar documentos do Google, use o método files.export.
  • O comportamento do método changes.list é diferente. Em vez de mudar IDs, use tokens de página opacos. Para consultar a coleção de mudanças, primeiro chame o método changes.getStartPageToken para o valor inicial. Para consultas subsequentes, o método changes.list retorna o valor newStartPageToken.
  • Os métodos de atualização agora rejeitam solicitações que especificam campos não graváveis.
  • Os campos exportFormats e importFormats da v2 no recurso about são listas de formatos de importação ou exportação permitidos. Na v3, eles são mapas de tipo MIME de possíveis destinos para todas as importações ou exportações com suporte.
  • Os aliases appdata e appfolder da v2 agora são appDataFolder na v3.
  • O recurso properties foi removido da v3. O recurso files tem o campo properties que contém pares de chave-valor verdadeiros. O campo properties contém propriedades públicas, e o campo appProperties contém propriedades privadas. Portanto, o campo de visibilidade não é necessário.
  • O campo modifiedTime no recurso files é atualizado na última vez que alguém modificou o arquivo. Na v2, o campo modifiedDate só era mutável na atualização se você definisse o campo setModifiedDate.
  • O campo viewedByMeTime no recurso files não é atualizado automaticamente.
  • Para importar formatos do Documentos Google, defina o mimeType de destino apropriado no corpo do recurso. Na v2, você define ?convert=true.
  • As operações de importação retornam um erro 400 se o formato não for compatível.
  • Os leitores e comentaristas não podem acessar as permissões.
  • O alias me para permissões foi removido.
  • Algumas funcionalidades estavam disponíveis como parte do recurso de solicitação, mas estão disponíveis como um parâmetro de solicitação. Exemplo:
    • Na v2, é possível usar children.delete para remover um arquivo filho de uma pasta mãe.
    • Na v3, você usa files.update na criança com ?removeParents=parent_id no URL.

Outras diferenças

Os nomes de campos e parâmetros são diferentes na v3. Veja alguns exemplos:

  • A propriedade name substitui title no recurso files.
  • Time é o sufixo de todos os campos de data e hora, em vez de Date.
  • As operações de lista não usam o campo items para conter o conjunto de resultados. O tipo de recurso fornece um campo para os resultados, como files ou changes.