Devam Ettirilebilir Yükleme Gerçekleştirme

Bu sayfada, Street View Publish API'de devam ettirilebilir yükleme isteğinin nasıl yapılacağı açıklanmaktadır. Bu protokol, iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemine devam etmenize olanak tanır. Bu seçeneği şu durumlarda kullanın:

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

Devam ettirilebilir yüklemeler, büyük dosya yüklemelerini baştan başlatmanız gerekmediğinden ağ hatası olduğunda bant genişliği kullanımınızı da azaltabilir.

Küçük dosyaları güvenilir bir ağ bağlantısı üzerinden gönderiyorsanız bunun yerine basit yükleme özelliğini kullanabilirsiniz.

Devam ettirilebilir yükleme oturumu başlatma

uploadUrl aldıktan sonra devam ettirilebilir bir yükleme oturumu başlatabilirsiniz:

  1. POST uploadUrl için istek oluşturun.

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

    • X-Goog-Upload-Protocol: resumable olarak ayarlayın.
    • X-Goog-Upload-Header-Content-Length: Dosya verilerinin toplam bayt sayısına ayarlanır. Bu veriler sonraki isteklerde aktarılır.
    • X-Goog-Upload-Header-Content-Type: Dosya verilerinin MIME türüne ayarlanır.
    • X-Goog-Upload-Command: start olarak ayarlayın.

  3. İsteği gönderin.

Örnek: Devam ettirilebilir yükleme oturumu başlatma

Aşağıdaki örnekte, yeni bir dosya yüklemek için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir. Bu durumda dosya bir resimdir ve dosyadaki toplam bayt sayısı 4200000'dür. İstek metninin boş olduğunu unutmayın. Bu nedenle, Content-Length üstbilgisi 0 olarak ayarlanır.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Devam ettirilebilir oturum URL'sini kaydetme, devam ettirilebilir yükleme oturumunu başlatma isteğine verilen yanıtın nasıl işleneceğini açıklar.

Devam ettirilebilir oturum URL'sini kaydetme

Devam ettirilebilir yükleme oturumu başlatmak için gönderilen isteğe sunucu, aşağıdaki başlığı içeren bir 200 OK HTTP durum koduyla yanıt verir:

  • X-Goog-Upload-URL: Kalan tüm istekler aracılığıyla yükleme işlemini tamamlamak için kullanılması gereken benzersiz bir URL.

Sonraki isteklerde kullanabilmek için devam ettirilebilir oturum URL'sini kopyalayıp kaydedin.

Örnek: Devam ettirilebilir oturum URL'sini kaydetme

Aşağıdaki örnekte, devam ettirilebilir oturum URL'si ve boyut ayrıntı düzeyi koşulu içeren bir yanıt gösterilmektedir.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Dosya yükleniyor

Devam ettirilebilir oturumla dosya yüklemenin iki yolu vardır:

  1. Tek bir istekte. Bu yaklaşım genellikle en iyisidir. Çünkü daha az istek gerektirir ve bu nedenle daha iyi performans gösterir.
  2. Birden fazla parça halinde. Bu yaklaşımı şu durumlarda kullanın:
    • Tek bir istekte aktarılan veri miktarını azaltmanız gerekir. Bu işlemi, tek tek istekler için sabit bir zaman sınırı olduğunda yapmanız gerekebilir.
    • Yükleme ilerlemesini gösteren özelleştirilmiş bir gösterge sağlamanız gerekir.
    • Verileri ne zaman güvenle silebileceğinizi 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. Dosyanın verilerini istek gövdesine ekleyin.

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

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

  4. İsteği gönderin.

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

Birden Fazla Parça

Dosyayı birden fazla parça halinde 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ç olmak üzere, 2 MiB (mebibayt) katları şeklinde parçalar 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: Parçadaki bayt sayısına ayarlanır.
    • X-Goog-Upload-Command: upload olarak ayarlayın. Son parça için upload, finalize olarak ayarlayın.
    • X-Goog-Upload-Offset: Baytların yazılması gereken ofset olarak ayarlanır. Baytların sırayla yüklenmesi gerektiğini unutmayın.

  4. İsteği gönderin. Yükleme isteği kesintiye uğrarsa veya 5xx yanıtı alırsanız Kesintiye uğrayan yüklemeyi devam ettirme bölümündeki prosedürü uygulayın.

  5. Dosyadaki kalan her parça için 1-4 arasındaki adımları tekrarlayın.

Örnek: Dosyayı yükleme

Tek İstek

Aşağıdaki örnekte, önceki adımda elde edilen devam ettirilebilir oturum URL'si kullanılarak 4.200.000 baytlık bir JPEG dosyasının tek bir istekte yüklenmesi için devam ettirilebilir bir istek gösterilmektedir:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

İstek başarılı olursa 200 OK HTTP durum kodu alırsınız.

Birden Fazla Parça

Aşağıdaki örnekte, önceki adımda elde edilen devam ettirilebilir oturum URL'si ve boyut ayrıntısı kullanılarak 4.200.000 baytlık bir JPEG dosyasını birden fazla parça halinde yüklemek için devam ettirilebilir bir istek gösterilmektedir. Bu örnekte, 2 MiB'in (mebibayt) katı olan 2097000 baytlık bir parça boyutu kullanılmaktadır.

İlk parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

İkinci parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Son parça: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Kesintiye uğrayan yüklemeyi devam ettirme

Yükleme isteği kesintiye uğrarsa veya 200 olmayan bir HTTP durum kodu alırsanız yüklemenin ne kadarının başarılı olduğunu öğrenmek için sunucuya sorgu gönderin:

  1. Devam ettirilebilir oturum URL'si için bir POST isteği oluşturun.
  2. X-Goog-Upload-Command değerini query olarak ayarlayın.
  3. İsteği gönderin.

Sunucu, 200 OK HTTP durum koduyla ve yüklemenin mevcut boyutuyla yanıt verir:

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

Ardından, yüklemeye bu ofsetten devam edebilirsiniz. Birleştirilmiş bir yükleme ve sonlandırma komutu göndermediğiniz sürece, sunucu tarafından sağlanan ofsetten devam etmeniz gerekir. Bu durumda, 0 ofsetinden de devam edebilirsiniz.

Sorgu komutunuzun HTTP yanıtındaki X-Goog-Upload-Status başlığı varsa ve değeri active değilse yükleme zaten sonlandırılmıştır.