Medya Yükleme

Medya yükleme özelliği, Campaign Manager 360 API'nin verileri bulutta depolamasına ve sunucunun kullanımına sunmasına olanak tanır. Kullanıcıların yüklemek isteyebileceği veri türleri arasında fotoğraflar, videolar, PDF dosyaları, ZIP dosyaları veya başka veri türleri yer alır.

Bu dokümanda verilen örneklerde, kurgusal bir Farm API için medya yükleme kullanımı gösterilmektedir. Ancak aynı kavramlar Campaign Manager 360 API için de geçerlidir.

Yükleme seçenekleri

Campaign Manager 360 API, belirli ikili veri veya medya türlerini yüklemenize olanak tanır. Yükleyebileceğiniz verilerin özellikleri, medya yüklemelerini destekleyen yöntemlerin referans sayfasında belirtilir:

  • 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 parametresi ile 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. Küçük dosyaların ve meta verilerin hızlı aktarımı için; dosyayı, tanımlayan meta verileriyle birlikte tek bir istekte aktarır.
  • Devam ettirilebilir yükleme: uploadType=resumable. Güvenilir aktarım için özellikle büyük dosyalarda önemlidir. Bu yöntemde, isteğe bağlı olarak meta veri içerebilen bir oturum başlatma isteği kullanırsınız. Bu, yükleme başına bir ek HTTP isteği maliyeti 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. Medya yüklemelerini destekleyen yöntemlerin iki URI uç noktası vardır:

  • Medya için /upload URI'si. Yükleme uç noktasının biçimi, "/upload" ön ekine sahip standart kaynak URI'sidir. Medya verilerinin kendisini aktarırken bu URI'yi kullanın.

    Örnek: POST /upload/farm/v1/animals

  • 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. Meta veri değerleri oluştururken veya güncellerken bu URI'yi 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 tercihtir:

  • Dosya, bağlantı kesilirse tamamının tekrar yüklenebilecek kadar küçük olmalıdır.
  • Gönderilecek meta veri yok. Bu kaynağın meta verilerini 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/farm/v1/animals?uploadType=media

Basit bir yükleme isteği gönderirken kullanılacak HTTP başlıkları şunlardır:

  • Content-Type. API referansında belirtilen, yöntemin kabul ettiği medya yükleme veri türlerinden birine ayarlanır.
  • 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, kurgusal Farm API 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 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/farm/v1/animals?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çimlendirilir ve tam olarak iki bölümden oluşur. Parçalar bir sınır dizesi ile tanımlanır ve son sınır dizesi iki kısa çizgiyle takip edilir.

Çok parçalı isteğinde her parça için ek bir Content-Type başlığı gerekir:

  1. Meta veri bölümü: İlk sırada gelmelidir ve Content-Type, kabul edilen meta veri biçimlerinden biriyle eşleşmelidir.
  2. 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 ve yüklenen dosyalar için boyut sınırlamaları listesi için API referansına bakın.

Not: Yalnızca meta veri bölümünü oluşturmak veya güncellemek için, ilişkili verileri yüklemeden standart kaynak uç noktasına bir 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, kurgusal Farm API 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 bir şekilde yüklemek için devam ettirilebilir yükleme protokolünü kullanabilirsiniz. Bu protokol, iletişim hatası nedeniyle veri akışı kesintiye uğradıktan sonra yükleme işlemini devam ettirmenize olanak tanır. Özellikle büyük dosyalar aktarıyorsanız ve ağ kesintisi veya başka bir aktarım hatası olasılığı yüksekse (ör. mobil istemci uygulamasından yükleme yaparken) kullanışlıdır. Ayrıca, büyük dosya yüklemelerini baştan başlatmanız gerekmediğinden ağ hataları durumunda bant genişliği kullanımınızı azaltabilir.

Devam ettirilebilir yüklemeyi kullanma adımları şunlardır:

  1. Devam ettirilebilir bir oturum başlatın. Varsa meta verileri içeren yükleme URI'sine ilk istek gönderin.
  2. 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.
  3. 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/farm/v1/animals?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 üst bilgilerini kullanın:

  • X-Upload-Content-Type. Sonraki isteklerde aktarılacak yükleme verilerinin medya MIME türüne ayarlanır.
  • X-Upload-Content-Length. Sonraki isteklerde aktarılacak yükleme verisinin bayt sayısına ayarlanır. İ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ğinin gövdesinde sağlanan bayt sayısına ayarlanır. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.

Her yöntemin kabul edilen medya MIME türleri ve yüklenen dosyalar için boyut sınırlamaları listesi için API referansına bakın.

Örnek: Devam ettirilebilir oturum başlatma isteği

Aşağıdaki örnekte kurgusal Farm API için devam ettirilebilir oturumun nasıl 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, yeniden başlatılabilir ilk güncelleme isteği için istek gövdesini boş bırakın ve Content-Length üst bilgisini 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'nizi belirten bir Location üstbilgisi 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 istek için verilen yanıtı aşağıda bulabilirsiniz:

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ıtta gösterildiği gibi Location başlığının değeri, gerçek dosya yüklemesini 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 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 burada bulabilirsiniz.

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 bir 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ı 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 kesintiye uğrayan yüklemeyi devam ettirme bölümünde açıklanan prosedürü uygulayın.  

Dosyayı parçalara ayırarak 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 olduğundan ve genellikle gerekli olmadığından bu yaklaşım tercih edilmez. Ancak tek bir istekte aktarılan veri miktarını azaltmak için parçalara ayırma işlemini 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österimleri sağlama gibi işlemleri yapmanıza olanak tanır.

Kesintiye uğrayan yüklemeyi devam ettirme

Bir yükleme isteği yanıt almadan 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:

  1. İ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 bir Content-Range üstbilgisi içermelidir.  Örneğin, toplam dosya uzunluğunuz 2.000.000 ise Content-Range değerini */2000000 olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanız Content-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ı olur.

  2. Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, yanıtında Range üst bilgisini kullanarak şu ana kadar hangi baytları aldığını belirtir. Örneğin, 0-299999 öğesinin Range üstbilgisi,dosyanın ilk 300.000 baytının alındığını belirtir.
  3. Kalan verileri yükleyin. Son olarak, isteği nereden devam ettireceğinizi öğrendiğ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 istek, 2.000.000 baytlık dosyanın mevcut konumunun 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ıttan o ana 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ü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 yanıt almadan önce bağlantının kesilmesi durumunda ortaya çıkabilir.

3) Yüklemeyi kaldığı yerden devam ettirin.

Aşağıdaki istek, 43. bayttan itibaren 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 hatalarla ilgili en iyi uygulamalardan bazılarını bilmeniz faydalı olacaktır.

  • 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. Bu hatalar, bir sunucu aşırı yüke giriyorsa 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ınızı sınırlandırın. Örneğin, kodunuz bir hatayı bildirmeden önce on veya daha az yeniden denemeyle sınırlanabilir.
  • Yüklemenin tamamını baştan başlatarak devam ettirilebilir yüklemeler yaparken 404 Not Found ve 410 Gone hatalarını giderin.

Eksponansiyel geri yükleme

Eksponansiyel geri yükleme, istemcinin başarısız bir isteği belirli aralıklarla artan bir süre boyunca yeniden denediği ağ uygulamaları için standart bir hata işleme stratejisidir. Ç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 veya yanıt süreleriyle ilgili olmayan hatalarla başa çıkmak için alakalı 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:

  1. API'ye istek gönderin.
  2. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  3. 1 saniye + random_number_milliseconds bekleyip isteği yeniden deneyin.
  4. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  5. 2 saniye + random_number_milliseconds bekleyip isteği yeniden deneyin.
  6. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  7. 4 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
  8. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alın.
  9. 8 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
  10. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alın.
  11. 16 saniye + rastgele_number_milisaniyelik bir süre bekleyip isteği yeniden deneyin.
  12. Durdur. Hata bildirme veya hata günlüğe kaydetme

Yukarıdaki akışta random_number_milliseconds, 1000'den küçük veya 1000'e eşit olan rastgele bir milisaniye sayısıdır. Küçük bir rastgele gecikme eklemek, yükü daha eşit şekilde dağıtmaya ve sunucunun aşırı yüklenmesini önlemeye yardımcı olduğundan bu işlem 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 5 olduğunda sonlandırılacak şekilde ayarlanmıştır. Bu tavan, istemcilerin sonsuz sayıda yeniden denemesini önler ve bir isteğin "kurtarılamaz bir hata" olarak değerlendirilmesinden önce toplam 32 saniyelik bir 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.

API istemci kitaplığı kılavuzları