Uzun süreli işlemleri yönetme

Uzun süren işlem (LRO), tamamlanması API yanıtına göre daha uzun süren bir API yöntemidir. Görev çalışırken çağıran ileti dizisini açık tutmak genellikle kötü bir kullanıcı deneyimi sunacağından istenmez. Bunun yerine, kullanıcıya bir tür söz verip daha sonra tekrar kontrol etmesine izin vermek daha iyidir.

Google Drive API, bir dosyanın içeriğini Drive API veya içerik kitaplıkları aracılığıyla indirmek için files kaynağında download() yöntemini her çağırdığınızda bir LRO döndürür.

Yöntem, istemciye bir operations kaynağı döndürür. get() yöntemi aracılığıyla işlemi sorgulayarak API yönteminin durumunu asynkron olarak almak için operations kaynağını kullanabilirsiniz. Drive API'deki LRO'lar Google Cloud LRO tasarım kalıbına uyar.

Daha fazla bilgi için Uzun süren işlemler konusuna bakın.

İşleme genel bakış

Aşağıdaki şemada, file.download yönteminin işleyiş şeklinin üst düzey adımları gösterilmektedir.

1. files.download çağrısı: Uygulamanız download() yöntemini çağrdığında dosya için Drive API indirme isteği başlatır. Daha fazla bilgi için Dosya indirme başlıklı makaleyi inceleyin.

2. İzin iste: İstek, Drive API'ye kimlik doğrulama kimlik bilgilerini gönderir. Uygulamanız, henüz verilmemiş bir kullanıcı kimlik doğrulamasını kullanarak Drive API'yi çağırmayı gerektiriyorsa kullanıcıdan oturum açmasını ister. Uygulamanız, kimlik doğrulamayı ayarlarken belirttiğiniz kapsamlarla da erişim ister.

3. İndiremeyi başlat: Dosya indirme işlemini başlatmak için bir Drive API isteği gönderilir. İstek, Google Vids veya başka bir Google Workspace içeriği için gönderilebilir.

4. LRO'yu başlat: İndirme işlemini yöneten uzun süreli bir işlem başlar.

5. Beklemede olan işlemi döndürme: Drive API, isteği gönderen kullanıcı ve çeşitli dosya meta veri alanları hakkında bilgi içeren beklemede olan bir işlem döndürür.

6. İlk bekleme durumu: Uygulamanız, bekleme işlemini done=null ilk bekleme durumuyla birlikte alır. Bu, dosyanın henüz indirilmeye hazır olmadığını ve işlem durumunun beklemede olduğunu gösterir.

7. operations.get'ı çağırıp sonucu doğrulama: Uygulamanız, işlem sonucunu sorgulamak ve uzun süredir çalışan bir işlemin son durumunu almak için önerilen aralıklarla get()'ı çağırır. done=false bekleme durumu döndürülürse uygulamanız, işlem tamamlandı durumuna (done=true) dönene kadar yoklamaya devam etmelidir. Büyük dosyalarda birden çok kez yoklama yapabilirsiniz. Daha fazla bilgi için Uzun süren bir işlemle ilgili ayrıntıları alma başlıklı makaleyi inceleyin.

8. Bekleme durumunu kontrol et: LRO'dan done=true bekleme durumu döndürülürse bu, dosyanın indirilmeye hazır olduğu ve işlem durumunun tamamlandığı anlamına gelir.

9. Tamamlanan işlemi indirme URI'siyle döndürme: LRO tamamlandığında Drive API, indirme URI'sini döndürür ve dosya artık kullanıcı tarafından kullanılabilir.

Dosyaları indir

Uzun süren bir işlem sırasında içerik indirmek için files kaynağındaki download() yöntemini kullanın. Yöntem, file_id, mime_type ve revision_id sorgu parametrelerini alır:

• Zorunlu. file_id sorgu parametresi, indirilecek dosyanın kimliğidir.

• İsteğe bağlı. mime_type sorgu parametresi, yöntemin kullanması gereken MIME türünü belirtir. Yalnızca blob olmayan medya içerikleri (ör. Google Workspace dokümanları) indirirken kullanılabilir. Desteklenen MIME türlerinin tam listesi için Google Workspace belgeleri için MIME türlerini dışa aktarma başlıklı makaleyi inceleyin.

  MIME türü ayarlanmamışsa Google Workspace dokümanı varsayılan MIME türüyle indirilir. Daha fazla bilgi için Varsayılan MIME türleri bölümüne bakın.

• İsteğe bağlı. revision_id sorgu parametresi, indirilecek dosyanın düzeltme kimliğidir. Bu özellik yalnızca blob dosyaları, Google Dokümanlar ve Google E-Tablolar'ı indirirken kullanılabilir. Desteklenmeyen dosyalardaki belirli bir düzeltmeyi indirirken INVALID_ARGUMENT hata kodunu döndürür.

download() yöntemi, Vids dosyalarını MP4 biçiminde indirmenin tek yoludur ve genellikle çoğu video dosyasını indirmek için en uygun yöntemdir.

Google Dokümanlar veya E-Tablolar için oluşturulan indirme bağlantıları başlangıçta yönlendirme döndürür. Dosyayı indirmek için yeni bağlantıyı tıklayın.

LRO'yu başlatan download() yöntemine gönderilen istek ve nihai indirme URI'sini getirme isteği, kaynak anahtarları kullanmalıdır. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantıyla paylaşılan Drive dosyalarına erişme başlıklı makaleyi inceleyin.

İstek protokolü burada gösterilir.

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

FILE_ID yerine, indirmek istediğiniz dosyanın fileId değerini yazın.

Varsayılan MIME türleri

Blob olmayan içerikler indirilirken bir MIME türü ayarlanmazsa aşağıdaki varsayılan MIME türleri atanır:

Yanıtı indirin

download() yöntemi çağrılırken yanıt gövdesi, uzun süreli bir işlemi temsil eden bir kaynaktan oluşur. Yöntem genellikle dosya içeriğini indirmek için bir bağlantı döndürür.

{
  "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
  }
}

Bu çıkış aşağıdaki değerleri içerir:

• RESOURCE_KEY: Kaynak anahtarı, dosyanızın istenmeyen erişime karşı korunmasına yardımcı olur. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantıyla paylaşılan Drive dosyalarına erişme başlıklı makaleyi inceleyin.

• NAME: Sunucu tarafından atanan ad.

• DOWNLOAD_URI: Dosyanın nihai indirme URI'si.

partialDownloadAllowed alanının, kısmi indirmeye izin verilip verilmediğini belirttiğini unutmayın. Blob dosyası içeriği indirilirken doğru değerini döndürür.

Uzun süren bir işlemle ilgili ayrıntıları alma

Uzun süreli işlemler, tamamlanması çok uzun sürebilecek yöntem çağrılarıdır. Genellikle yeni oluşturulan indirme işlemleri, özellikle Vids dosyaları için başlangıçta bekleme durumunda (done=null) döndürülür.

Sunucu tarafından atanan benzersiz adı ekleyerek işlenen LRO'nun durumunu kontrol etmek için Drive API'nin sağladığı operations kaynağını kullanabilirsiniz.

get() yöntemi, uzun süreli bir işlemin en son durumunu eşzamansız olarak alır. İstemciler, API hizmeti tarafından önerilen aralıklarla işlem sonucunu yoklamak için bu yöntemi kullanabilir.

Uzun süreli bir işlemde anket yapın

Mevcut bir LRO'yu yoklamak için işlem tamamlanana kadar get() yöntemini tekrar tekrar çağırın. Her anket isteği arasında 10 saniye gibi bir eksponansiyel geri yükleme kullanın.

LRO en az 12 saat boyunca kullanılabilir ancak bazı durumlarda bu süre daha uzun olabilir. Bu süre değişebilir ve dosya türleri arasında farklılık gösterebilir. Kaynağın süresi dolduğunda yeni bir download() yöntemi isteği gerekir.

get() için yapılan tüm istekler kaynak anahtarlarını kullanmalıdır. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantıyla paylaşılan Drive dosyalarına erişme başlıklı makaleyi inceleyin.

İstek protokolleri burada gösterilmektedir.

operations.get(name='NAME');

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

name öğesinin yalnızca download() isteğine yanıt olarak döndürüldüğünü unutmayın. Drive API, List() yöntemini desteklemediğinden bu verileri almanın başka bir yolu yoktur. name değeri kaybolursa download() yöntem isteğini tekrar çağırarak yeni bir yanıt oluşturmanız gerekir.

get() isteğinin yanıtı, uzun süreli bir işlemi temsil eden bir kaynaktan oluşur. Daha fazla bilgi için Yanıtı indirme başlıklı makaleyi inceleyin.

Yanıt tamamlandı durumunu (done=true) içeriyorsa uzun süren işlem tamamlanmıştır.

Düzeltmeyi indirme

En son düzeltmeyi indirmek için files kaynağındaki headRevisionId alanının değerini kullanabilirsiniz. Bu işlem, daha önce aldığınız dosyanın meta verilerine karşılık gelen düzeltmeyi getirir. Dosyanın hâlâ bulutta depolanan önceki tüm düzenlemelerine ait verileri indirmek için revisions kaynağındaki list() yöntemini fileId parametresiyle çağırabilirsiniz. Bu işlem, dosyadaki tüm revisionIds öğelerini döndürür.

Blob dosyalarının düzeltme içeriğini indirmek için indirilecek dosyanın kimliği, düzeltmenin kimliği ve alt=media URL parametresiyle birlikte revisions kaynağında get() yöntemini çağırmanız gerekir. alt=media URL parametresi, sunucuya alternatif yanıt biçimi olarak içerik indirme isteğinde bulunulduğunu bildirir.

Google Dokümanlar, E-Tablolar, Slaytlar ve videolardaki düzeltmeler, alt=media URL'si ile get() yöntemi kullanılarak indirilemez . Aksi takdirde fileNotDownloadable hatası oluşur.

alt=media URL parametresi, tüm Google REST API'lerinde kullanılabilen bir sistem parametresidir. Drive API için bir istemci kitaplığı kullanıyorsanız bu parametreyi açık bir şekilde ayarlamanız gerekmez.

İstek protokolü burada gösterilir.

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

Aşağıdakini değiştirin:

• FILE_ID: İndirmek istediğiniz dosyanın fileId.
• REVISION_ID: İndirmek istediğiniz düzeltmenin revisionId.

Google Dokümanlar, Çizimler ve Slaytlar'daki düzeltmelerde düzeltme numaraları otomatik olarak artar. Ancak revizyonlar silinirse sayı dizisinde boşluklar olabilir. Bu nedenle, revizyonları almak için sıralı sayılara güvenmemelisiniz.

LRO'larla ilgili sorunları giderme

LRO başarısız olduğunda yanıtında kanonik bir Google Cloud hata kodu bulunur.

Aşağıdaki tabloda, her bir kodun nedeni hakkında açıklama ve kodun nasıl kullanılacağına dair bir öneri verilmiştir. Birçok hata için önerilen işlem, eksponansiyel geri yükleme kullanarak isteği tekrar denemektir.

Bu hata modeli ve bu modelle çalışma hakkında daha fazla bilgiyi API Tasarım Kılavuzu'nda bulabilirsiniz.

İlgili konular

• Dosya indirme ve dışa aktarma
• Dosya düzeltmelerini yönetme