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 zasobem files.
Omówienie metadanych
W interfejsie Google Drive API zasób files reprezentuje metadane. W przeciwieństwie do interfejsów API, w których metadane są obiektem podrzędnym, interfejs Drive API traktuje cały zasób files jako metadane. Możesz uzyskać dostęp do metadanych bezpośrednio za pomocą metod get lub list w zasobie files.
Domyślnie metody get i list zwracają tylko częściowy zestaw pól. Aby pobrać określone dane, musisz w żądaniu zdefiniować fields parametr systemowy. Jeśli ten parametr zostanie pominięty, serwer zwróci domyślny podzbiór pól specyficznych dla danej metody. Na przykład metoda list zwraca tylko pola kind, id, name, mimeType i resourceKey dla każdego pliku. Aby zwrócić inne pola, zobacz Zwracanie określonych pól.
Widoczność metadanych zależy też od roli użytkownika w pliku. Zasób permissions nie określa dozwolonych działań użytkownika w przypadku pliku lub folderu. Zamiast tego zasób files zawiera zbiór pól logicznych capabilities. Interfejs Google Drive API pobiera te capabilities z zasobu permissions powiązanego z plikiem lub folderem. Więcej informacji znajdziesz w artykule Omówienie funkcji plików.
Interfejs Drive API oferuje 2 zakresy metadanych z ograniczeniami: drive.metadata i drive.metadata.readonly. Zakres drive.metadata umożliwia wyświetlanie metadanych plików i zarządzanie nimi, a zakres drive.metadata.readonly jest tylko do odczytu. Obie te metody ściśle zabraniają dostępu do zawartości pliku. Więcej informacji znajdziesz w artykule Wybieranie zakresów interfejsu Google Drive API.
Na koniec zawsze sprawdzaj logikę dotyczącą uprawnień i zakresów. Na przykład użytkownik może być właścicielem pliku z pełnymi uprawnieniami, ale interfejs Drive API zablokuje próby modyfikacji lub pobrania pliku, jeśli Twoja aplikacja ma tylko zakres drive.metadata.readonly.
Określanie nazw i rozszerzeń plików
Aplikacje powinny określać rozszerzenie pliku we właściwości name podczas wstawiania plików za pomocą interfejsu Google Drive API. Na przykład operacja wstawienia pliku JPEG powinna zawierać 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 poprosi o pobranie pliku lub gdy plik zostanie pobrany za pomocą klienta synchronizacji, Dysk utworzy pełną nazwę pliku (z rozszerzeniem) na podstawie nazwy. W przypadku braku rozszerzenia Dysk próbuje określić je 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, który można indeksować
<section attribute="value1">Here's some text</section>, zindeksowany zostanie 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:
- Maksymalny rozmiar w przypadku parametru
contentHints.indexableTextto 128 KB. - Wpisz 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 powiązany z zawartością pliku lub jego metadanymi.
Ten ostatni punkt może się wydawać oczywisty, ale jest ważny. Nie warto dodawać popularnych wyszukiwanych słów, 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.imagena bezpieczny dla adresów URL i nazw plików obraz zakodowany w base64 (patrz sekcja 5 dokumentu RFC 4648). - W polu
contentHints.thumbnail.mimeTypeustaw odpowiedni typ MIME miniatury.
Jeśli Dysk może wygenerować miniaturę z pliku, użyje wygenerowanej automatycznie 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:
- 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 get z wieloma polami jako parametrem zapytania, aby zwrócić thumbnailLinkmetadane konkretnego 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 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 aktywny 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.
Zwraca listę miniatur.
Poniższy przykładowy kod pokazuje żądanie metody list z wieloma polami jako parametrem zapytania, które zwraca thumbnailLink
metadane 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)