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 estão no campo thumbnailLink
da
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 estiver 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)