Ta strona została przetłumaczona przez Cloud Translation API.

Zarządzaj długo trwającymi operacjami

Długo trwająca operacja (LRO) to metoda interfejsu API, której wykonanie trwa dłużej niż jest to odpowiednie w przypadku odpowiedzi interfejsu API. Zwykle nie chcesz, aby wątek wywołujący był otwarty podczas wykonywania zadania, ponieważ pogarsza to wrażenia użytkownika. Zamiast tego lepiej zwrócić użytkownikowi obietnicę i umożliwić mu sprawdzenie stanu później.

Interfejs Google Drive API zwraca LRO za każdym razem, gdy wywołujesz metodę download w zasobie files, aby pobrać zawartość pliku za pomocą interfejsu Drive API lub jego bibliotek klienta.

Metoda zwraca klientowi zasób operations. Za pomocą zasobu operations możesz asynchronicznie pobierać stan metody interfejsu API, sprawdzając operację za pomocą metody get. Operacje LRO w interfejsie Drive API są zgodne z wzorcem projektowania operacji LRO w Google Cloud.

Więcej informacji znajdziesz w artykule Operacje długotrwałe.

Omówienie procesu

Na diagramie poniżej przedstawiono ogólne kroki działania metody file.download.

**Rysunek 1.** Najważniejsze kroki metody file.download.

Wywołanie files.download: gdy aplikacja wywołuje metodę download, wysyła żądanie pobrania pliku z interfejsu Drive API. Więcej informacji znajdziesz w artykule Pobieranie plików.
Poproś o uprawnienia: żądanie wysyła dane logowania do interfejsu Drive API. Jeśli aplikacja wymaga wywoływania interfejsu Drive API przy użyciu uwierzytelniania użytkownika, które nie zostało jeszcze przyznane, wyświetla prośbę o zalogowanie się. Aplikacja prosi też o dostęp z zakresami, które określasz podczas konfigurowania uwierzytelniania.
Rozpocznij pobieranie: wysyłane jest żądanie do interfejsu Drive API, aby rozpocząć pobieranie pliku. Prośba może dotyczyć Google Vids lub innych treści Google Workspace.
Uruchomienie LRO: rozpoczyna się długo trwająca operacja, która zarządza procesem pobierania.
Zwróć oczekującą operację: interfejs Drive API zwraca oczekującą operację zawierającą informacje o użytkowniku wysyłającym żądanie i kilka pól metadanych pliku.
Początkowy stan oczekiwania: aplikacja otrzymuje operację oczekującą wraz z początkowym stanem oczekiwania done=null. Oznacza to, że plik nie jest jeszcze gotowy do pobrania, a stan operacji to oczekiwanie.
Wywołaj operations.get i sprawdź wynik: aplikacja wywołuje get w zalecanych odstępach czasu, aby sprawdzać wynik operacji i uzyskiwać najnowszy stan długo trwającej operacji. Jeśli zwrócony zostanie stan oczekiwania done=false, aplikacja musi kontynuować sondowanie, dopóki operacja nie zwróci stanu ukończenia (done=true). W przypadku dużych plików sondowanie może być konieczne wielokrotnie. Więcej informacji znajdziesz w artykule Uzyskiwanie szczegółów długotrwałej operacji.
Sprawdź stan oczekiwania: jeśli LRO zwróci stan oczekiwania done=true, oznacza to, że plik jest gotowy do pobrania, a stan operacji to „ukończono”.
Zwróć ukończoną operację z identyfikatorem URI pobierania: po zakończeniu długo trwającej operacji interfejs Drive API zwraca identyfikator URI pobierania, a plik jest teraz dostępny dla użytkownika.

Pobieranie plików

Aby pobrać treści w ramach długotrwałej operacji, użyj metody download w zasobie files. Metoda przyjmuje parametry zapytania file_id, mime_type i revision_id:

Wymagany. Parametr zapytania file_id to identyfikator pliku do pobrania.
Opcjonalnie. Parametr zapytania mime_type oznacza typ MIME, którego powinna używać metoda. Jest ona dostępna tylko podczas pobierania treści multimedialnych innych niż obiekty blob (takich jak dokumenty Google Workspace). Pełną listę obsługiwanych typów MIME znajdziesz w artykule Eksportowanie typów MIME w dokumentach Google Workspace.

Jeśli typ MIME nie jest ustawiony, dokument Google Workspace zostanie pobrany z domyślnym typem MIME. Więcej informacji znajdziesz w artykule Domyślne typy MIME.
Opcjonalnie. Parametr zapytania revision_id to identyfikator wersji pliku do pobrania. Jest dostępna tylko podczas pobierania plików binarnych, Dokumentów Google i Arkuszy Google. Zwraca kod błędu INVALID_ARGUMENT podczas pobierania konkretnej wersji w przypadku nieobsługiwanych plików.

Metoda download to jedyny sposób na pobieranie plików Vids w formacie MP4. Zwykle najlepiej sprawdza się w przypadku pobierania większości plików wideo.

Linki pobierania wygenerowane początkowo dla Dokumentów lub Arkuszy Google zwracają przekierowanie. Kliknij nowy link, aby pobrać plik.

Żądanie do metody download, które rozpoczyna LRO, oraz żądanie pobrania końcowego identyfikatora URI pobierania powinny używać kluczy zasobów. Więcej informacji znajdziesz w artykule Dostęp do plików na Dysku udostępnionych za pomocą linku przy użyciu kluczy zasobów.

Protokół żądania jest widoczny tutaj.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Zastąp FILE_ID fileId pliku, który chcesz pobrać.

Domyślne typy MIME

Jeśli podczas pobierania treści innych niż obiekty blob nie ustawisz typu MIME, zostaną przypisane te domyślne typy MIME:

Typ dokumentu	Format	typ MIME	Rozszerzenie pliku
Google Apps Script	JSON	application/vnd.google-apps.script+json	.json
Dokumenty Google	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Rysunki Google	PNG	image/png	.png
Formularze Google	Kod pocztowy	application/zip	.zip
Arkusze Google	Microsoft Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
Witryny Google	Zwykły tekst	text/raw	.txt
Prezentacje Google	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Vids	MP4	application/mp4	.mp4
Jamboard	PDF	application/pdf	.pdf

Pobierz odpowiedź

Podczas wywoływania metody download treść odpowiedzi składa się z zasobu reprezentującego długotrwałą operację. Metoda zwykle zwraca link do pobrania zawartości pliku.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Dane wyjściowe zawierają te wartości:

RESOURCE_KEY: Klucz zasobu pomaga chronić plik przed nieautoryzowanym dostępem. Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do plików na Dysku udostępnionych za pomocą linku za pomocą kluczy zasobów.
NAME: nazwa przypisana przez serwer.
DOWNLOAD_URI: końcowy identyfikator URI pobierania pliku.

Pamiętaj, że pole partialDownloadAllowed określa, czy dozwolone jest częściowe pobieranie. Wartość true, gdy pobierana jest zawartość pliku binarnego.

Sprawdzanie szczegółów długo trwającej operacji

Długotrwałe operacje to wywołania metod, których wykonanie może zająć dużo czasu. Zwykle nowo utworzone operacje pobierania są początkowo zwracane w stanie oczekiwania (done=null), zwłaszcza w przypadku plików Vids.

Aby sprawdzić stan przetwarzania LRO, możesz użyć zasobu operations udostępnianego przez interfejs Drive API. Wystarczy, że podasz unikalną nazwę przypisaną przez serwer.

Metoda get asynchronicznie pobiera najnowszy stan długotrwałej operacji. Klienci mogą używać tej metody do okresowego sprawdzania wyniku operacji w interwałach zalecanych przez usługę API.

Pobieranie informacji o długo trwającej operacji

Aby sondować dostępną operację LRO, wielokrotnie wywołuj metodę get, aż operacja się zakończy. Między kolejnymi żądaniami sprawdzania używaj wzrastającego czasu do ponowienia, np. 10 sekund.

Długotrwałe działanie pozostaje dostępne przez co najmniej 12 godzin, ale w niektórych przypadkach może trwać dłużej. Ten czas może ulec zmianie i może się różnić w zależności od typu pliku. Gdy zasób wygaśnie, konieczne będzie przesłanie nowej prośby o zastosowanie metody download.

Wszystkie żądania wysyłane do get powinny używać kluczy zasobów. Więcej informacji znajdziesz w artykule Dostęp do plików na Dysku udostępnionych za pomocą linku przy użyciu kluczy zasobów.

Protokoły żądań są widoczne tutaj.

Wywołanie metody

operations.get(name='NAME');

Zastąp NAME nazwą operacji przypisaną przez serwer, która jest widoczna w odpowiedzi na żądanie metody download.

curl

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Zastąp NAME nazwą operacji przypisaną przez serwer, która jest widoczna w odpowiedzi na żądanie metody download.

Polecenie używa ścieżki /drive/v3/operations/NAME.

Pamiętaj, że wartość name jest zwracana tylko w odpowiedzi na żądanie download. Nie ma innego sposobu na jego pobranie, ponieważ interfejs Drive API nie obsługuje metody List. Jeśli wartość name zostanie utracona, musisz wygenerować nową odpowiedź, ponownie wywołując żądanie metody download.

Odpowiedź na żądanie get składa się z zasobu reprezentującego długo trwającą operację. Więcej informacji znajdziesz w sekcji Pobieranie odpowiedzi.

Gdy odpowiedź zawiera stan ukończenia (done=true), oznacza to, że długotrwała operacja została zakończona.

Pobieranie wersji

Aby pobrać najnowszą wersję, możesz użyć wartości pola headRevisionId z zasobu files. Pobierze to wersję odpowiadającą metadanym pliku, który został wcześniej pobrany. Aby pobrać dane wszystkich poprzednich wersji pliku, które są nadal przechowywane w chmurze, możesz wywołać metodę list w zasobie revisions z parametrem fileId. Zwraca wszystkie revisionIds w pliku.

Aby pobrać treść wersji plików binarnych, musisz wywołać metodę get w zasobie revisions z identyfikatorem pliku do pobrania, identyfikatorem wersji i parametrem adresu URL alt=media. Parametr URL alt=media informuje serwer, że pobieranie treści jest żądane jako alternatywny format odpowiedzi.

Wersji plików Dokumentów, Arkuszy, Prezentacji i Vids Google nie można pobrać za pomocą metody get z adresem URL alt=media . W przeciwnym razie generuje błąd fileNotDownloadable.

Parametr adresu URL alt=media to parametr systemowy dostępny we wszystkich interfejsach API REST Google. Jeśli używasz biblioteki klienta interfejsu Drive API, nie musisz jawnie ustawiać tego parametru.

Protokół żądania jest widoczny tutaj.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Zastąp następujące elementy:

FILE_ID: fileId pliku, który chcesz pobrać.
REVISION_ID: revisionId wersji, którą chcesz pobrać.

W Dokumentach, Rysunkach i Prezentacjach Google numery wersji są zwiększane automatycznie. Jeśli jednak usuniesz wersje, w serii numerów mogą pojawić się luki, więc nie możesz polegać na kolejnych numerach, aby pobrać wersje.

Rozwiązywanie problemów z LRO

Gdy LRO zakończy się niepowodzeniem, w odpowiedzi pojawi się kanoniczny kod błędu Google Cloud.

Poniższa tabela zawiera wyjaśnienie przyczyny każdego kodu i zalecenia dotyczące jego obsługi. W przypadku wielu błędów zalecanym działaniem jest ponowienie żądania przy użyciu wzrastającego czasu do ponowienia.

Więcej informacji o tym modelu błędów i sposobie pracy z nim znajdziesz w przewodniku API Design Guide.

Kod	Typ wyliczeniowy	Opis	Zalecane działanie
1	`CANCELLED`	Operacja została anulowana, zwykle przez element wywołujący.	Uruchom operację ponownie.
2	`UNKNOWN`	Ten błąd może być zwracany, gdy wartość `Status` otrzymana z innej przestrzeni adresowej należy do przestrzeni błędów, która nie jest znana w tej przestrzeni adresowej. Jeśli błąd interfejsu API nie zwraca wystarczającej ilości informacji, może zostać przekształcony w ten błąd.	Ponów próbę ze wzrastającym czasem do ponowienia.
3	`INVALID_ARGUMENT`	Klient podał nieprawidłowy argument. Ten błąd różni się od błędu `FAILED_PRECONDITION`. `INVALID_ARGUMENT` oznacza argumenty, które są problematyczne niezależnie od stanu systemu, np. nieprawidłową nazwę pliku.	Nie próbuj ponownie bez rozwiązania problemu.
4	`DEADLINE_EXCEEDED`	Termin upłynął przed wykonaniem operacji. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wówczas, gdy operacja zakończyła się pomyślnie. Na przykład pomyślna odpowiedź serwera mogła być tak opóźniona, że termin upłynął.	Ponów próbę ze wzrastającym czasem do ponowienia.
5	`NOT_FOUND`	Nie znaleziono żądanego elementu, np. zasobu FHIR.	Nie próbuj ponownie bez rozwiązania problemu.
6	`ALREADY_EXISTS`	Encja, którą próbował utworzyć klient, np. instancja DICOM, już istnieje.	Nie próbuj ponownie bez rozwiązania problemu.
7	`PERMISSION_DENIED`	Element wywołujący nie ma uprawnień do wykonania określonej operacji. Ten kod błędu nie oznacza, że żądanie jest prawidłowe, żądany podmiot istnieje lub spełnia inne warunki wstępne.	Nie próbuj ponownie bez rozwiązania problemu.
8	`RESOURCE_EXHAUSTED`	Został wyczerpany jeden z zasobów, np. limit na projekt.	Ponów próbę ze wzrastającym czasem do ponowienia. Limit może być dostępny z czasem.
9	`FAILED_PRECONDITION`	Operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania. Na przykład katalog do usunięcia nie jest pusty lub operacja `rmdir` jest stosowana do elementu, który nie jest katalogiem.	Nie próbuj ponownie bez rozwiązania problemu.
10	`ABORTED`	Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanej kontroli sekwencera lub przerwanej transakcji.	Ponów próbę ze wzrastającym czasem do ponowienia.
11	`OUT_OF_RANGE`	Operacja została podjęta poza prawidłowym zakresem, np. wyszukiwanie lub odczytywanie poza końcem pliku. W przeciwieństwie do błędu `INVALID_ARGUMENT` ten błąd wskazuje na problem, który można rozwiązać, jeśli zmieni się stan systemu.	Nie próbuj ponownie bez rozwiązania problemu.
12	`UNIMPLEMENTED`	Operacja nie jest zaimplementowana lub nie jest obsługiwana/włączona w interfejsie Drive API.	Nie próbuj ponownie.
13	`INTERNAL`	Błędy wewnętrzne. Oznacza to, że podczas przetwarzania w systemie bazowym wystąpił nieoczekiwany błąd.	Ponów próbę ze wzrastającym czasem do ponowienia.
14	`UNAVAILABLE`	Interfejs Drive API jest niedostępny. Jest to najczęściej stan przejściowy, który można rozwiązać, ponawiając próbę ze wzrastającym czasem do ponowienia. Pamiętaj, że ponawianie operacji nieidempotentnych nie zawsze jest bezpieczne.	Ponów próbę ze wzrastającym czasem do ponowienia.
15	`DATA_LOSS`	Nieodwracalna utrata lub uszkodzenie danych.	Skontaktuj się z administratorem systemu. Jeśli doszło do utraty lub uszkodzenia danych, administrator systemu może skontaktować się z przedstawicielem zespołu pomocy.
16	`UNAUTHENTICATED`	Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji.	Nie próbuj ponownie bez rozwiązania problemu.

Pobieranie i eksportowanie plików