Zarządzaj długo trwającymi operacjami

Długotrwała operacja (LRO) to metoda interfejsu API, której wykonanie zajmuje więcej czasu niż jest to dopuszczalne w przypadku odpowiedzi interfejsu API. Zwykle nie warto trzymać otwartego wątku wywołania podczas wykonywania zadania, ponieważ nie zapewnia to użytkownikom dobrego wrażenia. Lepiej jest dać użytkownikowi pewną obietnicę i pozwolić mu na sprawdzenie ponownie później.

Interfejs Drive API zwraca LRO za każdym razem, gdy wywołujesz metodę download() zasobu 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, przeprowadzając ankietowanie operacji 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 Długotrwałe operacje.

Omówienie procesu

Na schemacie poniżej widać ogólne kroki metody file.download.

Ogólne kroki związane z metodą file.download.
Rysunek 1. Ogólne kroki związane z metodą file.download.

  1. Wywołanie files.download: gdy aplikacja wywołuje metodę download(), uruchamia żądanie pobierania pliku za pomocą interfejsu Drive API. Więcej informacji znajdziesz w artykule Pobieranie plików.

  2. Poproś o uprawnienia: żądanie wysyła dane logowania do interfejsu Drive API. Jeśli Twoja aplikacja wymaga wywołania interfejsu Drive API przy użyciu uwierzytelniania użytkownika, które nie zostało jeszcze przyznane, wyświetli użytkownikowi prośbę o zalogowanie się. Aplikacja prosi też o dostęp z użyciem zakresów określonych podczas konfigurowania uwierzytelniania.

  3. Rozpocznij pobieranie: wysyłane jest żądanie interfejsu Drive API, aby rozpocząć pobieranie pliku. Prośba może dotyczyć Google Vids lub innych treści Google Workspace.

  4. Rozpoczęcie LRO: rozpoczyna się długotrwała operacja, która zarządza procesem pobierania.

  5. Zwracanie oczekującej operacji: interfejs Drive API zwraca oczekującą operację zawierającą informacje o użytkowniku przesyłającym żądanie oraz kilka pól metadanych pliku.

  6. Początkowy stan oczekujący: aplikacja otrzymuje oczekującą operację z początkowym stanem oczekujący done=null. Oznacza to, że plik nie jest jeszcze dostępny do pobrania, a stan operacji jest oczekujący.

  7. Wywołanie operations.get i sprawdzanie wyniku: aplikacja wywołuje funkcję get() w zalecanych odstępach czasu, aby pobrać wynik operacji i uzyskać najnowszy stan długotrwałej operacji. Jeśli zwrócony zostanie stan oczekujący done=false, aplikacja musi kontynuować odczytywanie, aż operacja zwróci stan ukończony (done=true). W przypadku dużych plików odczytywanie może się odbywać wielokrotnie. Więcej informacji znajdziesz w artykule Uzyskiwanie szczegółowych informacji o długotrwałej operacji.

  8. Sprawdzanie stanu oczekujący: jeśli stan oczekujący done=true jest zwracany z LRO, oznacza to, że plik jest gotowy do pobrania, a stan operacji to „zakończona”.

  9. Zwracanie zakończonej operacji z identyfikatorem URI pobierania: gdy długotrwała operacja zostanie zakończona, interfejs Drive API zwraca identyfikator URI pobierania, a plik staje się dostępny dla użytkownika.

Pobieranie plików

Aby pobrać treści w ramach długotrwałej operacji, użyj metody download() w przypadku zasobu files. Metoda przyjmuje parametry zapytania file_id, mime_typerevision_id:

  • Wymagane. Parametr zapytania file_id to identyfikator pliku do pobrania.

  • Opcjonalnie: Parametr zapytania mime_type wskazuje typ MIME, którego powinna używać metoda. Jest ona dostępna tylko podczas pobierania treści multimedialnych innych niż blob (np. dokumentów Google Workspace). Pełną listę obsługiwanych typów MIME znajdziesz w artykule Eksportowanie typów MIME dokumentów Google Workspace.

    Jeśli typ MIME nie jest ustawiony, dokument Google Workspace jest pobierany 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 ona dostępna tylko podczas pobierania plików blob, Dokumentów i Arkuszy Google. Zwraca kod błędu INVALID_ARGUMENT podczas pobierania określonej wersji nieobsługiwanych plików.

Metoda download() to jedyny sposób na pobranie plików Vids w formacie MP4. Jest ona zwykle najlepsza do pobierania większości plików wideo.

Linki do pobrania utworzone dla Dokumentów lub Arkuszy Google początkowo przekierowują. Kliknij nowy link, aby pobrać plik.

Żądanie do metody download(), która rozpoczyna LRO, oraz żądanie do pobrania ostatecznego 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 za pomocą kluczy zasobów.

Tutaj możesz zobaczyć protokół żądania.

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

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

Domyślne typy MIME

Jeśli podczas pobierania treści innych niż blob nie jest ustawiony typ MIME, przypisywane są 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 Tekst nieprzetworzony tekst/surowy .txt
Prezentacje Google Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
Google Vids MP4 application/mp4 .mp4
Jamboard PDF application/pdf .pdf

Pobieranie odpowiedzi

Gdy wywołujesz metodę download(), treść odpowiedzi składa się z zasobu reprezentującego długotrwałą operację. Metoda zwraca zwykle 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:

Pamiętaj, że pole partialDownloadAllowed wskazuje, czy pobieranie częściowe jest dozwolone. Prawda podczas pobierania zawartości pliku blob.

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

Długotrwałe operacje to wywołania metod, które mogą zająć dużo czasu. Nowo utworzone operacje pobierania są zwykle zwracane w stanie oczekującym (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, podając unikalną nazwę przypisaną przez serwer.

Metoda get() asynchronicznie pobiera najnowszy stan długo trwającej operacji. Klienci mogą używać tej metody do sprawdzania wyniku operacji w określonych odstępach czasu zalecanych przez usługę interfejsu API.

Pobieranie stanu długo trwającej operacji

Aby odczytać dostępne LRO, wielokrotnie wywołuj metodę get(), aż operacja się zakończy. Stosuj wzrastający czas do ponowienia między każdym żądaniem sondowania, np. 10 sekund.

LRO pozostaje aktywny przez co najmniej 12 godzin, ale w niektórych przypadkach może być dostępny dłużej. Czas trwania może ulec zmianie i może się różnić w zależności od typu pliku. Po upływie ważności zasobu konieczne jest przesłanie nowej prośby o metodę download().

W przypadku żądań wysyłanych do get() należy używać kluczy zasobów. Więcej informacji znajdziesz w artykule Dostęp do plików na Dysku udostępnionych za pomocą linku za pomocą kluczy zasobów.

Tutaj znajdziesz protokoły żądań.

wywołanie metody,

operations.get(name='NAME');

Zastąp NAME nazwą przypisaną przez serwer, jaką można zobaczyć 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ą przypisaną przez serwer, jaką można zobaczyć w odpowiedzi na żądanie metody download().

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

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

Odpowiedź na żądanie get() składa się z zasobu reprezentującego długotrwałą operację. Więcej informacji znajdziesz w artykule Pobieranie odpowiedzi.

Jeśli odpowiedź zawiera stan ukończony (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 zasosobu files. W ten sposób pobierasz wersję odpowiadającą metadanym wcześniej pobranego pliku. Aby pobrać dane ze wszystkich poprzednich wersji pliku, które są nadal przechowywane w chmurze, możesz wywołać metodę list() zasobu revisions z parametrem fileId. Zwraca to wszystkie revisionIds w pliku.

Aby pobrać zawartość rewizji plików blob, musisz wywołać metodę get() zasobu revisions z identyfikatorem pliku do pobrania, identyfikatorem rewizji i parametrem URL alt=media. Parametr adresu URL alt=media informuje serwer, że żądane jest pobranie treści jako alternatywny format odpowiedzi.

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

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.

Tutaj możesz zobaczyć protokół żądania.

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ć.

Wersje Dokumentów, Rysunków i Prezentacji Google automatycznie zwiększają numery wersji. Jednak w przypadku usunięcia wersji może wystąpić luka w serii liczb, dlatego nie należy polegać na numerach sekwencyjnych podczas pobierania wersji.

Rozwiązywanie problemów z LRO

Gdy LRO zakończy się niepowodzeniem, jego odpowiedź zawiera kanoniczny kod błędu Google Cloud.

W tabeli poniżej znajdziesz wyjaśnienie przyczyny każdego kodu oraz zalecenia dotyczące postępowania. W przypadku wielu błędów zaleca się ponowne wysłanie żądania przy użyciu wzrastającego czasu do ponowienia.

Więcej informacji o tym modelu błędów i sposobie jego używania znajdziesz w przewodniku API Design Guide (w języku angielskim).

Kod Typ wyliczeniowy Opis Zalecane działanie
1 CANCELLED Operacja została anulowana, zwykle przez element wywołujący. Ponownie uruchom operację.
2 UNKNOWN Ten błąd może zostać zwrócony, gdy wartość Status otrzymana z innego obszaru adresów należy do obszaru błędów, który nie jest znany w tym obszarze adresów. Jeśli błąd interfejsu API nie zawiera wystarczającej ilości informacji, może zostać przekształcony w ten błąd. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia.
3 INVALID_ARGUMENT Klient podał nieprawidłowy argument. Ten błąd różni się od FAILED_PRECONDITION. INVALID_ARGUMENT wskazuje argumenty, które są problematyczne niezależnie od stanu systemu, np. nieprawidłowo sformułowaną nazwę pliku. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
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ął. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia.
5 NOT_FOUND Nie znaleziono żądanego elementu, np. zasobu FHIR. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
6 ALREADY_EXISTS Encja, którą próbował utworzyć klient, np. instancja DICOM, już istnieje. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
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, że żądany element istnieje lub że spełnia inne warunki wstępne. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
8 RESOURCE_EXHAUSTED Niektóre zasoby zostały wyczerpane, np. limit na projekt. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia. Limit może stać się 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, który ma zostać usunięty, nie jest pusty lub operacja rmdir jest stosowana do elementu, który nie jest katalogiem. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
10 ABORTED Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanej kontroli sekwencera lub przerwanej transakcji. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia.
11 OUT_OF_RANGE Operacja została podjęta poza prawidłowym zakresem, np. przewijanie lub odczyt poza końcem pliku. W przeciwieństwie do błędu INVALID_ARGUMENT ten błąd wskazuje problem, który można rozwiązać, zmieniając stan systemu. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
12 UNIMPLEMENTED Operacja nie jest zaimplementowana lub nie jest obsługiwana/włączona w Drive API. Nie próbuj ponownie.
13 INTERNAL Błędy wewnętrzne. Wskazuje na nieoczekiwany błąd, który wystąpił podczas przetwarzania w podstawowym systemie. Podejmuje ponowne próby 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ę z wzrastającym czasem do ponowienia. Pamiętaj, że ponowne próby wykonywania operacji nie idempotentnych nie zawsze są bezpieczne. Podejmuje ponowne próby ze wzrastającym czasem do ponowienia.
15 DATA_LOSS Nieodwracalna utrata danych lub ich uszkodzenie. Skontaktuj się z administratorem systemu. W przypadku 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, jeśli problem nie został rozwiązany.