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 dobrego wrażenia użytkownika. 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.

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 zostanie zwrócony 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_type i revision_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:

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:

• RESOURCE_KEY: klucz zasobu pomaga chronić plik przed nieuprawnionym 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: ostateczny identyfikator URI pliku do pobrania.

Pamiętaj, że pole partialDownloadAllowed wskazuje, czy dozwolone jest częściowe pobieranie. 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. Zwykle nowo utworzone operacje pobierania są 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 kolejnymi żądaniami 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ń.

operations.get(name='NAME');

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

Pamiętaj, że name jest zwracany tylko w odpowiedzi na żądanie download(). Nie ma innego sposobu na pobranie 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).

Powiązane artykuły

• Pobieranie i eksportowanie plików
• Zarządzanie wersjami plików