Zarządzanie metadanymi plików

W tym artykule omawiamy ważne kwestie dotyczące nazewnictwa plików i pracy z metadanymi, takimi jak tekst i miniatury, które można indeksować. Aby wstawiać i pobierać pliki, zapoznaj się z zasobem files.

Określanie nazw i rozszerzeń plików

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

Kolejne odpowiedzi GET mogą zawierać tylko do odczytu właściwości fileExtension wypełnionej rozszerzeniem określonym pierwotnie we właściwości name. Gdy użytkownik Dysku Google poprosi o pobranie pliku lub gdy plik zostanie pobrany za pomocą klienta synchronizacji, Dysk utworzy pełną nazwę pliku (z rozszerzeniem) na podstawie tytułu. Jeśli brakuje rozszerzenia, Dysk próbuje je określić na podstawie typu MIME pliku.

Zapisz tekst możliwy do zindeksowania

Dysk automatycznie indeksuje dokumenty na potrzeby wyszukiwania, gdy rozpozna typ plików, w tym dokumenty tekstowe, pliki PDF, obrazy z tekstem i inne popularne typy plików. Jeśli Twoja aplikacja zapisuje inne typy plików (np. rysunki, filmy i skróty), możesz zwiększyć ich widoczność, podając tekst do zindeksowania w polu contentHints.indexableText pliku.

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

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

  • Limit rozmiaru dla contentHints.indexableText to 128 KB.
  • Uwzględnij kluczowe terminy i pojęcia, których użytkownik może szukać.
  • Nie próbuj sortować tekstu według ważności, ponieważ robot indeksujący robi to za Ciebie.
  • Aplikacja powinna aktualizować możliwy do indeksowania tekst przy każdym zapisie.
  • Upewnij się, że tekst jest powiązany z treścią lub metadanymi pliku.

Ten ostatni punkt może wydawać się oczywisty, ale jest ważny. Nie zalecamy dodawania często wyszukiwanych haseł, aby wymusić wyświetlanie pliku w wynikach wyszukiwania. Może to zirytować użytkowników i nawet skłonić ich do usunięcia pliku.

Prześlij miniatury

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 typów plików, dla których Dysk nie może wygenerować standardowej miniatury, możesz przesłać miniaturę wygenerowaną przez aplikację. Podczas tworzenia lub aktualizowania pliku prześlij miniaturę, ustawiając pole contentHints.thumbnail w zasobie files.

Oto najważniejsze kwestie:

  • W polu contentHints.thumbnail.image wpisz adres URL i nazwę pliku bezpiecznego obrazu zakodowanego w formacie base64 (patrz sekcja 5 dokumentu RFC 4648).
  • Ustaw pole contentHints.thumbnail.mimeType na odpowiedni typ MIME miniatury.

Jeśli Dysk może wygenerować miniaturę pliku, użyje automatycznie wygenerowanej miniatury i zignoruje 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:

  • mogą być przesyłane 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ć te wartości przy każdym zapisaniu.

Więcej informacji znajdziesz w dokumentacji files.

Pobierz miniatury

Możesz pobierać metadane, w tym miniatury, z plików na Dysku. Informacje o miniaturze są przechowywane w polu thumbnailLink zasobu files.

Zwracanie określonej miniatury

Poniższy przykładowy kod pokazuje żądanie metody files.get z wieloma polami jako parametrem zapytania, aby zwrócić metadane thumbnailLink określonego pliku. Więcej informacji znajdziesz w artykule Zwracanie określonych pól 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 chwilowy adres URL jako miniaturę pliku. Link jest zwykle ważny przez kilka godzin. Pole jest wypełniane tylko wtedy, gdy aplikacja wysyłająca żądanie może uzyskać dostęp do treści pliku. Jeśli plik nie jest udostępniany publicznie, adres URL zwrócony w thumbnailLink musi zostać pobrany za pomocą żądania z uprawnieniami.

zwracać listę miniatur;

Poniższy przykładowy kod pokazuje żądanie metody files.list z wieloma polami jako parametr 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. Z przykładowego kodu poniżej dowiesz się, jak ograniczyć listę do plików Arkuszy Google. Więcej informacji na temat typów MIME znajdziesz w artykule Typy MIME obsługiwane przez Google Workspace i Dysk Google.

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