Gerenciar metadados de arquivos

Este documento aborda considerações importantes para nomear arquivos e trabalhar com metadados, como texto indexável e miniaturas. Para inserir e recuperar arquivos, consulte o recurso files.

Especificar nomes e extensões de arquivos

Os aplicativos precisam especificar uma extensão de arquivo na propriedade do título ao inserir arquivos com a API Google Drive. Por exemplo, uma operação para inserir um arquivo JPEG precisa especificar algo como "name": "cat.jpg" nos metadados.

As respostas GET subsequentes podem incluir a propriedade fileExtension somente leitura preenchida com a extensão especificada originalmente na propriedade name. Quando um usuário do Google Drive solicita o download de um arquivo ou quando o arquivo é feito pelo cliente de sincronização, o Drive cria um nome de arquivo completo (com extensão) com base no título. Quando a extensão não existir, o Drive tentará determinar a extensão com base no tipo MIME do arquivo.

Salvar texto indexável

Observação: a partir de 31 de outubro de 2022, o texto indexável poderá ser mostrado nos snippets de resultados e afetará os resultados da pesquisa em mais lugares, incluindo a Pesquisa na Nuvem e a sobreposição de pesquisa no Drive e no Gmail.

O Drive indexa automaticamente documentos para pesquisa quando reconhece o tipo de arquivo, incluindo documentos de texto, PDFs, imagens com texto e outros tipos comuns. Se o app salvar outros tipos de arquivos (como desenhos, vídeos e atalhos), você pode melhorar a capacidade de descoberta fornecendo texto indexável no campo contentHints.indexableText do arquivo.

O texto indexável é indexado como HTML. Se você salvar a string de texto indexável <section attribute="value1">Here's some text</section>, "Aqui está um pouco do texto" será indexado, mas "value1" não. Por isso, salvar XML como texto indexável não é tão útil quanto salvar HTML.

Ao especificar indexableText, lembre-se também:

• O limite de tamanho do contentHints.indexableText é de 128 KB.
• Capture os principais termos e conceitos que você espera que um usuário pesquise.
• Não tente classificar o texto por ordem de importância, porque o indexador faz isso de maneira eficiente para você.
• Seu aplicativo precisa atualizar o texto indexável a cada salvamento.
• Verifique se o texto está relacionado ao conteúdo ou aos metadados do arquivo.

Este último ponto pode parecer óbvio, mas é importante. Não é uma boa ideia adicionar termos pesquisados com frequência para forçar um arquivo a aparecer nos resultados da pesquisa. Isso pode frustrar os usuários e até mesmo motivá-los a excluir o arquivo.

Fazer upload de miniaturas

O Drive gera automaticamente miniaturas de muitos tipos de arquivos comuns, como Documentos, Planilhas e Apresentações Google. As miniaturas ajudam o usuário a identificar melhor os arquivos do Drive.

Para tipos de arquivos que o Drive não consegue gerar uma miniatura padrão, forneça uma imagem de miniatura gerada pelo seu app. Durante a criação ou atualização de arquivos, faça upload de uma miniatura definindo o campo contentHints.thumbnail no recurso files.

Especificamente:

• Defina o campo contentHints.thumbnail.image como a imagem codificada em Base64 segura para URL e nome de arquivo (consulte a seção 5 do RFC 4648).
• Defina o campo contentHints.thumbnail.mimeType como o tipo MIME adequado para a miniatura.

Se o Drive puder gerar uma miniatura do arquivo, ele usará a gerada automaticamente e ignorará qualquer miniatura enviada. Se não for possível gerar uma miniatura, ela vai usar a que você fornecer.

As miniaturas precisam seguir estas regras:

• Podem ser enviados nos formatos PNG, GIF ou JPG.
• A largura recomendada é de 1.600 pixels.
• A largura mínima é de 220 pixels.
• O tamanho máximo do arquivo é de 2 MB.
• Eles precisam ser atualizados pelo seu aplicativo a cada salvamento.

Importante: as miniaturas são invalidadas sempre que o conteúdo do arquivo é modificado. Ao fornecer miniaturas, é importante enviar novas miniaturas sempre que o conteúdo for modificado. As mudanças nos metadados não invalidam as miniaturas.

Para mais informações, consulte o recurso files.

Extrair miniaturas

É possível recuperar metadados, incluindo miniaturas, de arquivos do Drive. As informações da miniatura estão armazenadas no campo thumbnailLink do recurso files.

Exibir uma miniatura específica

O exemplo de código abaixo mostra uma solicitação de método files.get com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink de um arquivo específico. Para mais informações, consulte Retornar campos específicos de um arquivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Substitua FILE_ID pelo fileId do arquivo que você quer encontrar.

Se disponível, a solicitação vai retornar um URL de curta duração para a miniatura do arquivo. Normalmente, o link dura várias horas. O campo só é preenchido quando o app solicitante pode acessar o conteúdo do arquivo. Se o arquivo não for compartilhado publicamente, o URL retornado em thumbnailLink precisará ser buscado usando uma solicitação com credenciais.

Retornar uma lista de miniaturas

O exemplo de código a seguir mostra uma solicitação de método files.list com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink de uma lista de arquivos. Para mais informações, consulte Pesquisar arquivos e pastas.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Para restringir os resultados da pesquisa a um tipo de arquivo específico, aplique uma string de consulta para definir o tipo MIME. Por exemplo, o exemplo de código a seguir mostra como limitar a lista a arquivos do Planilhas Google. Para mais informações sobre os tipos MIME, consulte Tipos MIME compatíveis com o Google Workspace e o Google Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)