Google Mirror API, yeni bir zaman çizelgesi öğesi oluştururken ek eklemenize olanak tanır.
Yükleme seçenekleri
Google Mirror API, belirli ikili veri veya medya türlerini yüklemenize olanak tanır. Yükleyebileceğiniz verilerin belirli özellikleri, medya yüklemelerini destekleyen herhangi bir yöntem için referans sayfasında belirtilmiştir:
- Maksimum yükleme dosyası boyutu: Bu yöntemle depolayabileceğiniz maksimum veri miktarıdır.
- Kabul edilen medya MIME türleri: Bu yöntemi kullanarak depolayabileceğiniz ikili program verisi türleri.
Aşağıdaki yöntemlerden herhangi birini kullanarak yükleme isteğinde bulunabilirsiniz. uploadType
istek parametresiyle kullandığınız yöntemi belirtin.
- Basit yükleme:
uploadType=media
. Örneğin 5 MB veya daha küçük boyutlu dosyaların hızlı aktarımı içindir. - Çok parçalı yükleme:
uploadType=multipart
. Daha küçük dosyaların ve meta verilerin hızlı aktarımı için; dosyayı, tek bir istekte bulunarak dosyayı açıklayan meta verilerle birlikte aktarır. - Devam ettirilebilir yükleme:
uploadType=resumable
. Güvenilir aktarım için özellikle büyük dosyalarda önemlidir. Bu yöntemle, isteğe bağlı olarak meta veriler içerebilen bir oturum başlatma isteği kullanırsınız. Bu, yükleme başına bir ek HTTP isteği karşılığında daha küçük dosyalarda da çalıştığından çoğu uygulamada iyi bir stratejidir.
Medya yüklerken özel bir URI kullanırsınız. Aslında medya yüklemelerini destekleyen yöntemlerde iki URI uç noktası bulunur:
Medya için /upload URI'si. Yükleme uç noktasının biçimi "/upload" önekine sahip standart kaynak URI'si Bu URI'yı şu durumlarda kullanın: aktarılmaya başlar.
Örnek:
POST /upload/mirror/v1/timeline
Meta veriler için standart kaynak URI'si. Kaynakta herhangi bir bu alanlar, yüklenen dosyayı açıklayan meta verileri depolamak için kullanılır. dosyası olarak kaydedebilirsiniz. Bu URI'yı meta veri değerlerini oluştururken veya güncellerken kullanabilirsiniz.
Örnek:
POST /mirror/v1/timeline
.
Basit yükleme
Dosya yüklemenin en basit yöntemi, basit bir yükleme isteğinde bulunmaktır. Aşağıdaki durumlarda bu seçenek iyi bir tercihtir:
- Dosya, bağlantı kurulamazsa tamamen yüklenebilecek kadar küçüktür.
- Gönderilecek meta veri yok. Bu kaynakla ilgili meta verileri ayrı bir istekte göndermeyi planlıyorsanız ya da meta veri desteklenmiyorsa veya mevcut değilse bu durum geçerli olabilir.
Basit yüklemeyi kullanmak için şunun için bir POST
veya PUT
isteğinde bulunun:
yöntemin /upload URI'si ve sorgu parametresini ekleyin
uploadType=media
. Örneğin:
POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=media
Basit bir yükleme isteği gönderirken kullanılacak HTTP üstbilgileri şunlardır:
Content-Type
API referansında belirtilen, yöntemin kabul edilen medya yükleme veri türlerinden birine ayarlayın.Content-Length
Yüklediğiniz bayt sayısına ayarlayın. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.
Örnek: Basit yükleme
Aşağıdaki örnekte, Google Mirror API'si.
POST /upload/mirror/v1/timeline?uploadType=media HTTP/1.1 Host: www.googleapis.com Content-Type: image/jpeg Content-Length: number_of_bytes_in_file Authorization: Bearer your_auth_token JPEG data
İstek başarılı olursa sunucu, meta verilerle birlikte HTTP 200 OK
durum kodunu döndürür:
HTTP/1.1 200 Content-Type: application/json { "text": "Hello world!" }
Çok parçalı yükleme
Yüklenecek verilerle birlikte göndermek istediğiniz meta veriler varsa tek bir multipart/related
isteğinde bulunabilirsiniz. Gönderdiğiniz veriler, bağlantı başarısız olursa tamamen yeniden yüklenecek kadar küçükse bu iyi bir seçenektir.
Çok parçalı yüklemeyi kullanmak için yöntemin /upload URI'sine POST
veya PUT
isteğinde bulunun ve sorgu parametresini ekleyin
uploadType=multipart
, örneğin:
POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=multipart
Çok parçalı bir yükleme isteği gönderirken kullanılacak üst düzey HTTP üstbilgileri şunlardır:
Content-Type
Çok parçalı/ilgili olarak ayarlayın ve isteğin bölümlerini tanımlamak için kullandığınız sınır dizesini ekleyin.Content-Length
İstek gövdesindeki toplam bayt sayısına ayarlayın. İsteğin medya bölümü, bu yöntem için belirtilen maksimum dosya boyutundan küçük olmalıdır.
İsteğin gövdesi, multipart/related
içerik türü [RFC2387] olarak biçimlendirilmiştir ve tam olarak iki bölümden oluşur. Bölümler bir sınır dizesiyle tanımlanır ve son sınır dizesinin ardından iki kısa çizgi gelir.
Çok parçalı isteğin her bölümü için ek bir Content-Type
başlığı gerekir:
- Meta veri bölümü: Önce gelmeli ve
Content-Type
, kabul edilen meta veri biçimlerinden biriyle eşleşmelidir. - Medya bölümü: İkinci olarak gelmeli ve
Content-Type
, yöntemin kabul edilen medya MIME türleriyle eşleşmelidir.
Her yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyalar için boyut sınırları listesi için API referansına bakın.
Not: Meta veri bölümünü oluşturmak veya güncellemek için
yalnızca, ilişkilendirilmiş verileri yüklemeden standart kaynak uç noktasına bir POST
veya PUT
isteği göndermeniz yeterlidir:
https://www.googleapis.com/mirror/v1/timeline
Örnek: Çok parçalı yükleme
Aşağıdaki örnekte, Google Mirror API için çok parçalı bir yükleme isteği gösterilmektedir.
POST /upload/mirror/v1/timeline?uploadType=multipart HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Type: multipart/related; boundary=foo_bar_baz Content-Length: number_of_bytes_in_entire_request_body --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "text": "Hello world!" } --foo_bar_baz Content-Type: image/jpeg JPEG data --foo_bar_baz--
İstek başarılı olursa sunucu, meta verilerle birlikte HTTP 200 OK
durum kodunu döndürür:
HTTP/1.1 200 Content-Type: application/json { "text": "Hello world!" }
Devam ettirilebilir yükleme
Veri dosyalarını daha güvenilir şekilde yüklemek için devam ettirilebilir yükleme protokolünü kullanabilirsiniz. Bu protokol, bir iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemini devam ettirmenizi sağlar. Bu, özellikle büyük dosyalar aktarıyorsanız ve ağ kesintisi veya başka bir iletim hatası olasılığı yüksekse (örneğin, bir mobil istemci uygulamasından yükleme yaparken) kullanışlıdır. Ayrıca, büyük dosya yüklemelerini en baştan yeniden başlatmanız gerekmediği için ağ hatası durumunda bant genişliği kullanımınızı da azaltabilir.
Devam ettirilebilir yüklemeyi kullanma adımları şunlardır:
- Devam ettirilebilir bir oturum başlatın. Varsa meta verileri içeren yükleme URI'sine ilk istekte bulunun.
- Devam ettirilebilir oturum URI'sini kaydedin. İlk isteğin yanıtında döndürülen oturum URI'sini kaydedin; bu oturumdaki kalan istekler için bu numarayı kullanacaksınız.
- Dosyayı yükleyin. Medya dosyasını, devam ettirilebilir oturum URI'sine gönderin.
Ayrıca, devam ettirilebilir yüklemeyi kullanan uygulamaların, kesintili yüklemeyi devam ettirecek koda sahip olmaları gerekir. Yükleme kesintiye uğrarsa başarıyla ne kadar veri alındığını öğrenin ve yüklemeyi bu noktadan itibaren devam ettirin.
Not: Yükleme URI'sinin süresi bir hafta sonra dolar.
1. Adım: Devam ettirilebilir bir oturum başlatın
Devam ettirilebilir bir yükleme başlatmak için yöntemin /upload URI'sine POST
veya PUT
isteğinde bulunun ve sorgu parametresini ekleyin
uploadType=resumable
, örneğin:
POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable
Bu başlatılan istek için gövde boş veya yalnızca meta veri içeriyor; sonraki isteklerde yüklemek istediğiniz dosyanın gerçek içeriğini aktarırsınız.
İlk istekle birlikte aşağıdaki HTTP üstbilgilerini kullanın:X-Upload-Content-Type
Sonraki isteklerde aktarılacak yükleme verilerinin medya MIME türüne ayarlayın.X-Upload-Content-Length
Sonraki isteklerde aktarılacak yükleme verilerinin bayt sayısını ayarlayın. İstek sırasında uzunluk bilinmiyorsa bu başlığı atlayabilirsiniz.- Meta veri sağlıyorsanız:
Content-Type
. Meta verilerin veri türüne göre ayarlanır. Content-Length
Bu ilk isteğin gövdesinde sağlanan bayt sayısına ayarlayın. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.
Her yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyalar için boyut sınırları listesi için API referansına bakın.
Örnek: Devam ettirilebilir oturum başlatma isteği
Aşağıdaki örnekte, Google Mirror API için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir.
POST /upload/mirror/v1/timeline?uploadType=resumable HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Length: 38 Content-Type: application/json; charset=UTF-8 X-Upload-Content-Type: image/jpeg X-Upload-Content-Length: 2000000 { "text": "Hello world!" }
Not: Meta veri içermeyen ilk devam ettirilebilir güncelleme isteği için isteğin gövdesini boş bırakın ve Content-Length
başlığını 0
olarak ayarlayın.
Sonraki bölümde yanıtın nasıl ele alınacağı açıklanmaktadır.
2. Adım: Devam ettirilebilir oturum URI'sini kaydedin
Oturum başlatma isteği başarılı olursa API sunucusu, 200 OK
HTTP durum koduyla yanıt verir. Ayrıca, devam ettirilebilir oturum URI'nızı belirten bir Location
üst bilgisi sağlar. Aşağıdaki örnekte gösterilen Location
üstbilgisi, bu oturum için kullanılacak benzersiz yükleme kimliğini veren upload_id
sorgu parametresi bölümünü içerir.
Örnek: Devam ettirilebilir oturum başlatma yanıtı
1. Adımdaki isteğin yanıtı aşağıda verilmiştir:
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Yukarıdaki örnek yanıtta gösterildiği gibi Location
üstbilgisinin değeri, gerçek dosya yüklemeyi yapmak veya yükleme durumunu sorgulamak için HTTP uç noktası olarak kullanacağınız oturum URI'sidir.
Sonraki isteklerde kullanmak için oturum URI'sini kopyalayıp kaydedin.
3. adım: Dosyayı yükleyin
Dosyayı yüklemek için önceki adımda aldığınız yükleme URI'sine bir PUT
isteği gönderin. Yükleme isteğinin biçimi şu şekildedir:
PUT session_uri
Devam ettirilebilir dosya yükleme istekleri yapılırken kullanılacak HTTP üstbilgileri, Content-Length
öğesini içerir. Bunu, söz konusu istekte yüklediğiniz bayt sayısına (genellikle yükleme dosyasının boyutu) ayarlayın.
Örnek: Devam ettirilebilir dosya yükleme isteği
Geçerli örnek için 2.000.000 baytlık JPEG dosyasının tamamını yüklemeyle ilgili devam ettirilebilir bir isteği aşağıda bulabilirsiniz.
PUT https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1 Content-Length: 2000000 Content-Type: image/jpeg bytes 0-1999999
İstek başarılı olursa sunucu, bu kaynakla ilişkili tüm meta verilerle birlikte bir HTTP 201 Created
ile yanıt verir. Devam ettirilebilir oturumun ilk isteği bir PUT
olsaydı mevcut bir kaynağı güncellemek için başarılı yanıt, bu kaynakla ilişkili tüm meta verilerle birlikte 200 OK
olur.
Yükleme isteği kesintiye uğrarsa veya sunucudan HTTP 503 Service Unavailable
ya da başka bir 5xx
yanıtı alırsanız kesintiyi devam ettirme başlıklı makalede açıklanan prosedürü uygulayın.
Dosyayı parçalar halinde yükleme
Devam ettirilebilir yüklemelerle bir dosyayı parçalara ayırabilir ve her parçayı sırayla yüklemek için bir dizi istek gönderebilirsiniz. Ek isteklerle ilişkili performans maliyetleri bulunduğundan ve genellikle bu gerekli değildir. Bu nedenle tercih edilen yaklaşım bu değildir. Ancak herhangi bir istekte aktarılan veri miktarını azaltmak için parçalamayı kullanmanız gerekebilir. Bu, belirli Google App Engine istek sınıfları için geçerli olduğu gibi, tek tek istekler için sabit bir zaman sınırı olduğunda faydalıdır. Ayrıca, varsayılan olarak yükleme ilerleme durumu desteği olmayan eski tarayıcılar için yükleme ilerleme durumu göstergeleri sağlamak gibi işlemler yapmanıza da olanak tanır.
Kesintiye uğrayan yüklemeyi devam ettirme
Yükleme isteği yanıt alınmadan sonlandırılırsa veya sunucudan HTTP 503 Service Unavailable
yanıtı alırsanız kesintiye uğrayan yüklemeyi devam ettirmeniz gerekir. Bunun için:
- İstek durumu. Yükleme URI'sine boş bir
PUT
isteği göndererek yüklemenin mevcut durumunu sorgulayın. Bu istek için, HTTP üstbilgileri, dosyadaki mevcut konumun bilinmediğini belirten birContent-Range
başlığı içermelidir. Örneğin, toplam dosya uzunluğunuz 2.000.000 iseContent-Range
değerini*/2000000
olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanızContent-Range
özelliğini*/*
olarak ayarlayın.Not: Yalnızca yükleme kesintiye uğradığında değil, parçalar arasında durum bilgisi isteyebilirsiniz. Bu, örneğin, eski tarayıcılar için yükleme ilerleme göstergelerini göstermek istiyorsanız yararlıdır.
- Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, şu ana kadar aldığı baytları belirtmek için yanıtında
Range
üstbilgisini kullanır. Örneğin,0-299999
öğesininRange
üstbilgisi,dosyanın ilk 300.000 baytının alındığını gösterir. - Kalan verileri yükleyin. Son olarak, isteği nereden devam ettireceğinizi bildiğinize göre, kalan verileri veya mevcut parçayı gönderin. Kalan verileri her iki durumda da ayrı bir parça olarak ele almanız gerektiğini unutmayın. Bu nedenle, yüklemeyi devam ettirdiğinizde
Content-Range
başlığını göndermeniz gerekir.
Örnek: Kesintiye uğrayan bir yüklemeyi devam ettirme
1) Yükleme durumunu isteyin.
Aşağıdaki istekte, 2.000.000 baytlık dosyadaki mevcut konumun bilinmediğini belirtmek için Content-Range
başlığı kullanılmaktadır.
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000
2) Yanıttan o ana kadar yüklenen bayt sayısını çıkarın.
Sunucunun yanıtı, şimdiye kadar dosyanın ilk 43 baytını aldığını belirtmek için Range
üstbilgisini kullanır. Devam ettirilen yüklemenin nereden başlatılacağını belirlemek için Range
başlığının üst değerini kullanın.
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: 0-42
Not: Yükleme tamamlandıysa durum yanıtı 201 Created
veya 200 OK
olabilir. Bu durum, tüm baytlar yüklendikten sonra ancak istemci sunucudan bir yanıt almadan önce bağlantı koptuysa ortaya çıkabilir.
3) Yüklemeye kaldığı yerden devam edin.
Aşağıdaki istek, dosyanın kalan baytlarını göndererek 43. bayttan başlayarak yüklemeyi devam ettirir.
PUT {session_uri} HTTP/1.1 Content-Length: 1999957 Content-Range: bytes 43-1999999/2000000 bytes 43-1999999
En iyi uygulamalar
Medya yüklerken, hata işlemeyle ilgili en iyi uygulamaları dikkate almanız önerilir.
- Aşağıdakiler dahil olmak üzere, bağlantı kesintileri veya herhangi bir
5xx
hatası nedeniyle başarısız olan yüklemeleri devam ettirin veya yeniden deneyin:500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Yükleme istekleri devam ettirilirken veya yeniden denenirken
5xx
sunucu hatası döndürülürse eksponansiyel geri yükleme stratejisi kullanın. Sunucu aşırı yükleniyorsa bu hatalar ortaya çıkabilir. Üstel geri yükleme, yüksek istek hacmi veya yoğun ağ trafiği sırasında bu tür sorunların giderilmesine yardımcı olabilir. - Diğer istek türlerinin eksponansiyel geri yükleme ile işlenmemesi gerekir ancak birkaçını yeniden deneyebilirsiniz. Bu istekleri yeniden denerken işlemi deneme sayısını sınırlandırın. Örneğin, kodunuzda, hata bildirmeden önce en fazla on deneme olabilir.
- Devam ettirilebilir yüklemeler yaparken tüm yüklemeyi baştan başlatarak
404 Not Found
ve410 Gone
hatalarını giderin.
Eksponansiyel geri yükleme
Üstel geri yükleme, ağ uygulamaları için standart bir hata işleme stratejisidir. İstemci bu uygulamada, istemcinin başarısız bir isteği belirli bir süre boyunca düzenli olarak yeniden dener. Çok sayıda istek veya yoğun ağ trafiği, sunucunun hata döndürmesine neden oluyorsa üstel geri yükleme, bu hataları ele almak için iyi bir strateji olabilir. Buna karşılık, geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları gibi ağ hacmi ya da yanıt süreleriyle ilgili olmayan hataları ele almak için uygun bir strateji değildir.
Doğru kullanıldığında, üstel geri yükleme bant genişliği kullanımının verimliliğini artırır, başarılı bir yanıt almak için gereken istek sayısını azaltır ve eşzamanlı ortamlarda isteklerin işleme hızını en üst düzeye çıkarır.
Basit üstel geri yükleme uygulama akışı aşağıdaki gibidir:
- API'ye istekte bulunun.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 1 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 2 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 4 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 8 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 16 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
- Durdur. Hata bildirin veya günlüğe kaydedin.
Yukarıdaki akışta rastgele_sayı_milisaniye sayısı, 1000'den küçük veya 1000'e eşit olan rastgele bir milisaniye sayısıdır. Küçük bir rastgele gecikme uygulamak, yükün daha eşit şekilde dağıtılmasına yardımcı olacağından ve sunucunun damgalanması olasılığını ortadan kaldıracağından bu gereklidir. Rastgele_sayı_milisaniye değeri, her beklemeden sonra yeniden tanımlanmalıdır.
Not: Bekleme süresi her zaman (2 ^ n) + rastgele_sayı_milisaniyedir. Burada n, başlangıçta 0 olarak tanımlanan, monoton olarak artan bir tam sayıdır. n tam sayısı her iterasyon (her istek) için 1 oranında artar.
Algoritma, n değeri 5 olduğunda sona erecek şekilde ayarlanmıştır. Bu üst sınır, istemcilerin sonsuza kadar yeniden denemesini engeller ve istek "kurtarılamayan hata" olarak değerlendirilmeden önce yaklaşık 32 saniyelik bir toplam gecikmeyle sonuçlanır. Özellikle uzun bir yükleme devam ediyorsa maksimum yeniden deneme sayısının yüksek olması sorun yaratmaz; yeniden deneme süresini makul bir süreye (örneğin, bir dakikadan az) ayarladığınızdan emin olun.