Zarządzanie metadanymi plików

W tym dokumencie znajdziesz ważne informacje na temat nadawania nazw plikom i pracy z metadanymi takimi jak tekst z możliwością indeksowania i miniatury. Aby wstawić lub pobrać pliki, zapoznaj się z zasobem files.

Podaj nazwy i rozszerzenia plików

Podczas wstawiania plików przy użyciu interfejsu Google Drive API aplikacje powinny określać rozszerzenie pliku we właściwości title. Na przykład operacja wstawiania pliku JPEG powinna określać w metadanych coś takiego jak "name": "cat.jpg".

Kolejne odpowiedzi GET mogą zawierać właściwość fileExtension tylko do odczytu wypełnioną rozszerzeniem pierwotnie określonym we właściwości name. Gdy użytkownik Dysku Google prosi o pobranie pliku lub gdy jest on pobierany za pomocą klienta synchronizacji, Dysk na jej podstawie tworzy pełną nazwę pliku (z rozszerzeniem). Jeśli brakuje rozszerzenia, Dysk próbuje określić rozszerzenie na podstawie typu MIME pliku.

Zapisz tekst, który można zindeksować

Dysk automatycznie indeksuje dokumenty na potrzeby wyszukiwania, gdy rozpoznaje typ pliku, w tym dokumenty tekstowe, pliki PDF, obrazy z tekstem i inne popularne typy. Jeśli Twoja aplikacja zapisuje inne typy plików (np. rysunki, filmy i skróty), możesz poprawić wykrywalność, podając tekst z możliwością indeksowania w polu contentHints.indexableText pliku.

Tekst, który można zindeksować, jest indeksowany w formacie HTML. Jeśli zapiszesz możliwy do zindeksowania ciąg tekstowy <section attribute="value1">Here's some text</section>, ciąg „Oto tekst”, ale ciąg „wartość1” już nie. Z tego powodu zapisanie pliku XML jako tekstu możliwego do indeksowania nie jest tak przydatne jak zapisywanie kodu HTML.

Określając indexableText, pamiętaj też o tych kwestiach:

  • Maksymalny rozmiar pliku contentHints.indexableText to 128 KB.
  • Uwzględnij kluczowe terminy i koncepcje, których oczekujesz od użytkownika.
  • Nie próbuj sortować tekstu według ważności, ponieważ indekser zrobi to za Ciebie skutecznie.
  • Aplikacja powinna aktualizować tekst dostępny do indeksowania przy każdym zapisie.
  • Upewnij się, że tekst jest powiązany z zawartością lub metadanymi pliku.

Ostatnia uwaga może wydawać się oczywista, ale jest bardzo ważna. Nie dodawaj często wyszukiwanych haseł, by wymusić wyświetlanie pliku w wynikach wyszukiwania. Może to frustrować użytkowników, a nawet zmotywować ich do usunięcia pliku.

Przesyłanie miniatur

Dysk automatycznie generuje miniatury wielu popularnych typów plików, takich jak Dokumenty, Arkusze i Prezentacje Google. Miniatury pomagają użytkownikom lepiej rozpoznawać pliki na Dysku.

W przypadku plików, dla których Dysk nie może wygenerować standardowej miniatury, możesz udostępnić obraz miniatury wygenerowany przez aplikację. Podczas tworzenia lub aktualizacji pliku prześlij miniaturę, ustawiając pole contentHints.thumbnail dla zasobu files.

Oto najważniejsze kwestie:

  • W polu contentHints.thumbnail.image wpisz adres URL i nazwę pliku obrazu zakodowanego w formacie base64 (zobacz sekcję 5 w sekcji RFC 4648).
  • W polu contentHints.thumbnail.mimeType ustaw odpowiedni typ MIME miniatury.

Jeśli Dysk może wygenerować miniaturę z pliku, użyje wygenerowanej automatycznie miniatury i ignoruje wszystkie przesłane przez Ciebie miniatury. Jeśli nie może wygenerować miniatury, użyje tej, którą podasz.

Miniatury powinny być zgodne z tymi zasadami:

  • Materiały można przesyłać w formacie PNG, GIF lub JPG.
  • Zalecana szerokość to 1600 pikseli.
  • Minimalna szerokość to 220 pikseli.
  • Maksymalny rozmiar pliku to 2 MB.
  • Aplikacja powinna aktualizować je przy każdym zapisywaniu.

Więcej informacji znajdziesz w materiałach files.

Pobieranie miniatur

Możesz pobierać metadane, w tym miniatury, plików z Dysku. Informacje o miniaturze znajdują się w polu thumbnailLink zasobu files.

Zwracanie konkretnej miniatury

Poniższy przykładowy kod przedstawia żądanie metody files.get z wieloma polami jako parametrem zapytania zwracającym metadane thumbnailLink dla konkretnego pliku. Więcej informacji znajdziesz w sekcji Zwracanie określonych pól w pliku.

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

Zastąp FILE_ID wartością fileId pliku, który chcesz znaleźć.

Jeśli to możliwe, żądanie zwraca krótkotrwały adres URL do miniatury pliku. Zwykle link działa przez kilka godzin. Pole jest wypełniane tylko wtedy, gdy aplikacja żądająca dostępu ma dostęp do zawartości pliku. Jeśli plik nie jest udostępniony publicznie, adres URL zwrócony w funkcji thumbnailLink trzeba pobrać za pomocą żądania danych uwierzytelniających.

Zwraca listę miniatur

Poniższy przykładowy kod przedstawia żądanie metody files.list z wieloma polami jako parametr zapytania zwracający metadane thumbnailLink listy plików. Więcej informacji znajdziesz w artykule Wyszukiwanie plików i folderów.

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

Aby ograniczyć wyniki wyszukiwania do określonego typu pliku, zastosuj ciąg zapytania, aby ustawić typ MIME. Na przykład ten przykładowy kod pokazuje, jak ograniczyć listę do plików Arkuszy Google. Więcej informacji o typach MIME znajdziesz w artykule na temat obsługiwanych typów MIME w Google Workspace i na Dysku Google.

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