Interfejs Google Drive API umożliwia przesyłanie danych plików podczas tworzenia lub aktualizowania File
. Informacje o tworzeniu plików zawierających tylko metadane, np. folderów, znajdziesz w artykule Tworzenie plików zawierających tylko metadane.
Istnieją 3 rodzaje przesyłania:
Proste przesyłanie (
uploadType=media
): użyj tego typu przesyłania, aby przenieść mały plik multimedialny (do 5 MB) bez dołączania metadanych. Aby przeprowadzić proste przesyłanie, zapoznaj się z artykułem Przeprowadzanie prostego przesyłania.Przesłanie w wielu częściach (
uploadType=multipart
): używaj tego typu przesyłania, aby przesłać mały plik (do 5 MB) wraz z metadanymi, które opisują plik, w jednym żądaniu. Aby przeprowadzić przesyłanie wieloczęściowe, zapoznaj się z artykułem Przesyłanie wieloczęściowe.Przesyłanie z możliwością wznowienia (
uploadType=resumable
): używaj tego typu przesyłania w przypadku dużych plików (większych niż 5 MB) oraz gdy istnieje duże prawdopodobieństwo przerwania połączenia z siecią, na przykład podczas tworzenia pliku z aplikacji mobilnej. Przesyłanie z możliwością wznowienia jest też dobrym wyborem w przypadku większości aplikacji, ponieważ działa również w przypadku małych plików przy minimalnym koszcie przesyłania, który stanowi jedno dodatkowe żądanie HTTP na przesyłanie. Aby przeprowadzić przesyłanie z możliwością wznowienia, zapoznaj się z artykułem Przeprowadzanie przesyłania z możliwością wznowienia.
Biblioteki klienta interfejsu API Google obsługują co najmniej 1 z tych typów przesyłania. Więcej informacji o sposobach używania poszczególnych typów znajdziesz w dokumentacji biblioteki klienta.
Użyj PATCH
lub PUT
Przypominamy, że czasownik HTTP PATCH
obsługuje częściową aktualizację zasobu pliku, a czasownik HTTP PUT
obsługuje pełną wymianę zasobu. Pamiętaj, że PUT
może wprowadzić zmiany powodujące przerwanie działania, gdy dodasz nowe pole do istniejącego zasobu.
Podczas przesyłania zasobu pliku postępuj zgodnie z tymi wskazówkami:
- Użyj czasownika HTTP opisanego w dokumentacji interfejsu API do początkowego żądania wznawialnego przesyłania lub jedynego żądania prostego lub wieloczęściowego przesyłania.
- Używaj
PUT
do wszystkich kolejnych próśb o przesyłanie z możliwością wznowienia, gdy żądanie zostało już rozpoczęte. Te żądania przesyłają treści niezależnie od wywoływanej metody.
Przesyłanie proste
Aby przeprowadzić proste przesyłanie, użyj metody files.create
z opcją uploadType=media
.
Poniżej znajdziesz instrukcje prostego przesyłania:
HTTP
Utwórz żądanie
POST
do identyfikatora URI metody /upload 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 nośnika MIME obiektu, który chcesz przesłać.Content-Length
. Ustaw na liczbę bajtów, które chcesz przesłać. Jeśli używasz kodowania przesyłania w porcjach, ten nagłówek nie jest wymagany.
Prześlij prośbę. Jeśli żądanie się powiedzie, serwer zwróci kod stanu
HTTP 200 OK
wraz z metadanymi pliku. {HTTP}
Podczas prostego przesyłania danych tworzone są podstawowe metadane, a z pliku wyodrębniane są niektóre atrybuty, takie jak typ MIME czy modifiedTime
. Możesz użyć prostego przesyłania w przypadku małych plików, których metadane nie są ważne.
Przesyłanie wieloczęściowe
Prośba o przesyłanie w wielu częściach umożliwia przesyłanie metadanych i danych w ramach tej samej prośby. Użyj tej opcji, jeśli wysyłane dane są na tyle małe, że można je ponownie przesłać w całości, jeśli połączenie się nie powiedzie.
Aby przeprowadzić przesyłanie wieloczęściowe, użyj metody files.create
z parametrem uploadType=multipart
.
Poniżej znajdziesz instrukcje przesyłania wieloczęściowego:
Java
Python
Node.js
PHP
.NET
HTTP
Utwórz żądanie
POST
do identyfikatora URI metody /upload 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 multipart/related RFC 2387, który składa się z 2 części:
- Metadane Metadane muszą być podane jako pierwsze i mieć nagłówek
Content-Type
application/json;
charset=UTF-8
. Dodaj metadane pliku w formacie JSON. - Multimedia. Media muszą znajdować się w drugiej kolejności i mieć nagłówek
Content-Type
dowolnego typu MIME. Dodaj dane pliku do części multimedialnej.
Każdą część należy oznaczyć ciągiem znaków granicznych poprzedzonym przez 2 łączniki. Dodatkowo dodaj 2 łączniki po ostatnim ciągu znaków granicy.
- Metadane Metadane muszą być podane jako pierwsze i mieć nagłówek
Dodaj te nagłówki HTTP najwyższego poziomu:
Content-Type
. Ustaw namultipart/related
i uwzględnij ciąg znaków 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 ciele żądania.
Prześ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 się powiedzie, serwer zwróci kod stanu HTTP 200 OK
wraz z metadanymi pliku.
Podczas tworzenia plików należy określić rozszerzenie pliku w polu name
. Podczas tworzenia pliku JPEG ze zdjęciem możesz na przykład podać w metadanych wartość "name": "photo.jpg"
. Kolejne wywołania funkcji files.get
zwracają właściwość fileExtension
tylko do odczytu, która zawiera rozszerzenie określone pierwotnie w polu name
.
Przesyłanie z możliwością wznowienia
Przesyłanie z możliwością wznowienia umożliwia wznowienie operacji przesyłania po tym, jak błąd komunikacji przerwie przepływ danych. Ponieważ nie musisz ponownie rozpoczynać przesyłania dużych plików, przesyłanie z możliwością wznowienia może też zmniejszyć wykorzystanie przepustowości, jeśli wystąpi błąd sieci.
Przerywane przesyłanie jest przydatne, gdy rozmiary plików mogą się znacznie różnić lub gdy istnieją stałe limity czasowe dla żądań (np. zadania w tle w systemie operacyjnym na urządzeniach mobilnych i niektóre żądania App Engine). Przesyłanie możliwe do wznowienia możesz też stosować w sytuacjach, gdy chcesz wyświetlić pasek postępu przesyłania.
Przerywane przesyłanie składa się z kilku kroków ogólnych:
- Wyślij początkowe żądanie i pobierz identyfikator URI sesji, którą można wznowić.
- Przesyłanie danych i monitorowanie stanu przesyłania.
- (opcjonalnie) Jeśli przesyłanie zostało przerwane, wznów je.
Wysyłanie początkowego żądania
Aby rozpocząć przesyłanie możliwe do wznowienia, użyj metody files.create
z uploadType=resumable
.
HTTP
Utwórz żądanie
POST
do identyfikatora URI metody /upload z parametrem zapytaniauploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Jeśli żądanie zainicjowania się powiedzie, odpowiedź będzie zawierać kod stanu HTTP
200 OK
. Dodatkowo zawiera nagłówekLocation
, który określa identyfikator URI sesji, którą można wznowić: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, którą można wznowić, aby móc przesłać dane pliku i wysłać zapytanie o stan przesyłania. Identyfikator URI sesji, którą można wznowić, 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
. Opcjonalna. Ustaw na typ MIME danych pliku, które są przesyłane w kolejnych żądaniach. Jeśli typ MIME danych nie jest określony w metadanych ani w tym nagłówku, obiekt jest wyświetlany jakoapplication/octet-stream.
X-Upload-Content-Length
. Opcjonalna. Ustaw na liczbę bajtów danych pliku, które są przesyłane w kolejnych żądaniach.Content-Type
. Wymagane, jeśli masz metadane pliku. Ustaw naapplication/json;
charset=UTF-8
.Content-Length
. Wymagane, chyba że używasz kodowania z dzieleniem na części. Ustaw na liczbę bajtów w treści tego początkowego żądania.
Prześlij prośbę. Jeśli żądanie rozpoczęcia sesji zakończy się powodzeniem, odpowiedź będzie zawierać kod stanu
200 OK HTTP
. Dodatkowo odpowiedź zawiera nagłówekLocation
, który określa identyfikator URI sesji z możliwością wznowienia. Użyj identyfikatora URI sesji z możliwością wznowienia, aby przesłać dane pliku i sprawdzić stan przesyłania. Identyfikator URI sesji, którą można wznowić, wygasa po tygodniu.Skopiuj i zapisz adres URL sesji, którą można wznowić.
Przejdź do przesyłania treści.
Przesyłanie treści
Plik można przesłać w ramach sesji możliwej do wznowienia na 2 sposoby:
- Przesyłanie treści w ramach jednego żądania: użyj tego podejścia, gdy plik może zostać przesłany w ramach jednego żądania, jeśli nie ma określonego limitu czasu dla żadnego żądania lub nie musisz wyświetlać wskaźnika postępu przesyłania. To podejście jest najlepsze, ponieważ wymaga wysłania mniejszej liczby żądań i daje lepsze wyniki.
Przesyłanie treści w kilku częściach: użyj tego podejścia, jeśli musisz zmniejszyć ilość danych przesyłanych w pojedynczym żądaniu. Jeśli w przypadku poszczególnych żądań obowiązuje określony limit czasowy, konieczne może być ograniczenie przesyłanych danych. Może się tak zdarzyć w przypadku niektórych klas żądań App Engine. Takie podejście jest też przydatne, jeśli musisz wyświetlić niestandardowy wskaźnik postępu przesyłania.
HTTP – pojedyncze żądanie
- Utwórz żądanie
PUT
do identyfikatora URI sesji z możliwością wznowienia. - Dodaj dane pliku do treści żądania.
- Dodaj nagłówek HTTP Content-Length, ustawiając go na liczbę bajtów w pliku.
- Prześlij prośbę. Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź
5xx
, postępuj zgodnie z instrukcjami w artykule Wznawianie przerwanego przesyłania.
HTTP – wiele żądań
Utwórz żądanie
PUT
do identyfikatora URI sesji z możliwością wznowienia.Dodaj dane fragmentu do treści żądania. Tworzenie fragmentów o wielokrotności 256 KB (256 x 1024 bajtów), z wyjątkiem ostatniego fragmentu, który kończy przesyłanie. Ustaw rozmiar fragmentu na jak największy, aby przesyłanie było wydajne.
Dodaj te nagłówki HTTP:
Content-Length
. Ustaw na liczbę bajtów w bieżącym fragmencie.Content-Range
. Ustaw, które bajty w przesyłanym pliku mają być widoczne. Na przykładContent-Range: bytes 0-524287/2000000
oznacza, że przesyłasz pierwsze 524 288 bajtów (256 x 1024 x 2) z pliku o rozmiarze 2 000 000 bajtów.
Prześlij żądanie i przetwórz odpowiedź. Jeśli żądanie przesyłania zostało przerwane lub jeśli otrzymasz odpowiedź
5xx
, postępuj zgodnie z instrukcjami w artykule Wznawianie przerwanego przesyłania.Powtórz kroki 1–4 w przypadku każdego fragmentu, który pozostał w pliku. Aby określić, gdzie ma się zacząć następny fragment, użyj nagłówka
Range
w odpowiedzi. 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 z metadanymi powiązanymi z zasobem.
Wznawianie przerwanego przesyłania
Jeśli żądanie przesyłania zostało przerwane przed otrzymaniem odpowiedzi lub jeśli otrzymasz odpowiedź 503
Service Unavailable
, musisz wznowić przerwane przesyłanie.
HTTP
Aby uzyskać stan przesyłania, utwórz puste żądanie
PUT
do identyfikatora URI sesji z możliwością wznowienia.Dodaj nagłówek
Content-Range
, aby wskazać, że bieżąca pozycja w pliku jest nieznana. Jeśli na przykład łączna długość pliku wynosi 2 000 000 bajtów, ustaw wartość parametruContent-Range
na*/2000000
. Jeśli nie znasz pełnego rozmiaru pliku, ustawContent-Range
na*/*
.Prześlij prośbę.
Przetwarzanie odpowiedzi:
- Odpowiedź
200 OK
lub201 Created
oznacza, że przesyłanie zostało zakończone i nie trzeba podejmować żadnych dalszych działań. - Odpowiedź
308 Resume Incomplete
oznacza, że musisz kontynuować przesyłanie pliku. - Odpowiedź
404 Not Found
wskazuje, że sesja przesyłania wygasła i przesyłanie musi zostać rozpoczęte od początku.
- Odpowiedź
Jeśli otrzymasz odpowiedź
308 Resume Incomplete
, przetwórz nagłówekRange
odpowiedzi, aby określić, które bajty zostały odebrane przez serwer. Jeśli odpowiedź nie zawiera nagłówkaRange
, nie otrzymano żadnych bajtów. Na przykład nagłówekRange
o wartościbytes=0-42
wskazuje, że otrzymano pierwsze 43 bajty pliku, a następny fragment do przesłania rozpocznie się od bajtu 44.Teraz, gdy wiesz, od którego miejsca wznowić przesyłanie, kontynuuj przesyłanie pliku, zaczynając od następnego bajta. 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 o numerach 44–2 000 000.
Obsługa błędów przesyłania multimediów
Podczas przesyłania multimediów stosuj te sprawdzone metody radzenia sobie z błędami:
- W przypadku błędów
5xx
wznów lub ponów próbę przesyłania, które nie powiodło się z powodu przerwania połączenia. Więcej informacji o postępowaniu z błędami5xx
znajdziesz w artykule Błędy 500, 502, 503 i 504. - W przypadku błędów
403 rate limit
spróbuj przesłać plik ponownie. Więcej informacji o rozwiązywaniu błędów403 rate limit
znajdziesz w artykule Błąd 403:rateLimitExceeded
. - W przypadku błędów
4xx
(w tym403
) podczas przesyłania z możliwością wznowienia należy je ponownie rozpocząć. Te błędy wskazują, że sesja przesyłania wygasła i musi zostać ponownie uruchomiona przez wysłanie żądania nowego identyfikatora URI sesji. Sesje przesyłania również wygasają po tygodniu nieaktywności.
Importowanie do typów Dokumentów Google
Podczas tworzenia pliku na Dysku możesz chcieć przekonwertować go na plik typu Google Workspace, takiego jak Dokumenty lub Arkusze. Możesz na przykład przekonwertować dokument z ulubionego procesora tekstu na dokument Google, aby skorzystać z jego funkcji.
Aby przekonwertować plik na określony typ pliku Google Workspace, podczas tworzenia pliku określ opcję Google Workspace mimeType
.
Poniżej znajdziesz instrukcje konwertowania pliku CSV na arkusz Google Workspace:
Java
Python
Node.js
PHP
.NET
Aby sprawdzić, czy konwersja jest dostępna, przed utworzeniem pliku sprawdź tablicę importFormats
zasobu about
.
Obsługiwane konwersje są dynamicznie dostępne w tym tablicy. Oto kilka typowych formatów importu:
Z | Do |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, zwykły tekst | Dokumenty Google |
Microsoft Excel, OpenDocument Spreadsheet, CSV, TSV, zwykły tekst | Arkusze Google |
Microsoft PowerPoint, prezentacja OpenDocument | Prezentacje Google |
JPEG, PNG, GIF, BMP, PDF | Dokumenty Google (obraz jest umieszczany w dokumencie) |
Tekst (specjalny typ MIME), JSON | Google Apps Script |
Gdy przesyłasz i konwertujesz multimedia podczas update
do pliku Dokumentów, Arkuszy lub Prezentacji, cała zawartość dokumentu zostanie zastąpiona.
Gdy konwertujesz obraz na dokument w Dokumentach, Dysk używa optycznego rozpoznawania znaków (OCR), aby przekształcić obraz w tekst. Możesz poprawić jakość algorytmu OCR, podając odpowiedni kod języka BCP 47 w parametrze ocrLanguage
. Wyodrębniony tekst pojawi się w dokumencie obok umieszczonego obrazu.
Przesyłanie plików za pomocą wygenerowanego wcześniej identyfikatora
Interfejs Drive API umożliwia pobieranie listy wcześniej wygenerowanych identyfikatorów plików, które służą do przesyłania i tworzenia zasobów. Prośby o przesyłanie i tworzenie plików mogą używać tych wstępnie wygenerowanych identyfikatorów. W metadanych pliku ustaw pole id
.
Aby utworzyć wygenerowane wcześniej identyfikatory, wywołaj funkcję files.generateIds
z liczbą identyfikatorów do utworzenia.
Jeśli wystąpi nieokreślony błąd serwera lub przekroczenie limitu czasu, możesz bezpiecznie powtórzyć przesyłanie za pomocą wygenerowanych wcześniej identyfikatorów. Jeśli plik został utworzony, kolejne próby zwracają błąd HTTP 409
i nie tworzą duplikatów.
Definiowanie tekstu możliwego do zindeksowania w przypadku nieznanych typów plików
Użytkownicy mogą znaleźć zawartość dokumentu za pomocą interfejsu Dysku. Możesz też użyć pola files.list
i fullText
, aby wyszukać treści z aplikacji. 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 zwiększyć ich widoczność, podając tekst do zindeksowania w polu contentHints.indexableText
pliku.
Więcej informacji o tekstach możliwych do zindeksowania znajdziesz w artykule Zarządzanie metadanymi plików.