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 widać ogólne kroki działania metody file.download.

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

2. Żądanie uprawnień: żądanie wysyła dane uwierzytelniające 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.

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

4. Uruchomienie LRO: rozpoczyna się długo trwająca operacja, która zarządza procesem pobierania.

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

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

7. Wywołaj operations.get i sprawdź wynik: aplikacja wywołuje get w zalecanych odstępach czasu, aby sprawdzać wynik operacji i pobierać 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.

8. Sprawdź stan oczekiwania: jeśli z długotrwałej operacji zostanie zwrócony stan oczekiwania done=true, oznacza to, że plik jest gotowy do pobrania, a stan operacji to „ukończono”.

9. 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 file_id, mime_type i revision_id:

• Wymagane. Parametr ścieżki 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ż blob (np. dokumentów 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 metody download, która 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:

Pobieranie odpowiedzi

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, i ma wartość true podczas pobierania zawartości 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ługo trwającej operacji. Klienci mogą używać tej metody do 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ła operacja pozostaje dostępna przez co najmniej 12 godzin, ale w niektórych przypadkach może być dostępna 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.

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 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ługo trwająca operacja została zakończona.

Pobieranie wersji

Aby pobrać najnowszą wersję, możesz użyć wartości pola headRevisionId z zasobu files. Spowoduje to pobranie wersji odpowiadającej 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 z 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.

W tabeli poniżej znajdziesz poszczególne kody błędów, odpowiadające im kody stanu HTTP, opis oraz zalecenia dotyczące obsługi kodu błędu. W przypadku wielu błędów zalecane działanie to ponowienie próby wysłania żą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.

Powiązane artykuły

• Pobieranie i eksportowanie plików