Devam ettirilebilir yüklemeler

Bu sayfada, REST protokolü aracılığıyla Google Photos Library API'ye nasıl devam ettirilebilir yükleme isteğinde bulunulacağı açıklanmaktadır. Bu protokol, bir iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemini devam ettirmenize olanak tanır.

İstemci kitaplıklarını kullanan bir geliştiriciyseniz bazı istemci kitaplıklarının devam ettirilebilir yüklemeler için yerel destek sağladığını unutmayın.

Aşağıdaki durumlarda devam ettirilebilir yükleme seçeneğini kullanın:

  • Büyük dosyalar yüklüyorsunuz.
  • Ağ kesintisi veya başka bir iletim hatası olasılığı yüksektir (örneğin, mobil uygulamadan dosya yüklüyorsanız).

Devam ettirilebilir yüklemeler, ağ hatası olduğunda bant genişliği kullanımınızı da azaltabilir. Çünkü büyük boyutlu dosya yüklemelerini baştan başlatmak zorunda kalmazsınız.

1. Adım: Yükleme oturumu başlatma

https://photoslibrary.googleapis.com/v1/uploads adresine POST isteği göndererek devam ettirilebilir bir yükleme oturumu başlatın. Bu istekte döndürülen devam ettirilebilir yükleme URL'sini kullanarak dosyayı yükleyin.

POST isteği aşağıdaki üstbilgileri içermelidir:

Başlık alanları
Content-Length İstek gövdesi boş olduğundan 0 değerine ayarlayın.
X-Goog-Upload-Command start olarak ayarlayın.
X-Goog-Upload-Content-Type Dosyanın MIME türüne ayarlayın, örneğin, image/jpeg.
X-Goog-Upload-Protocol resumable olarak ayarlayın.
X-Goog-Upload-Raw-Size Aktarılacak dosya verilerinin toplam bayt sayısını belirleyin.

Aşağıda POST isteği başlığını görebilirsiniz:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

2. adım: Oturum URL'sini kaydetme

Başarılı olursa POST isteği, aşağıdaki başlığı da içeren bir 200 OK HTTP durum kodu döndürür.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

x-goog-upload-chunk-granularity başlık alanı, istemci tarafından gönderilen tüm veri parçaları için bayt hizalamasını ve boyut ayrıntı düzeyini içerir. Yükleme birden fazla parça halinde yapılmışsa son yükleme hariç tüm yüklemeler bu değerin katları halinde yapılmalıdır. Yani dosyanın yükleme baytları bu değere hizalanmalıdır. Son parçada, kalan baytları yükleyebilirsiniz.

X-Goog-Upload-URL başlık alanı, yüklemeyi kalan tüm istekler aracılığıyla tamamlamak için kullanılması gereken benzersiz bir URL içerir. Sonraki isteklerde kullanabilmek için bu devam ettirilebilir oturum URL'sini kopyalayıp kaydedin.

3. Adım: Dosyayı yükleme

Devam ettirilebilir oturumu olan bir dosyayı iki şekilde yükleyebilirsiniz:

  1. Tek bir istekte. Bu yaklaşım, daha az istek gerektirdiği ve dolayısıyla daha iyi performans gösterdiği için genellikle en iyisidir.

  2. Birden çok parça halinde. Bu yaklaşımda, veriler parçalara ayrılarak birden çok istekte yükleme yapılır. Veriler x-goog-upload-chunk-granularity katlarına bölünür. Gerekirse, parçalı istekler yeniden denenebilir.

    Bu yaklaşımı aşağıdaki durumlarda kullanın:

    • Herhangi bir istekte aktarılan veri miktarını azaltmanız gerekir. Tek tek istekler için sabit bir süre sınırı olduğunda bu işlemi yapmanız gerekebilir.
    • Yükleme işleminin ilerleme durumunu gösteren özelleştirilmiş bir gösterge sağlamanız gerekir.
    • Verileri silmenin ne zaman güvenli olduğunu bilmeniz gerekir.

Tek İstek

Dosyayı tek bir istekte yüklemek için:

  1. Devam ettirilebilir oturum URL'si için bir POST isteği oluşturun.
  2. Dosya verilerini istek gövdesine ekleyin.

  3. Aşağıdaki HTTP üstbilgilerini ekleyin:

    • Content-Length: Dosyadaki bayt sayısını ayarlayın.
    • X-Goog-Upload-Command: upload, finalize olarak ayarlanır.

  4. İsteği gönderin.

Yükleme isteği kesilirse veya 5xx yanıtı alırsanız Kesintiye uğrayan bir yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.

İstek başarılı olursa yanıt gövdesinde bir 200 OK HTTP durum kodu ve yükleme jetonu alırsınız. Bu yükleme jetonunu kullanarak medya öğesini oluşturun.

Birden Fazla Parça

Dosyayı birden fazla parçaya yüklemek için:

  1. Devam ettirilebilir oturum URL'si için bir POST isteği oluşturun.

  2. Parçanın verilerini istek gövdesine ekleyin.

    Yüklemeyi tamamlayan son parça hariç, diğer parçaları kabul edilen parça boyutlarının katları halinde oluşturun. Yüklemenin verimli olması için parça boyutunu mümkün olduğunca büyük tutun.

  3. Aşağıdaki HTTP üstbilgilerini ekleyin:

    • Content-Length: Yığındaki bayt sayısını ayarlayın.
    • X-Goog-Upload-Command: upload olarak ayarlanır. Son yığın için upload, finalize olarak ayarlayın.
    • X-Goog-Upload-Offset: Baytların yazılması gereken ofset olarak ayarlayın. Baytların seri olarak yüklenmesi gerektiğini unutmayın. İlk ofset 0.
  4. İsteği gönderin.

    Yükleme isteği kesilirse veya 5xx yanıtı alırsanız Kesintiye uğrayan bir yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.

  5. Dosyadaki kalan her parça için yukarıdaki adımları tekrarlayın.

İstek başarılı olursa yanıt gövdesinde bir 200 OK HTTP durum kodu ve yükleme jetonu alırsınız. Bu yükleme jetonunu kullanarak medya öğesini oluşturun.

Örnek

Tek İstek

Aşağıdaki örnekte, tek bir istekle 3.039.417 baytlık JPEG dosyası yüklemeye yönelik devam ettirilebilir bir istek gösterilmektedir.

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

Yanıt, yükleme URL'sini ve beklenen yığın boyutunu içerir:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

Son yükleme isteği:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Birden Fazla Parça

Aşağıdaki örnekte, devam ettirilebilir oturum URL'si ve önceki adımda elde edilen kabul edilen yığın boyutu ayrıntı düzeyi kullanılarak 3.039.417 baytlık bir JPEG dosyası birden fazla parça halinde yüklemeye yönelik devam ettirilebilir bir istek gösterilmektedir. Bu örnekte, 262.144 baytlık bir yığın boyutu kullanılmaktadır. Bu boyut, yükleme oturumu başlatıldığında x-goog-upload-chunk-granularity başlık alanında döndürülür. Her yüklemenin 262.144'ün katları olan baytlar içerdiğini unutmayın.

Önceki adımda açıklandığı gibi yükleme URL'sini ve parça boyutunu almak için yükleme oturumunu başlatın:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

Yanıt, yükleme URL'sini ve beklenen yığın boyutunu içerir:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

İlk yığın:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

İkinci yığın:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

Son yığın:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

Kesintiye uğrayan bir yüklemeyi devam ettirme

Yükleme isteği kesilirse veya 200 olmayan bir HTTP durum kodu alırsanız yüklemenin ne kadarının başarılı olduğunu öğrenmek için sunucuyu sorgulayın.

Burada, devam ettirilebilir oturum URL'sine yönelik bir POST isteği gösterilmektedir. X-Goog-Upload-Command, query olarak ayarlanmalıdır.

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

Sunucudan gelen yanıtta bir 200 OK HTTP durum kodu ve yüklemenin geçerli boyutu bulunur.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Daha sonra bu ofsette yüklemeye devam edebilirsiniz. Birleşik yükleme ve sonlandırma komutu göndermediğiniz sürece sunucu tarafından sağlanan ofsette devam etmeniz gerekir. Bu durumda, ofset 0'dan devam edebilirsiniz.

Sorgu komutunuzun HTTP yanıtında X-Goog-Upload-Status üst bilgisi varsa ve değer active değilse bu, yüklemenin sonlandırıldığını gösterir.