Medya yükleme özelliği, Display & Video 360 API'nin verileri bulutta depolamasına ve sunucuya sunmasına olanak tanır. Kullanıcının yüklemek isteyebileceği veri türü; fotoğrafları, videoları, PDF dosyalarını, zip dosyalarını veya diğer veri türlerini içerir.
Bu belgede verilen örnekler, kurgusal bir Çiftlik API'si için medya yükleme kullanımını göstermektedir. Ancak aynı kavramlar Display & Video 360 API'si için de geçerlidir.
Yükleme seçenekleri
Display & Video 360 API, belirli türdeki ikili program verilerini veya medyayı yüklemenize olanak tanır. Yükleyebileceğiniz verilerin belirli özellikleri, medya yüklemelerini destekleyen tüm yöntemler 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 veri türleridir.
Aşağıdaki yöntemlerden birini kullanarak yükleme isteğinde bulunabilirsiniz. uploadType
istek parametresiyle, kullandığınız yöntemi belirtin.
- Basit yükleme:
uploadType=media
. 5 MB veya daha küçük olması gibi daha küçük dosyaların hızlıca aktarılması için. - Çok parçalı yükleme:
uploadType=multipart
. Daha küçük dosyaların ve meta verilerin hızlı aktarımı için dosyayı tanımlayan meta verilerle birlikte tek bir istekte aktarılı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 veri içerebilen bir oturum başlatma isteği kullanırsınız. Bu, yükleme başına fazladan bir HTTP isteğine denk gelen küçük dosyalarda da çalıştığından çoğu uygulama için iyi bir stratejidir.
Medya yüklediğinizde özel bir URI kullanırsınız. Aslında, medya yüklemelerini destekleyen yöntemlerin iki URI uç noktası vardır:
Medya için /upload URI'sı. Yükleme uç noktasının biçimi, "/upload" önekine sahip standart kaynak URI'sidir. Medya verilerinin kendisini aktarırken bu URI'yi kullanın.
Örnek:
POST /upload/farm/v1/animals
Meta verilerin standart kaynak URI'sı. Kaynakta herhangi bir veri alanı varsa bu alanlar yüklenen dosyayı açıklayan meta verileri depolamak için kullanılır. Bu URI'yi meta veri değerlerini oluştururken veya güncellerken kullanabilirsiniz.
Örnek:
POST /farm/v1/animals
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 seçenektir:
- Dosya, bağlantı başarısız olursa tamamen yeniden yüklenecek kadar küçüktür.
- Gönderilecek meta veri yok. Bu kaynak için ayrı bir istekte meta veri göndermeyi planlıyorsanız veya hiçbir meta veri desteklenmiyor ya da mevcut değilse bu durum geçerli olabilir.
Basit yüklemeyi kullanmak için yöntemin /upload URI'sine bir POST
veya PUT
isteği yapın ve uploadType=media
sorgu parametresini ekleyin. Örneğin:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media
Basit bir yükleme isteği yaparken kullanılacak HTTP üstbilgileri şunlardır:
Content-Type
. API referanında belirtilen, yöntemin kabul ettiği yükleme medya verisi türlerinden birine ayarlayın.Content-Length
. Yüklemekte olduğunuz 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, hayali Çiftlik API'si için basit bir yükleme isteğinin kullanımı gösterilmektedir.
POST /upload/farm/v1/animals?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 tüm meta verilerle birlikte HTTP 200 OK
durum kodunu döndürür:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
Çok parçalı yükleme
Yüklenecek verilerle birlikte göndermek istediğiniz meta verileriniz varsa tek bir multipart/related
isteğinde bulunabilirsiniz. Gönderdiğiniz veriler, bağlantı başarısız olursa tamamen yükleme yapmaya yetecek 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ği yapın ve uploadType=multipart
sorgu parametresini ekleyin. Örneğin:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart
Çok parçalı bir yükleme isteği oluştururken 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 dahil edin.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çimlendirilir ve tam olarak iki bölümden oluşur. Parçalar 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 gelmelidir ve
Content-Type
, kabul edilen meta veri biçimlerinden biriyle eşleşmelidir. - Medya bölümü: İkinci olarak gelmelidir ve
Content-Type
, yöntemin kabul edilen medya MIME türlerinden biriyle eşleşmelidir.
Her yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyalarla ilgili boyut sınırları listesi için API referansı'na bakın.
Not: İlişkili verileri yüklemeden yalnızca meta veri bölümünü oluşturmak veya güncellemek için standart kaynak uç noktasına POST
veya PUT
isteği göndermeniz yeterlidir:
https://www.googleapis.com/farm/v1/animals
Örnek: Çok parçalı yükleme
Aşağıdaki örnekte hayali Çiftlik API'si için çok parçalı bir yükleme isteği gösterilmektedir.
POST /upload/farm/v1/animals?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 { "name": "Llama" } --foo_bar_baz Content-Type: image/jpeg JPEG data --foo_bar_baz--
İstek başarılı olursa sunucu tüm meta verilerle birlikte HTTP 200 OK
durum kodunu döndürür:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
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 ettirmenize olanak tanır. 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) özellikle kullanışlıdır. Ayrıca, büyük dosya yüklemelerini baştan başlatmak zorunda kalmayacağınız için ağ kesintileri 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 istek yapın.
- Devam ettirilebilir oturum URI'sini kaydedin. İlk isteğin yanıtında döndürülen oturum URI'sını kaydedin. Bu oturumdaki kalan istekler için 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, kesilen bir yüklemeyi devam ettirecek koda sahip olması gerekir. Yükleme kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yükleme işlemini buradan başlayarak 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 bir POST
veya PUT
isteği yapın ve uploadType=resumable
sorgu parametresini ekleyin. Örneğin:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable
Bu başlatma isteği için gövde boş veya yalnızca meta verileri içeriyor; yüklemek istediğiniz dosyanın gerçek içeriğini sonraki isteklerde aktaracaksı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ünü ayarlayın.X-Upload-Content-Length
. Sonraki isteklerde aktarılacak yükleme verilerinin bayt sayısını ayarlayın. Bu isteğin gönderildiği esnada uzunluk bilinmiyorsa bu başlığı çıkarabilirsiniz.- 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ını 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 dosyalarla ilgili boyut sınırları listesi için API referansı'na bakın.
Örnek: Devam ettirilebilir oturum başlatma isteği
Aşağıdaki örnekte, kurgusal Çiftlik API'si için nasıl devam ettirilebilir bir oturum başlatılacağı gösterilmektedir.
POST /upload/farm/v1/animals?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 { "name": "Llama" }
Not: Meta veri içermeyen ilk devam ettirilebilir güncelleme isteği için isteğin gövde bölümünü 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
başlığı, bu oturum için kullanılacak benzersiz yükleme kimliğini veren bir upload_id
sorgu parametresi bölümü 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/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Yukarıdaki örnek yanıtında gösterildiği gibi Location
üst bilgisinin 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.
Oturum URI'sini sonraki isteklerde kullanabilmek için 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 oluşturulurken kullanılacak HTTP üstbilgileri, Content-Length
öğesini içerir. Bunu, bu istekte yüklediğiniz bayt sayısına ayarlayın (bu genellikle yükleme dosyasının boyutudur.)
Örnek: Devam ettirilebilir dosya yükleme isteği
Mevcut örnek için 2.000.000 baytlık JPEG dosyasının tamamını yüklemek üzere devam ettirilebilir bir isteği burada görebilirsiniz.
PUT https://www.googleapis.com/upload/farm/v1/animals?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 HTTP 201 Created
ile yanıt verir. Devam ettirilebilir oturumun ilk isteği bir PUT
ise mevcut bir kaynağı güncellemek için başarılı yanıt bu kaynakla ilişkilendirilen 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 kesintisi olan bir yüklemeyi 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 bölebilir ve her bir parçayı sırayla yüklemek için bir dizi istek gönderebilirsiniz. Ek isteklerle ilişkili performans maliyetleri olduğundan ve genellikle gerekli olmadığından bu, tercih edilen yaklaşım değildir. Ancak, herhangi bir tek istekte aktarılan veri miktarını azaltmak için bölmeyi kullanmanız gerekebilir. Bu, belirli Google App Engine isteği sınıfları için geçerli olduğu gibi, tek tek istekler için sabit bir süre sınırı olduğunda faydalıdır. Ayrıca, varsayılan olarak yükleme ilerleme durumu desteği sunmayan eski tarayıcılar için yükleme ilerleme durumu göstergeleri sağlamak gibi işlemler yapmanıza da olanak tanır.
Kesilen bir yüklemeyi devam ettirme
Yükleme isteği yanıt alınmadan sonlandırılır 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
üstbilgisi içermelidir. Örneğin, toplam dosya uzunluğu 2.000.000 iseContent-Range
değerini*/2000000
olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanızContent-Range
öğesini*/*
olarak ayarlayın.Not: Yalnızca yükleme kesintiye uğradığında değil, parçalar arasındaki durumu da isteyebilirsiniz. Örneğin, eski tarayıcılar için yükleme ilerleme durumunu göstermek istiyorsanız bu seçenek yararlıdır.
- Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, şu ana kadar hangi baytları aldığını belirtmek için yanıtında
Range
üst bilgisini kullanır. Örneğin,0-299999
öğesininRange
üstbilgisi,dosyanın ilk 300.000 baytının alındığını belirtir. - Kalan verileri yükleyin. Son olarak, isteği nerede devam ettireceğinizi bildiğinize göre kalan verileri veya mevcut parçayı gönderin. Her iki durumda da kalan verileri ayrı bir yığın olarak işlemeniz gerektiğini, dolayısıyla yüklemeyi devam ettirdiğinizde
Content-Range
üstbilgisini göndermeniz gerektiğini unutmayın.
Örnek: Kesilen bir yüklemeyi devam ettirme
1) Yükleme durumunu isteyin.
Aşağıdaki istek, 2.000.000 baytlık dosyadaki mevcut konumun bilinmediğini belirtmek için Content-Range
başlığını kullanır.
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000
2) Yanıtın şimdiye kadar yüklenen bayt sayısını çıkarın.
Sunucunun yanıtında, dosyanın şu ana kadar ilk 43 baytını aldığını belirtmek için Range
üst bilgisi kullanılır. Devam ettirilen yüklemeyi nereden başlatacağınızı belirlemek için Range
üst bilgisinin ü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. Bağlantı, tüm baytlar yüklendikten sonra ancak istemci sunucudan bir yanıt almadan önce kesildiyse bu durum ortaya çıkabilir.
3) Yüklemeyi kaldığı yerden devam ettirin.
Aşağıdaki istek, 43 bayttan başlayarak dosyanın kalan baytlarını göndererek 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 giderme ile ilgili bazı en iyi uygulamaları bilmeniz yararlı olacaktır.
- Aşağıdakiler dahil olmak üzere bağlantı kesintileri veya
5xx
hataları nedeniyle başarısız olan yüklemeleri devam ettirin ya da yeniden deneyin:500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Yükleme istekleri devam ettirildiğinde veya yeniden denendiğinde
5xx
sunucu hatası döndürülürse üstel geri yükleme stratejisi kullanın. Bu hatalar, bir sunucu aşırı yükleniyorsa ortaya çıkabilir. Üstel geri çekilme, yüksek istek hacminin veya yoğun ağ trafiğinin olduğu dönemlerde bu tür sorunların hafifletilmesine yardımcı olabilir. - Diğer istek türleri üstel geri yükleme ile işlenmemelidir. Ancak yine de bazılarını yeniden deneyebilirsiniz. Bu istekleri yeniden denediğinizde, tekrar deneme sayısını sınırlayın. Örneğin, kodunuz hata bildirmeden önce on veya daha az yeniden denemeyle sınırlanabilir.
- Devam ettirilebilir yüklemeler yaparken, tüm yükleme işlemini baştan başlatarak
404 Not Found
ve410 Gone
hatalarını giderin.
Eksponansiyel geri yükleme
Üstel geri yükleme, istemcinin başarısız bir isteği giderek artan bir süre içinde düzenli olarak yeniden denediği, ağ uygulamaları için standart bir hata işleme stratejisidir. Yüksek hacimli istek veya yoğun ağ trafiği, sunucunun hata döndürmesine neden oluyorsa üstel geri çekilme, bu hataları ele almak için iyi bir strateji olabilir. Bununla birlikte, geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları gibi ağ hacmi veya 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 özelliği, 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 +Random_number_milliseconds bekleyin ve isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 2 saniye +Random_number_milliseconds bekleyin ve isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 4 saniye +Random_number_milliseconds bekleyin ve isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 8 saniye + rastgele_sayı_milisaniye cinsinden bekleyin ve isteği yeniden deneyin.
- İsteği yeniden denemeniz gerektiğini belirten bir
HTTP 503
yanıtı alın. - 16 saniye + rastgele_sayı_milisaniye cinsinden bekleyin ve isteği yeniden deneyin.
- Durdur. Hata bildirin veya günlüğe kaydedin.
Yukarıdaki akışta, rastgele_sayı_milisaniye, 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 bir şekilde dağıtılmasına ve sunucunun damgalanma olasılığını ortadan kaldırmaya yardımcı olduğundan bu gereklidir. Rastgele_sayı_milisaniye değeri, her beklemenin ardından yeniden tanımlanmalıdır.
Not: Bekleme süresi her zaman (2 ^ n) + rastgele_sayı_millisaniyedir. 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 artar.
Algoritma, n 5 olduğunda sona erecek şekilde ayarlanır. Bu üst sınır, istemcilerin sonsuza kadar yeniden deneme yapmasını engeller ve bir istek "kurtarılamaz hata" olarak kabul edilmeden önce toplamda yaklaşık 32 saniyelik bir gecikmeyle sonuçlanır. Özellikle uzun bir yükleme işlemi devam ediyorsa maksimum yeniden deneme sayısının daha yüksek olması sorun teşkil etmez. Yine de yeniden deneme gecikmesini makul bir süre, örneğin bir dakikadan daha az bir süreyle sınırladığınızdan emin olun.