Devam ettirilebilir yüklemeler

Bu sayfada, REST protokolü aracılığıyla Google Fotoğraflar Kitaplığı API'sine nasıl devam ettirilebilir yükleme isteği gönderileceği açıklanmaktadır. Bu protokol, iletişim hatası nedeniyle veri akışı kesintiye uğradıktan sonra yükleme işlemini devam ettirmenize olanak tanır.

Şu durumlarda devam ettirilebilir yükleme seçeneğini kullanın:

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

Devam ettirilebilir yüklemeler, ağ üzerindeyken bant genişliği kullanımınızı da azaltabilir büyük dosya yüklemelerini yeniden başlatmak zorunda olmadığınızdan başlar.

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

Şu kullanıcıya POST isteği göndererek devam ettirilebilir bir yükleme oturumu başlatın: https://photoslibrary.googleapis.com/v1/uploads Devam ettirilebilir yüklemeyi kullanma Bu istekte döndürülen URL, dosyayı yükleyin.

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

Üst bilgi alanları
Content-Length İstek metni boş olduğundan 0 olarak ayarlanır.
X-Goog-Upload-Command start olarak ayarlayın.
X-Goog-Upload-Content-Type Dosyanın MIME türüne ayarlanır (ö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ına ayarlanır.

Aşağıda bir POST istek başlığı verilmiştir:

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

POST isteği başarılı olursa aşağıdaki başlık da dahil olmak üzere 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ı bayt hizalamasını içeriyor ve boyut ayrıntı düzeyini gösterir. Yükleme birden fazla parça halinde yapılır. Son yükleme dışındaki tüm yüklemeler, bu değerin katları halinde yapılmalıdır. Yani dosyanın yükleme baytları bu değere göre hizalanmalıdır. Son parçada, kalan baytları yükleyebilirsiniz.

X-Goog-Upload-URL başlık alanı, şunların yapılması için kullanılması gereken benzersiz bir URL içeriyor: ve kalan tüm istekler doğrultusunda yüklemeyi tamamlamalıdır. Bunu kopyalayıp kaydet devam ettirilebilir oturum URL'si oluşturun.

3. adım: Dosyayı yükleme

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

  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 fazla parça halinde. Bu yaklaşımda, yüklenen her video verileri topluca birleştirerek birden fazla istekte bulunabilirsiniz. Veriler parçalı x-goog-upload-chunk-granularity sayısının katları. Gerekirse, bölümlendirilmiş istekler yeniden denenebilir.

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

    • Tek bir istekte aktarılan veri miktarını azaltmanız gerekir. Projenin hedefleri için sabit bir zaman sınırı talep edebilir.
    • Yüklemeyi gösteren özelleştirilmiş bir gösterge sağlamanız gerekir takip edebilirsiniz.
    • Verileri silmenin ne zaman güvenli olduğunu bilmeniz gerekir.

Tek İstek

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

  1. Devam ettirilebilir oturum URL'sine 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 ayarlandı.

  4. İsteği gönderin.

Yükleme isteği kesintiye uğrarsa veya bir 5xx alırsanız devam etmek istiyorsanız Yükleme kesintiye uğradı.

İ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 Çok Parça

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

  1. Devam ettirilebilir oturum URL'sine bir POST isteği oluşturun.

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

    Yüklemeyi tamamlayan son parça dışında, kabul edilen parça boyutunun katları şeklinde oluşturulduğundan emin olun. Yüklemenin verimli olması için bölüm 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 ayarlanır. Son parça için upload, finalize olarak ayarlayın.
    • X-Goog-Upload-Offset: Baytların yazılacağı ofset değerine ayarlanır. Baytların seri olarak yüklenmesi gerektiğini unutmayın. İlk ofset 0.
  4. İsteği gönderin.

    Yükleme isteği kesintiye uğrarsa veya bir 5xx alırsanız devam etmek istiyorsanız Yükleme kesintiye uğradı.

  5. Dosyada kalan her parça için bu 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. Oluştur medya öğesine gönderebilirsiniz.

Örnek

Tekli İstek

Aşağıdaki örnekte, 3.039.417 baytlık bir JPEG dosyasını tek bir istekle yüklemek için kullanılabilecek, 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 parça 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 büyük parça

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

Yükleme URL'sini ve parça boyutunu almak için yükleme oturumunu başlatın adımları uygulayı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 parça 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 parça:

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 parça:

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 parça:

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 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 sunucuyu sorgulayın.

Devam ettirilebilir oturum URL'sine yapılan bir POST isteği. 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 200 OK HTTP durum kodu ve yüklemenin mevcut boyutu yer alır.

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

Ardından, yüklemeyi bu uzaklıkta devam ettirebilirsiniz. Ofsetten devam etmeniz gerekir yükleme ve sonlandırma komutu göndermediğiniz sürece sunucu tarafından sağlanır. Bu durumda, ofseti 0'dan da devam ettirebilirsiniz.

Sorgu komutunuzun HTTP yanıtında X-Goog-Upload-Status başlığı varsa ve değer active değilse yüklemenin zaten sonlandırılmış olduğu anlamına gelir.