Uzun süreli işlem (LRO), bir API yanıtı için uygun olandan daha uzun süren bir API yöntemidir. Genellikle, görev çalışırken arama iş parçacığını açık tutmak istemezsiniz. Bu, kötü bir kullanıcı deneyimi sunar. Bunun yerine, kullanıcıya bir tür söz vermek ve daha sonra tekrar kontrol etmesine izin vermek daha iyidir.
Google Drive API, bir dosyanın içeriğini Drive API veya istemci 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öntemiyle işlemi yoklayarak 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
modeline uygundur.
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.
Çağrı
files.download: Uygulamanızdownloadyöntemini çağırdığında dosya için Drive API indirme isteğini başlatır. Daha fazla bilgi için Dosya indirme başlıklı makaleyi inceleyin.İzin iste: İstek, kimlik doğrulama kimlik bilgilerini Drive API'ye gönderir. Uygulamanızın, henüz verilmemiş bir kullanıcı kimlik doğrulaması kullanılarak Drive API'nin çağrılması gerekiyorsa kullanıcıdan oturum açması istenir. Uygulamanız, kimlik doğrulama ayarlarını yaparken belirttiğiniz kapsamlarla erişim de istiyor.
İndirmeyi başlatma: Dosya indirme işlemini başlatmak için Drive API isteği gönderilir. İstek, Google Vids'e veya başka bir Google Workspace içeriğine yönelik olabilir.
LRO'yu başlatma: Uzun süreli bir işlem başlar ve indirme sürecini yönetir.
Bekleyen işlemi döndürme: Drive API, isteği gönderen kullanıcı ve çeşitli dosya meta verileri alanları hakkında bilgi içeren bekleyen bir işlem döndürür.
İlk bekleme durumu: Uygulamanız, bekleyen işlemi
done=nullilk bekleme durumuyla birlikte alır. Bu, dosyanın henüz indirilmeye hazır olmadığını ve işlem durumunun beklemede olduğunu gösterir.operations.getişlevini çağırın ve sonucu doğrulayın: Uygulamanız, işlem sonucunu yoklamak ve uzun süren bir işlemin en son durumunu almak içingetişlevini önerilen aralıklarla çağırır.done=false'nın beklemede durumu döndürülürse uygulamanız, işlem tamamlandı durumunu (done=true) döndürene kadar yoklama yapmaya devam etmelidir. Büyük dosyalar için birden çok kez yoklama yapmanız gerekir. Daha fazla bilgi için Uzun süren bir işlemle ilgili ayrıntıları alma başlıklı makaleyi inceleyin.Beklemede durumunu kontrol edin: LRO'dan
done=truebeklemede durumu döndürülürse bu, dosyanın indirilmeye hazır olduğunu ve işlem durumunun tamamlandığını gösterir.İndirme URI'si ile tamamlanan işlemi döndürme: LRO tamamlandıktan sonra Drive API, indirme URI'sini döndürür ve dosya kullanıcı tarafından kullanılabilir.
Dosyaları indir
Uzun süren bir işlem kapsamında içerik indirmek için download yöntemini files kaynağında kullanın. Yöntem, file_id, mime_type ve revision_id sorgu parametrelerini alır:
Zorunlu.
file_idsorgu parametresi, indirilecek dosyanın kimliğidir.İsteğe bağlı.
mime_typesorgu parametresi, yöntemin kullanması gereken MIME türünü belirtir. Bu özellik yalnızca blob olmayan medya içerikleri (ör. Google Workspace dokümanları) indirilirken kullanılabilir. Desteklenen MIME türlerinin tam listesi için Google Workspace dokümanları 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_idsorgu 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 indirilirkenINVALID_ARGUMENThata 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.
Başlangıçta Google Dokümanlar veya E-Tablolar için oluşturulan indirme bağlantıları yönlendirme döndürür. Dosyayı indirmek için yeni bağlantıyı tıklayın.
LRO'yu başlatan download yöntemine yapılan istek ve nihai indirme URI'sini getirme isteği için kaynak anahtarları kullanılmalıdır. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantı ile 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}/downloadFILE_ID yerine, indirmek istediğiniz dosyanın fileId değerini girin.
Varsayılan MIME türleri
Blob olmayan içerik indirilirken bir MIME türü ayarlanmazsa aşağıdaki varsayılan MIME türleri atanır:
| Belge Türü | Biçim | MIME türü | Dosya uzantısı |
|---|---|---|---|
| Google Apps Komut Dosyası | JSON | application/vnd.google-apps.script+json | .json |
| Google Dokümanlar | Microsoft Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| Google Çizimler | PNG | image/png | .png |
| Google Forms | ZIP | application/zip | .zip |
| Google E-Tablolar | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google Sites | Ham Metin | text/raw | .txt |
| Google Slaytlar | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
Yanıtı indirme
download yöntemi çağrıldığında yanıt gövdesi, uzun süreli bir işlemi temsil eden bir kaynaktan oluşur. Bu yöntem genellikle dosya içeriklerini 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ı istenmeyen erişime karşı korur. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantı ile 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 gösterdiğini unutmayın. Blob dosyası içeriği indirilirken doğru olur.
Uzun süren bir işlemle ilgili ayrıntıları alma
Uzun süreli işlemler, tamamlanması önemli ölçüde zaman alabilen yöntem çağrılarıdır. Genellikle, yeni oluşturulan indirme işlemleri başlangıçta beklemede (done=null) durumunda döndürülür. Bu durum özellikle Vids dosyaları için geçerlidir.
Sunucu tarafından atanan benzersiz adı ekleyerek uzun süren işlem (LRO) işlemenin durumunu kontrol etmek için Drive API'nin sağladığı operations kaynağını kullanabilirsiniz.
get yöntemi, uzun süren bir işlemin en son durumunu eşzamansız olarak alır. Müşteriler, API hizmetinin önerdiği aralıklarla işlem sonucunu yoklamak için bu yöntemi kullanabilir.
Uzun süreli bir işlemi sorgulama
Kullanılabilir bir LRO'yu yoklamak için işlem tamamlanana kadar get yöntemini tekrar tekrar çağırın.
Her bir yoklama isteği arasında eksponansiyel geri yükleme kullanın (ör. 10 saniye).
Uzun süreli işlem, 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. Kaynağın süresi dolduğunda yeni bir download yöntemi isteği gerekir.
get için yapılan tüm isteklerde kaynak anahtarları kullanılmalıdır. Daha fazla bilgi için Kaynak anahtarlarını kullanarak bağlantı ile paylaşılan Drive dosyalarına erişme başlıklı makaleyi inceleyin.
İstek protokolleri burada gösterilmektedir.
Yöntem çağrısı
operations.get(name='NAME');
NAME yöntem isteğine verilen yanıtta gösterildiği gibi NAME ifadesini işlemin sunucu tarafından atanan adıyla değiştirin.download
curl
curl -i -H \
'Authorization: Bearer $(gcloud auth print-access-token)" \
'https://googleapis.com/drive/v3/operations/NAME?alt=json'
NAME yöntem isteğine verilen yanıtta gösterildiği gibi NAME ifadesini işlemin sunucu tarafından atanan adıyla değiştirin.download
Komut, /drive/v3/operations/NAME yolunu kullanıyor.
name öğesinin yalnızca download isteğine verilen yanıtta döndürüldüğünü unutmayın.
Drive API, List yöntemini desteklemediğinden bu dosyayı 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ğinden gelen 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 tamamlanmış bir durumu (done=true) içerdiğinde uzun süren işlem tamamlanmıştır.
Düzeltme 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 bulutta depolanmaya devam eden tüm önceki düzeltmelerine ait verileri indirmek için fileId parametresiyle revisions kaynağında list yöntemini çağırabilirsiniz. Bu işlev, dosyadaki tüm revisionIds değerlerini döndürür.
Blob dosyalarının düzeltme içeriğini indirmek için get yöntemini, indirilecek dosyanın kimliği, düzeltmenin kimliği ve alt=media URL parametresiyle birlikte revisions kaynağında ç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'deki düzeltmeler, get yöntemiyle alt=media URL'si kullanılarak indirilemez . Aksi takdirde fileNotDownloadable hatası oluşturulur.
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=mediaAş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 artırılır. Ancak revizyonlar silinirse sayı dizisinde boşluklar olabilir. Bu nedenle, revizyonları almak için sıralı sayılara güvenmemelisiniz.
Uzun süreli işlemlerle ilgili sorunları giderme
Uzun süreli işlem başarısız olduğunda yanıtında standart bir Google Cloud hata kodu yer alır.
Aşağıdaki tabloda, her kodun nedenine ilişkin açıklama ve kodu nasıl işleyeceğinize dair öneri yer almaktadır. Birçok hata için önerilen işlem, eksponansiyel geri yükleme kullanarak isteği tekrar denemektir.
Bu hata modeli ve bununla nasıl çalışılacağı hakkında daha fazla bilgiyi API Tasarım Kılavuzu'nda bulabilirsiniz.
| Kod | Enum | Açıklama | Önerilen işlem |
|---|---|---|---|
| 1 | CANCELLED |
İşlem genellikle arayan tarafından iptal edildi. | İşlemi yeniden çalıştırın. |
| 2 | UNKNOWN |
Bu hata, başka bir adres alanından alınan Status değeri, bu adres alanında bilinmeyen bir hata alanına ait olduğunda döndürülebilir. API hatası yeterli bilgiyi döndürmezse hata bu hataya dönüştürülebilir. |
Eksponansiyel geri yüklemeyle yeniden deneyin. |
| 3 | INVALID_ARGUMENT |
İstemci, geçersiz bir bağımsız değişken belirtti. Bu hata, FAILED_PRECONDITION hatasından farklıdır. INVALID_ARGUMENT, sistemin durumundan bağımsız olarak sorunlu olan bağımsız değişkenleri (ör. hatalı biçimlendirilmiş bir dosya adı) gösterir. |
Sorunu düzeltmeden tekrar denemeyin. |
| 4 | DEADLINE_EXCEEDED |
İşlem tamamlanmadan son tarih geçti. Sistemin durumunu değiştiren işlemler için, işlem başarıyla tamamlanmış olsa bile bu hata döndürülebilir. Örneğin, bir sunucudan gelen başarılı yanıt, son kullanma tarihinin geçmesine yetecek kadar uzun süre gecikmiş olabilir. | Eksponansiyel geri yüklemeyle yeniden deneyin. |
| 5 | NOT_FOUND |
İstenen bazı varlıklar (ör. FHIR kaynağı) bulunamadı. | Sorunu düzeltmeden tekrar denemeyin. |
| 6 | ALREADY_EXISTS |
Bir istemcinin oluşturmaya çalıştığı varlık (ör. DICOM örneği) zaten mevcut. | Sorunu düzeltmeden tekrar denemeyin. |
| 7 | PERMISSION_DENIED |
Arayan kullanıcının belirtilen işlemi gerçekleştirme izni yok. Bu hata kodu, isteğin geçerli olduğunu, istenen öğenin mevcut olduğunu veya diğer ön koşulları karşıladığını göstermez. | Sorunu düzeltmeden tekrar denemeyin. |
| 8 | RESOURCE_EXHAUSTED |
Proje başına kota gibi bazı kaynaklar tükendi. | Eksponansiyel geri yüklemeyle yeniden deneyin. Kota zamanla kullanılabilir hale gelebilir. |
| 9 | FAILED_PRECONDITION |
Sistem, işlemin yürütülmesi için gerekli durumda olmadığından işlem reddedildi. Örneğin, silinecek dizin boş değildir veya dizin olmayan bir öğeye rmdir işlemi uygulanmıştır. |
Sorunu düzeltmeden tekrar denemeyin. |
| 10 | ABORTED |
İşlem, genellikle sıralayıcı kontrolü hatası veya işlem iptali gibi eşzamanlılık sorunu nedeniyle iptal edildi. | Eksponansiyel geri yüklemeyle yeniden deneyin. |
| 11 | OUT_OF_RANGE |
İşlem, geçerli aralığın dışında denenmiştir (ör. dosya sonunun ötesinde arama veya okuma). INVALID_ARGUMENT hatasının aksine bu hata, sistem durumu değiştiğinde düzeltilebilecek bir sorunu gösterir. |
Sorunu düzeltmeden tekrar denemeyin. |
| 12 | UNIMPLEMENTED |
İşlem uygulanmamış veya Drive API'de desteklenmiyor/etkinleştirilmemiş. | Tekrar denemeyin. |
| 13 | INTERNAL |
Dahili hatalar. Bu, temel sistemdeki işleme sırasında beklenmeyen bir hatayla karşılaşıldığını gösterir. | Eksponansiyel geri yüklemeyle yeniden deneyin. |
| 14 | UNAVAILABLE |
Drive API kullanılamıyor. Bu durum büyük olasılıkla geçicidir ve eksponansiyel geri yüklemeyle yeniden deneme yapılarak düzeltilebilir. İdempotent olmayan işlemleri yeniden denemenin her zaman güvenli olmadığını unutmayın. | Eksponansiyel geri yüklemeyle yeniden deneyin. |
| 15 | DATA_LOSS |
Kurtarılamaz veri kaybı veya bozulması. | Sistem yöneticinizle iletişime geçin. Veri kaybı veya bozulması durumunda sistem yöneticisi bir destek temsilcisiyle iletişime geçebilir. |
| 16 | UNAUTHENTICATED |
İstekte işlemle ilgili geçerli kimlik doğrulama bilgileri bulunmuyor. | Sorunu düzeltmeden tekrar denemeyin. |