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 de arquivos e extensões

Os apps 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 especifique 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 Os usuários do Google Drive solicitam o download de um arquivo ou quando o download é feito. pelo cliente de sincronização, o Drive cria um nome de arquivo completo (com ) com base no título. Nos casos em que a extensão estiver ausente, O Drive tenta determinar a extensão com base no Tipo MIME.

Salvar texto indexável

O Drive indexa documentos automaticamente para pesquisa ao reconhece o tipo de arquivo, incluindo documentos de texto, PDFs, imagens com texto e e outros tipos comuns. Se o app salvar outros tipos de arquivo (como desenhos, vídeo 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> e "Aqui estão algumas texto" está indexado, mas "value1" não é. Por isso, salvar XML como 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 o usuário pesquise.
  • Não tente classificar o texto em ordem de importância, porque o indexador faz isso com eficiência 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 de pesquisa. Isso pode frustrar os usuários e pode até mesmo motivá-los a excluir o arquivo.

Enviar miniaturas

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

Para tipos de arquivo em que o Drive não consegue gerar uma miniatura padrão é possível fornecer uma imagem de miniatura gerada pelo seu aplicativo. Durante criação ou atualização de um arquivo, envie uma miniatura definindo o Campo contentHints.thumbnail no recurso files.

Especificamente:

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

Se o Drive puder gerar uma miniatura a partir do arquivo, ele usará o gerou automaticamente e ignora qualquer outro que você tenha enviado. Se não for possível para gerar uma miniatura, ele usa a que você forneceu.

As miniaturas precisam seguir estas regras:

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

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

Recuperar miniaturas

Você pode recuperar metadados, incluindo miniaturas, de arquivos do Drive. As informações da miniatura são hospedadas no campo thumbnailLink do files.

Exibir uma miniatura específica

O exemplo de código a seguir mostra solicitação do método files.get com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink para um arquivo específico. Para mais informações, consulte Retornar campos específicos para 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 retorna 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 precisa ser buscado usando uma solicitação credenciada.

Retornar uma lista de miniaturas

O exemplo de código a seguir mostra solicitação do método files.list com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink para 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 a defina o tipo MIME. Por exemplo, o exemplo de código a seguir mostra como limitar o aos arquivos do Planilhas Google. Para obter mais informações sobre tipos MIME, consulte MIME compatível com o Google Workspace e o Google Drive tipos.

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