Interfejs Google Drive API umożliwia przesyłanie danych plików podczas tworzenia lub aktualizowania File
. Aby dowiedzieć się, jak utworzyć plik zawierający tylko metadane, np. folder, przeczytaj artykuł Tworzenie plików zawierających tylko metadane.
Istnieją 3 rodzaje przesyłania:
Proste przesyłanie (
uploadType=media
): ten typ przesyłania służy do przesyłania niewielkich plików multimedialnych (maksymalnie 5 MB) bez konieczności dostarczania metadanych. Informacje o prostym przesyłaniu znajdziesz w artykule Przesyłanie prostego pliku.Przesyłanie wieloczęściowe (
uploadType=multipart
): „za pomocą tego typu przesyłania możesz przesłać w jednym żądaniu niewielki plik (do 5 MB) wraz z metadanymi opisującymi go. Aby dowiedzieć się, jak przesyłać wiele części, przeczytaj artykuł Przesyłanie wieloczęściowe.Wznawianie przesyłania (
uploadType=resumable
): tego typu przesyłania używaj w przypadku dużych plików (większych niż 5 MB) i gdy występuje wysokie ryzyko przerw w działaniu sieci, np. podczas tworzenia pliku z aplikacji mobilnej. W przypadku większości aplikacji dobrym rozwiązaniem jest też przesyłanie z możliwością wznowienia, ponieważ takie rozwiązanie sprawdza się też w przypadku małych plików przy minimalnym koszcie 1 dodatkowego żądania HTTP na przesłanie. Aby dowiedzieć się, jak wznowić przesyłanie, przeczytaj sekcję Przesyłanie z możliwością wznowienia.
Biblioteki klienta interfejsów API Google implementują co najmniej 1 z tych typów przesyłania. Więcej informacji o korzystaniu z poszczególnych typów znajdziesz w dokumentacji biblioteki klienta.
Używaj strategii PATCH
i PUT
Dla przypomnienia: czasownik HTTP PATCH
obsługuje częściową aktualizację zasobów plików, natomiast czasownik HTTP PUT
obsługuje pełne zastępowanie zasobów. Pamiętaj, że PUT
może wprowadzić zmiany powodujące niezgodność podczas dodawania nowego pola do istniejącego zasobu.
Podczas przesyłania zasobu związanego z plikiem postępuj zgodnie z tymi wskazówkami:
- Używaj czasowników HTTP opisanych w dokumentacji API w przypadku początkowego żądania przesyłania możliwego do wznowienia lub jedynego żądania prostego lub wieloczęściowego przesyłania.
- Używaj
PUT
w przypadku wszystkich kolejnych żądań wznowienia przesyłania po ich rozpoczęciu. Żądania te przesyłają treści niezależnie od wywoływania metody.
Proste przesyłanie
Aby wykonać proste przesyłanie, użyj metody files.create
z uploadType=media
.
Poniżej pokazujemy, jak wykonać proste przesyłanie:
HTTP
Utwórz żądanie
POST
do identyfikatora URI /upload metody z parametrem zapytaniauploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Dodaj dane pliku do treści żądania.
Dodaj te nagłówki HTTP:
Content-Type
. Ustaw typ multimediów MIME przesyłanego obiektu.Content-Length
. Ustaw liczbę przesyłanych bajtów. Jeśli używasz fragmentowego kodowania transferu, ten nagłówek nie jest wymagany.
Wyślij prośbę. Jeśli żądanie zostanie zrealizowane, serwer zwraca kod stanu
HTTP 200 OK
wraz z metadanymi pliku. {HTTP}
Gdy wykonujesz proste przesyłanie, tworzone są podstawowe metadane, a niektóre atrybuty są pobierane z pliku, takie jak typ MIME czy modifiedTime
. Możesz użyć prostego przesyłania w sytuacjach, gdy masz małe pliki, a metadane plików nie są ważne.
Przesyłanie wieloczęściowe
Wieloczęściowe żądanie przesyłania umożliwia przesyłanie metadanych i danych w ramach tego samego żądania. Użyj tej opcji, jeśli wysyłane dane są wystarczająco małe, by przesłać je ponownie w całości w przypadku niepowodzenia połączenia.
Aby przesłać wiele części, użyj metody files.create
z uploadType=multipart
.
Poniżej przedstawiono sposób przesyłania wieloczęściowego:
Java
Python
Node.js
PHP
.NET
HTTP
Utwórz żądanie
POST
do identyfikatora URI /upload metody z parametrem zapytaniauploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Utwórz treść żądania. Sformatuj treść zgodnie z typem treści wieloczęściowych/powiązanych RFC 2387, który składa się z 2 części:
- Metadane Metadane muszą występować na pierwszym miejscu i muszą mieć nagłówek
Content-Type
ustawiony naapplication/json;
charset=UTF-8
. Dodaj metadane pliku w formacie JSON. - Multimedia. Plik multimedialny musi być na drugim miejscu i musi mieć nagłówek
Content-Type
dowolnego typu MIME. Dodaj dane pliku do sekcji multimediów.
Określ każdą część za pomocą ciągu granicy poprzedzonego 2 łącznikami. Dodatkowo po końcowym ciągu znaków granicznych wstaw 2 łączniki.
- Metadane Metadane muszą występować na pierwszym miejscu i muszą mieć nagłówek
Dodaj te nagłówki HTTP najwyższego poziomu:
Content-Type
. Ustaw wartośćmultipart/related
i dodaj ciąg granicy używany do identyfikowania różnych części żądania. Przykład:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Ustaw na łączną liczbę bajtów w treści żądania.
Wyślij prośbę.
Aby utworzyć lub zaktualizować tylko część metadanych bez powiązanych danych, wyślij żądanie POST
lub PATCH
do standardowego punktu końcowego zasobu:https://www.googleapis.com/drive/v3/files
Jeśli żądanie zostanie zrealizowane, serwer zwraca kod stanu HTTP 200 OK
wraz z metadanymi pliku.
Podczas tworzenia plików należy określić ich rozszerzenie w polu name
. Na przykład podczas tworzenia pliku JPEG zdjęcia możesz w metadanych określić coś takiego jak "name": "photo.jpg"
. Kolejne wywołania files.get
zwracają właściwość fileExtension
tylko do odczytu zawierającą rozszerzenie pierwotnie określone w polu name
.
Przesyłanie z możliwością wznowienia
Przesyłanie z możliwością wznowienia umożliwia wznowienie operacji przesyłania, gdy błąd komunikacji przerwie przepływ danych. Wznowienie przesyłania dużych plików nie wymaga od razu ponownego rozpoczynania przesyłania, więc w przypadku awarii sieci może to spowodować zmniejszenie wykorzystania przepustowości.
Przesyłanie z możliwością wznowienia jest przydatne, gdy rozmiary plików mogą się znacznie różnić lub gdy istnieje ustalony limit czasu dla żądań (takich jak zadania wykonywane w tle na urządzeniu mobilnym lub określone żądania App Engine). Możesz też użyć funkcji wznawiania przesyłania, gdy chcesz pokazać pasek postępu przesyłania.
Przesyłanie danych, które można wznowić, składa się z kilku głównych czynności:
- Wyślij początkowe żądanie i pobierz identyfikator URI sesji możliwej do wznowienia.
- Przesyłanie danych i monitorowanie stanu przesyłania.
- (Opcjonalnie) Jeśli przesyłanie zostało zakłócone, wznów przesyłanie.
Wyślij początkową prośbę
Aby zainicjować przesyłanie z możliwością wznowienia, użyj metody files.create
z uploadType=resumable
.
HTTP
Utwórz żądanie
POST
do identyfikatora URI /upload metody z parametrem zapytaniauploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Jeśli żądanie inicjowania się powiedzie, odpowiedź będzie zawierać kod stanu HTTP
200 OK
. Dodatkowo zawiera nagłówekLocation
, który określa identyfikator URI sesji możliwej do wznowienia:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Zapisz identyfikator URI sesji możliwej do wznowienia, aby móc przesłać dane pliku i zapytać o stan przesyłania. Identyfikator URI sesji z możliwością wznowienia wygasa po tygodniu.
Jeśli masz metadane pliku, dodaj je do treści żądania w formacie JSON. W przeciwnym razie pozostaw treść żądania pustą.
Dodaj te nagłówki HTTP:
X-Upload-Content-Type
. Opcjonalnie. Ustaw typ MIME danych pliku, które są przesyłane w kolejnych żądaniach. Jeśli typ MIME danych nie jest określony w metadanych ani przez ten nagłówek, obiekt jest udostępniany jakoapplication/octet-stream.
X-Upload-Content-Length
. Opcjonalnie. Ustaw liczbę bajtów danych plików, które są przesyłane w kolejnych żądaniach.Content-Type
. Wymagany, jeśli masz metadane pliku. Ustaw jakoapplication/json;
charset=UTF-8
.Content-Length
. Wymagane, chyba że używasz fragmentów kodowania transferu. Ustaw liczbę bajtów w treści tego początkowego żądania.
Wyślij prośbę. Jeśli żądanie inicjowania sesji zostanie zrealizowane, odpowiedź zawiera kod stanu
200 OK HTTP
. Dodatkowo odpowiedź zawiera nagłówekLocation
, który określa identyfikator URI sesji możliwej do wznowienia. Aby przesłać dane pliku i zapytać o stan przesyłania, użyj identyfikatora URI sesji możliwego do wznowienia. Identyfikator URI sesji z możliwością wznowienia wygasa po tygodniu.Skopiuj i zapisz adres URL sesji możliwej do wznowienia.
Przejdź do sekcji Przesyłanie treści.
Prześlij treści
Plik z sesją, którą można wznowić, można przesłać na 2 sposoby:
- Prześlij treści w ramach pojedynczego żądania: skorzystaj z tej metody, jeśli plik można przesłać w ramach jednego żądania, jeśli nie ma stałego limitu czasu dla pojedynczego żądania lub nie musisz wyświetlać wskaźnika postępu przesyłania. Ta metoda jest najlepsza, ponieważ wymaga mniejszej liczby żądań i zwiększa wydajność.
Prześlij treść w wielu fragmentach: użyj tej metody, jeśli musisz zmniejszyć ilość danych przesyłanych w jednym żądaniu. Gdy istnieje ustalony limit czasu na poszczególne żądania, może być konieczne zmniejszenie ilości przesyłanych danych, jak w przypadku niektórych klas żądań App Engine. Ta metoda jest też przydatna, jeśli musisz zapewnić niestandardowy wskaźnik postępu przesyłania.
HTTP – pojedyncze żądanie
- Utwórz żądanie
PUT
do identyfikatora URI sesji możliwej do wznowienia. - Dodaj dane pliku do treści żądania.
- Dodaj nagłówek HTTP Content-Length, ustawiony na liczbę bajtów w pliku.
- Wyślij prośbę. Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź
5xx
, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.
HTTP – wiele żądań
Utwórz żądanie
PUT
do identyfikatora URI sesji możliwej do wznowienia.Dodaj dane fragmentu do treści żądania. Utwórz fragmenty jako wielokrotności 256 KB (256 x 1024 bajty) z wyjątkiem ostatniego fragmentu, który kończy przesyłanie. Aby przesyłanie było skuteczne, zadbaj o jak największą wielkość fragmentu.
Dodaj te nagłówki HTTP:
Content-Length
. Ustaw na liczbę bajtów w bieżącym fragmencie.Content-Range
. Służy do wyświetlania liczby bajtów w przesłanym pliku. Na przykładContent-Range: bytes 0-524287/2000000
pokazuje, że przesyłasz pierwsze 524 288 bajtów (256 × 1024 × 2) w pliku o wielkości 2 000 000 bajtów.
Wyślij żądanie i przetwórz odpowiedź. Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź
5xx
, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.Powtarzaj kroki od 1 do 4 w przypadku każdego fragmentu, który pozostaje w pliku. Aby określić, od którego momentu rozpocząć następny fragment, użyj w odpowiedzi nagłówka
Range
. Nie zakładaj, że serwer otrzymał wszystkie bajty wysłane w poprzednim żądaniu.
Po zakończeniu przesyłania pliku otrzymasz odpowiedź 200 OK
lub 201 Created
wraz ze wszystkimi metadanymi powiązanymi z zasobem.
Wznawianie przerwanego przesyłania
Jeśli żądanie przesłania zostanie zakończone przed otrzymaniem odpowiedzi lub gdy otrzymasz odpowiedź 503
Service Unavailable
, musisz wznowić przerwane przesyłanie.
HTTP
Aby zażądać stanu przesyłania, utwórz puste żądanie
PUT
do identyfikatora URI sesji możliwej do wznowienia.Dodaj nagłówek
Content-Range
, aby wskazać, że bieżąca pozycja w pliku jest nieznana. Jeśli np. łączna długość pliku to 2 000 000 bajtów, ustawContent-Range
na*/2000000
. Jeśli nie znasz pełnego rozmiaru pliku, ustawContent-Range
na*/*
.Wyślij prośbę.
Przetwarzaj odpowiedź:
- Odpowiedź
200 OK
lub201 Created
oznacza, że przesyłanie zostało zakończone i nie musisz nic więcej robić. - Odpowiedź
308 Resume Incomplete
oznacza, że musisz kontynuować przesyłanie pliku. - Odpowiedź
404 Not Found
oznacza, że sesja przesyłania wygasła i trzeba rozpocząć przesyłanie od początku.
- Odpowiedź
Jeśli otrzymano odpowiedź
308 Resume Incomplete
, przetwórz jej nagłówekRange
, aby określić, jakie bajty odebrał serwer. Jeśli odpowiedź nie ma nagłówkaRange
, nie otrzymano żadnych bajtów. Na przykład nagłówekRange
o wartościbytes=0-42
oznacza, że otrzymano pierwsze 43 bajty pliku i że następny fragment do przesłania rozpoczynałby się od bajtu 44.Gdy już wiesz, gdzie wznowić przesyłanie, możesz kontynuować przesyłanie pliku, zaczynając od następnego bajtu. Dołącz nagłówek
Content-Range
, aby wskazać, która część pliku jest wysyłana. Na przykładContent-Range: bytes 43-1999999
oznacza, że wysyłasz bajty od 44 do 2 000 000.
Postępowanie w przypadku błędów przesyłania multimediów
Podczas przesyłania multimediów postępuj zgodnie z tymi sprawdzonymi metodami, aby naprawić błędy:
- W przypadku
5xx
błędów wznów lub ponów próbę przesyłania, które nie powiedzie się z powodu przerw w połączeniu. Więcej informacji o postępowaniu z błędami5xx
znajdziesz w sekcji dotyczącej błędów 500, 502, 503 i 504. - Jeśli wystąpiło
403 rate limit
błędów, spróbuj przesłać ponownie. Więcej informacji o postępowaniu z błędami403 rate limit
znajdziesz w sekcji dotyczącej błędu 403:rateLimitExceeded
. - W przypadku wszelkich błędów
4xx
(w tym403
) występujących podczas przesyłania możliwego do wznowienia, uruchom przesyłanie ponownie. Te błędy oznaczają, że sesja przesyłania wygasła i trzeba ją uruchomić ponownie, żądając nowego identyfikatora URI sesji. Sesje przesyłania wygasają również po tygodniu braku aktywności.
Typy importu do Dokumentów Google
Gdy tworzysz plik na Dysku, możesz go przekonwertować na typ pliku Google Workspace, taki jak Dokumenty lub Arkusze Google. Można na przykład przekształcić dokument z ulubionego edytora tekstu w Dokumenty, aby skorzystać z jego funkcji.
Aby przekonwertować plik na określony typ pliku Google Workspace, podczas tworzenia pliku wskaż mimeType
Google Workspace.
Poniżej pokazujemy, jak przekonwertować plik CSV na arkusz Google Workspace:
Java
Python
Node.js
PHP
.NET
Aby zobaczyć, czy jest dostępna konwersja, przed utworzeniem pliku sprawdź tablicę importFormats
zasobu about
.
Obsługiwane konwersje są dostępne w tej tablicy dynamicznie. Typowe formaty importu:
Od | Do |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, zwykły tekst | Dokumenty Google |
Microsoft Excel, OpenDocument Sheet, CSV, TSV, zwykły tekst | Arkusze Google |
Microsoft PowerPoint, prezentacja OpenDocument | Prezentacje Google |
JPEG, PNG, GIF, BMP, PDF | Dokumenty Google (umieszcza obraz w dokumencie) |
Zwykły tekst (specjalny typ MIME), JSON | Google Apps Script |
Gdy w ramach żądania update
przesyłasz multimedia i konwertujesz je na plik Dokumentów, Arkuszy lub Prezentacji, zastępowana jest pełna zawartość dokumentu.
Gdy konwertujesz obraz na plik Dokumentów, Dysk używa optycznego rozpoznawania znaków (OCR) do konwersji na tekst. Możesz poprawić jakość algorytmu OCR, określając odpowiedni kod języka BCP47 w parametrze ocrLanguage
. Wyodrębniony tekst pojawi się w dokumencie obok umieszczonego obrazu.
Używanie wcześniej wygenerowanego identyfikatora do przesyłania plików
Interfejs Drive API umożliwia pobranie listy wstępnie wygenerowanych identyfikatorów plików, które służą do przesyłania i tworzenia zasobów. W prośbach o przesłanie i utworzenie pliku
można wykorzystać te wstępnie wygenerowane identyfikatory. Ustaw pole id
w metadanych pliku.
Aby utworzyć wstępnie wygenerowane identyfikatory, wywołaj metodę files.generateIds
z odpowiednią liczbą identyfikatorów do utworzenia.
Jeśli wystąpi nieokreślony błąd serwera lub przekroczono czas oczekiwania, możesz bezpiecznie przesłać treści ponownie przy użyciu wstępnie wygenerowanych identyfikatorów. Jeśli plik został utworzony, kolejne próby zwracają błąd HTTP 409
i nie tworzą duplikatów plików.
Zdefiniuj indeksowalny tekst dla nieznanych typów plików
Użytkownicy mogą znajdować treść dokumentów w interfejsie Dysku. Do wyszukiwania zawartości aplikacji możesz też używać files.list
i pola fullText
. Więcej informacji znajdziesz w artykule Wyszukiwanie plików i folderów.
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.
Więcej informacji o tekście umożliwiającym indeksowanie znajdziesz w artykule Zarządzanie metadanymi plików.