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:
- 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.
-
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:
- Devam ettirilebilir oturum URL'si için bir
POST
isteği oluşturun. - Dosya verilerini istek gövdesine ekleyin.
Aşağıdaki HTTP üstbilgilerini ekleyin:
Content-Length
: Dosyadaki bayt sayısını ayarlayın.X-Goog-Upload-Command
:upload, finalize
olarak ayarlanır.
İ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:
- Devam ettirilebilir oturum URL'si için bir
POST
isteği oluşturun. -
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.
-
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çinupload, 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 ofset0
.
- İ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. - 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.