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 komfort użytkowania. Zamiast tego lepiej jest zwrócić użytkownikowi obietnicę i pozwolić mu na sprawdzenie stanu później.

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

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

Więcej informacji znajdziesz w artykule Długo trwające operacje.

Omówienie procesu

Poniższy schemat przedstawia najważniejsze kroki działania metody file.download.

1. Wywołanie metody files.download: gdy aplikacja wywoła metodę download, uruchomi żądanie pobrania pliku z interfejsu Drive API. Więcej informacji znajdziesz w sekcji Pobieranie plików.

2. Żądanie uprawnień: żądanie wysyła dane uwierzytelniające do interfejsu Drive API. Jeśli Twoja aplikacja wymaga wywołania interfejsu Drive API przy użyciu uwierzytelnienia użytkownika, które nie zostało jeszcze przyznane, wyświetli się prośba o zalogowanie. Aplikacja poprosi też o dostęp z zakresami, które określisz podczas konfigurowania uwierzytelniania.

3. Rozpoczęcie pobierania: wysyłane jest żądanie do interfejsu Drive API, aby rozpocząć pobieranie pliku. Żądanie może zostać wysłane do Google Vids lub innej treści Google Workspace.

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

5. Zwrócenie operacji w stanie oczekiwania: interfejs Drive API zwraca operację w stanie oczekiwania, która zawiera informacje o użytkowniku wysyłającym żądanie oraz kilka pól metadanych pliku.

6. Początkowy stan oczekiwania: aplikacja otrzymuje operację w stanie oczekiwania 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łanie metody operations.get i sprawdzenie wyniku: aplikacja wywołuje metodę get w zalecanych odstępach czasu, aby sprawdzić wynik operacji i uzyskać najnowszy stan długo trwającej operacji. Jeśli zostanie zwrócony stan oczekiwania done=false, aplikacja musi kontynuować sprawdzanie stanu, dopóki operacja nie zwróci stanu ukończenia (done=true). W przypadku dużych plików należy spodziewać się wielokrotnego sprawdzania stanu. Więcej informacji znajdziesz w sekcji Sprawdzanie szczegółów długo trwającej operacji.

8. Sprawdzenie stanu oczekiwania: jeśli LRO zwróci stan oczekiwania done=true, oznacza to, że plik jest gotowy do pobrania, a stan operacji to „ukończono”.

9. Zwrócenie ukończonej operacji z identyfikatorem URI pobierania: po zakończeniu LRO 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ługo trwającej 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 określa typ MIME, którego powinna używać metoda. Jest dostępny tylko podczas pobierania treści multimedialnych innych niż blob (np. dokumentów Google Workspace). Pełną listę obsługiwanych typów MIME znajdziesz w sekcji Typy MIME eksportu dokumentów Google Workspace.

  Jeśli typ MIME nie jest ustawiony, dokument Google Workspace zostanie pobrany z domyślnym typem MIME. Więcej informacji znajdziesz w sekcji Domyślne typy MIME.

• Opcjonalnie. Parametr zapytania revision_id to identyfikator wersji pliku do pobrania. Jest dostępny tylko podczas pobierania plików blob, Dokumentów Google i Arkuszy Google. Podczas pobierania określonej wersji nieobsługiwanych plików zwraca kod błędu INVALID_ARGUMENT.

Metoda download to jedyny sposób na pobieranie plików Vids w formacie MP4. Zwykle najlepiej nadaje się do pobierania większości plików wideo. Jeśli spróbujesz wyeksportować pliki Google Vids, otrzymasz błąd fileNotExportable.

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

Żą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 sekcji Uzyskiwanie dostępu 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 ciąg 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:

Pobierz odpowiedź

Podczas wywoływania metody download treść odpowiedzi składa się z zasobu reprezentującego długo trwającą 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 sekcji Uzyskiwanie dostępu do plików na Dysku udostępnionych za pomocą linku przy użyciu kluczy zasobów.

• NAME: nazwa przypisana przez serwer.

• DOWNLOAD_URI: końcowy identyfikator URI pobierania pliku.

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

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

Długo trwające operacje to wywołania metod, których wykonanie może zająć sporo 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, 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 interwałach zalecanych przez usługę API.

Sprawdzanie stanu długo trwającej operacji

Aby sprawdzić stan dostępnej LRO, wielokrotnie wywołuj metodę get, dopóki operacja się nie zakończy. Między kolejnymi żądaniami sprawdzania stanu używaj wzrastającego czasu do ponowienia, np. 10 sekund.

LRO 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 się zmienić i różnić w zależności od typu pliku. Po wygaśnięciu zasobu konieczne jest nowe żądanie metody download.

Wszystkie żądania get powinny używać kluczy zasobów. Więcej informacji znajdziesz w sekcji Uzyskiwanie dostępu 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 name jest zwracana tylko w odpowiedzi na żądanie download. Nie ma innego sposobu na jej 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 Pobierz odpowiedź.

Gdy odpowiedź zawiera stan ukończenia (done=true), 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óre zostały wcześniej pobrane. 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. Spowoduje to zwrócenie wszystkich wartości revisionIds w pliku.

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

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

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

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

Wersje Dokumentów, Rysunków i Prezentacji Google automatycznie zwiększają numery wersji. Jeśli jednak wersje zostaną usunięte, w serii liczb mogą występować luki, dlatego nie należy polegać na kolejnych numerach podczas pobierania wersji.

Rozwiązywanie problemów z LRO

Gdy LRO się nie powiedzie, odpowiedź zawiera kanoniczny kod błędu Google Cloud.

W tabeli poniżej znajdziesz każdy kod błędu, odpowiadający mu kod stanu HTTP, opis i zalecenia dotyczące obsługi kodu błędu. W przypadku wielu błędów zalecane działanie to ponowienie żądania ze wzrastającym czasem 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