Zarządzanie metadanymi plików

Ten dokument zawiera ważne informacje dotyczące nadawania nazw plików i pracy z metadanymi, takimi jak tekst indeksowalny i miniatury. 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 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 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 XML jako tekstu indeksowalnego nie jest tak przydatne jak zapisywanie 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ż indeksator robi to za Ciebie.
  • Aplikacja powinna aktualizować tekst indeksowany przy każdym zapisaniu.
  • 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 należy dodawać 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.

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 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 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:

  • mogą być przesyłane w formatach 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.

Pobieranie miniatur

Możesz pobierać metadane, w tym miniatury, plików na Dysku. Informacje o miniaturach 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, 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 jest dostępny, żądanie zwraca krótkotrwały adres URL miniatury pliku. Link jest zwykle ważny przez kilka godzin. Pole jest wypełniane tylko wtedy, gdy aplikacja przesyłająca żądanie ma dostęp do zawartoś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 parametrem zapytania, aby zwrócić 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)