Uzun süreli işlemleri yönetme

Uzun süreli işlem (LRO), tamamlanması API yanıtı için uygun olandan 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 eşzamansız 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. Beklemede durumu (done=false) döndürülürse uygulamanız, işlem tamamlandı durumunu (done=true) döndürene kadar sorgulamaya devam etmelidir. Büyük dosyalar için birden fazla kez sorgu yapmanız gerekebilir. 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 edin: LRO'dan done=true için bekleme durumu döndürülürse 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. Bu özellik 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 başlıklı makaleyi inceleyin.

• İ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 dosyalarda belirli bir düzeltme indirilirken INVALID_ARGUMENT hata kodu döndürülü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ı indirme

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 indirme işlemine 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. Yeni oluşturulan indirme işlemleri genellikle başlangıçta beklemede durumunda (done=null) döndürülür. Bu durum özellikle Vids dosyaları için geçerlidir.

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 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şlemi sorgulayı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 daha uzun süre devam edebilir. Bu süre değişebilir ve dosya türleri arasında farklılık gösterebilir. Kaynak süresinin dolmasından sonra yeni bir download() yöntem isteği gerekir.

get() adresine yapılan tüm isteklerde kaynak anahtarları kullanılmalı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österilir.

operations.get(name='NAME');

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

name değerinin yalnızca download() isteğinin yanıtında döndürüldüğünü unutmayın. Drive API, List() yöntemini desteklemediğinden bu değeri başka bir şekilde alamazsınız. 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 revisions kaynağında get() yöntemini indirilecek dosyanın kimliği, düzeltmenin kimliği ve alt=media URL parametresini belirterek ç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 Vids için 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ça 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 ve kodun nasıl ele alınacağına dair öneriler 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