Zarządzanie metadanymi plików

W tym dokumencie znajdziesz ważne informacje dotyczące nazywania plików i pracy z metadanymi, takimi jak tekst indeksowany i miniatury. Aby wstawiać i pobierać pliki, zapoznaj się z files.

Określanie nazw plików i rozszerzeń

Aplikacje powinny określać rozszerzenie pliku we właściwości title podczas wstawiania plików za pomocą interfejsu Google Drive API. Na przykład operacja wstawienia pliku JPEG powinna określać w metadanych coś w rodzaju "name": "cat.jpg".

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

Zapisywanie tekstu, który można indeksować

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 aplikacja zapisuje inne typy plików (np. rysunki, filmy i skróty), możesz zwiększyć ich wykrywalność, podając tekst indeksowany w polu contentHints.indexableText pliku.

Tekst, który można indeksować, jest indeksowany jako HTML. Jeśli zapiszesz ciąg tekstowy podlegający indeksowaniu <section attribute="value1">Here's some text</section>, zostanie zindeksowany tekst „Here's some text”, ale nie „value1”. Z tego powodu zapisywanie plików XML jako indeksowalnego tekstu nie jest tak przydatne jak zapisywanie plików HTML.

Podczas określania wartości indexableText pamiętaj też o tych kwestiach:

  • Limit rozmiaru dla contentHints.indexableText wynosi 128 KB.
  • Wybierz kluczowe terminy i pojęcia, które według Ciebie użytkownik może wpisać w wyszukiwarce.
  • Nie próbuj sortować tekstu według ważności, ponieważ indeksator robi to za Ciebie skutecznie.
  • Aplikacja powinna aktualizować tekst podlegający indeksowaniu przy każdym zapisaniu.
  • Upewnij się, że tekst jest związany z zawartością lub metadanymi pliku.

Ten ostatni punkt może wydawać się oczywisty, ale jest ważny. Nie warto dodawać popularnych wyszukiwanych haseł, aby wymusić wyświetlanie pliku w wynikach wyszukiwania. Może to frustrować użytkowników, a nawet skłonić 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żytkownikowi lepiej identyfikować pliki na Dysku.

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

Więcej szczegółów:

  • Ustaw pole contentHints.thumbnail.image na adres URL i nazwę pliku bezpiecznego obrazu zakodowanego w base64 (patrz sekcja 5 dokumentu 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 i zignoruje 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:

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

Więcej informacji znajdziesz w files.

Pobieranie miniatur

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

Zwracanie konkretnej miniatury

Poniższy przykładowy kod pokazuje żądanie metody files.get z wieloma polami jako parametrem zapytania, które zwraca metadane thumbnailLink określonego pliku. Więcej informacji znajdziesz w artykule Zwracanie określonych pól w przypadku pliku.

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

Zastąp symbol FILE_ID symbolem fileId pliku, który chcesz znaleźć.

Jeśli jest dostępna, w odpowiedzi na żądanie zwracany jest krótkotrwały adres URL miniatury pliku. Zwykle link jest ważny przez kilka godzin. Pole jest wypełniane tylko wtedy, gdy aplikacja wysyłająca żądanie ma dostęp do zawartości pliku. Jeśli plik nie jest udostępniony publicznie, adres URL zwrócony w thumbnailLink musi zostać pobrany za pomocą żądania z użyciem danych logowania.

Zwracanie listy miniatur

Poniższy przykładowy kod pokazuje żądanie metody files.list z wieloma polami jako parametrem zapytania, które zwraca metadane thumbnailLink dla 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 poniższy przykładowy kod pokazuje, jak ograniczyć listę do plików Arkuszy Google. Więcej informacji o typach MIME znajdziesz w artykule Obsługiwane typy 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)