Medya Yükleme

Medya yükleme özelliği, Campaign Manager 360 API'sinin verileri bulutta depolamasına ve sunucuda kullanılabilir hale getirmesine olanak tanır. Fotoğraf, video, PDF dosyası, zip dosyası veya diğer tüm veri türlerini yüklemek isteyebileceğiniz veri türleri şunlardır.

Bu belgede, kurgusal bir çiftlik API'si için medya yükleme kullanımını gösteren örnekler bulunmaktadır. Ancak, aynı kavramlar Campaign Manager 360 API'si için geçerlidir.

Yükleme seçenekleri

Campaign Manager 360 API'si, belirli türde ikili veri veya medya yüklemenize olanak tanır. Yükleyebileceğiniz verilerin özellikleri, medya yüklemelerini destekleyen yöntemler için 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 türleri.

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. Örneğin, 5 MB veya daha küçük boyutlu daha küçük dosyaların hızlı bir şekilde aktarılması için.
  • Çok parçalı yükleme: uploadType=multipart. Küçük dosyaların ve meta verilerin hızlı aktarımı için; dosyayı açıklayan meta verilerle 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öntemle, isteğe bağlı olarak meta verileri içerebilen bir oturum başlatma isteği kullanırsınız. Bu, yükleme başına bir ek HTTP isteği maliyetiyle daha küçük dosyalarda da çalıştığından çoğu uygulama için iyi bir stratejidir.

Medya yüklerken özel bir URI kullanırsınız. Medya yüklemelerini destekleyen yöntemler iki URI uç noktasına sahiptir:

  • Medya için /upload URI'sı. Yükleme uç noktasının biçimi, "/upload" önekine sahip standart kaynak URI'sıdır. Medya verilerini aktarırken bu URI'yi kullanın.

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

  • Meta veriler için standart kaynak URI'sı. Kaynak herhangi bir veri alanı içeriyorsa bu alanlar, yüklenen dosyayı açıklayan meta verileri depolamak için kullanılır. Meta veri değerlerini oluştururken veya güncellerken bu URI'yı kullanabilirsiniz.

    Örnek: POST /farm/v1/animals

Basit yükleme

Dosya yüklemek için en basit yöntem basit bir yükleme isteğinde bulunmaktır. Bu seçenek, aşağıdaki durumlarda iyi bir seçenektir:

  • Dosya, bağlantı başarısız olursa tamamen yeniden yüklenebilecek kadar küçüktür.
  • Gönderilecek meta veri yok. Bu kaynak için meta verileri ayrı bir istekte göndermeyi planlıyorsanız veya meta veriler desteklenmiyorsa ya da kullanılabilir değilse doğru olabilir.

Basit yüklemeyi kullanmak için yöntemin /upload URI'sine bir POST veya PUT isteğinde bulunun ve sorgu parametresini ekleyin uploadType=media. Örneğin:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

Basit bir yükleme isteğinde bulunurken kullanılacak HTTP üstbilgileri şunlardır:

  • Content-Type. API referansında belirtilen yöntemin kabul edilen medya yükleme veri türlerinden birine ayarlanır.
  • Content-Length. Yüklediğiniz bayt sayısını seçin. Parçalı aktarım kodlamasını 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, 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 yeniden yüklenebilecek kadar küçükse bu iyi bir seçimdir.

Çok parçalı yüklemeyi kullanmak için yöntemin /upload URI'sine bir POST veya PUT isteği gönderin ve aşağıdaki gibi sorgu parametresini ekleyin: uploadType=multipart:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

Çok parçalı yükleme isteğinde bulunurken 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övdesinde toplam bayt sayısına ayarlanır. İ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 üst bilgisi gerekir:

  1. Meta veri bölümü: İlk önce giriş yapılmalıdır 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 bir yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyalar için boyut sınırları için API referansını inceleyin.

Not: Yalnızca ilişkili verileri yüklemeden 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 kurgusal Farm API için çok parçalı 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, 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ı nedeniyle veri akışı kesintiye uğradıktan sonra yükleme işlemini devam ettirmenizi sağlar. Bu, özellikle büyük dosyalar aktarıyorsanız ve örneğin bir mobil istemci uygulamasından yükleme yaparken ağ kesintisi veya başka bir iletim hatası ihtimalinin yüksek olduğu durumlarda yararlıdır.

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

  1. Devam ettirilebilir bir oturum başlatın. Meta verileri içeren yükleme URI'sına (varsa) ilk istek yapın.
  2. Devam ettirilebilen oturum URI'sini kaydedin. İlk isteğin yanıtında döndürülen oturum URI'sini kaydedin; bu oturumda kalan istekler için kullanılır.
  3. Dosyayı yükleyin. Medya dosyasını devam ettirilebilen oturum URI'sine gönderin.

Ek olarak, devam ettirilebilir yükleme özelliğini kullanan uygulamaların sonlandırılmış bir yüklemeyi devam ettirmek için koda sahip olması gerekir. Bir yükleme kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yükleme işlemini bu noktadan itibaren devam ettirin.

Not: Bir 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 aşağıdaki gibi sorgu parametresini ekleyin: uploadType=resumable:

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üne ayarlayın.
  • X-Upload-Content-Length. Sonraki isteklerde aktarılacak bayt veri sayısını ayarlayın. İsteğin yapıldığı tarihte uzunluk bilinmiyorsa bu başlığı atlayabilirsiniz.
  • Meta veri sağlanıyorsa: Content-Type. Meta verinin veri türüne göre ayarlayın.
  • Content-Length. Bu ilk isteğin gövdesinde sağlanan bayt sayısına ayarlayın. Parçalı aktarım kodlamasını kullanıyorsanız gerekli değildir.

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

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

Aşağıdaki örnekte, Hayali Ç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 edilebilir 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 ettirilebilen oturum URI'sini kaydedin

Oturum başlatma isteği başarılı olursa API sunucusu bir 200 OK HTTP durum koduyla yanıt verir. Ayrıca, devam ettirilebilir oturum URI'nizi 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 bir upload_id sorgu parametresi bölümü içerir.

Örnek: Devam ettirilebilir oturum başlatma yanıtı

Aşağıda, 1. adımdaki isteğe yanıt 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ıtta gösterildiği gibi Location üstbilgisinin değeri, gerçek dosya yüklemesini gerçekleştirmek veya yükleme durumunu sorgulamak için HTTP uç noktası olarak kullanacağınız oturum URI'sidir.

Oturum URI'sini kopyalayıp sonraki isteklerde kullanmak için 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 isteklerinde kullanılacak HTTP üstbilgileri Content-Length değerini içerir. Bunu, genellikle yükleme dosyasının boyutu olan bu istekte yüklediğiniz bayt sayısına ayarlayın.

Örnek: Devam ettirilebilir dosya yükleme isteği

Mevcut örnek için 2.000.000 baytlık JPEG dosyasının tamamını yüklemeye devam ettirilebilir bir istek.

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şkilendirilen tüm meta verilerle birlikte bir HTTP 201 Created ile yanıt verir. Devam ettirilebilir oturumun ilk isteği PUT ise mevcut bir kaynağı güncellemek için bu kaynakla ilişkilendirilen tüm meta verilerle birlikte yanıt yanıtı da 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 kesilen bir yüklemeyi devam ettirme bölümünde açıklanan prosedürü izleyin.  

Dosyayı parçalara yükleme

Devam ettirilebilir yüklemelerle bir dosyayı parçalara bölebilir ve her parçayı sırayla yüklemek için bir dizi istek gönderebilirsiniz. Ek isteklerle ilgili performans maliyetleri olduğundan ve genellikle gerekli olmadığından bu tercih edilen yaklaşım değildir. Ancak, tek bir istekte aktarılan veri miktarını azaltmak için veri parçalarını kullanmanız gerekebilir. Bu, belirli Google App Engine istek sınıfları için olduğu gibi, tek tek istekler için belirli bir süre sınırı olduğunda kullanışlıdır. Ayrıca, varsayılan olarak yükleme ilerleme 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ğramış yüklemeleri devam ettirme

Bir yanıt isteği yanıt verilmeden önce sonlandırılırsa veya sunucudan bir 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 üstbilgilerinde, dosyadaki geçerli konumun bilinmiyor olduğunu belirten bir Content-Range üst bilgisi bulunmalıdır. Örneğin, toplam dosya süreniz 2.000.000 ise Content-Range değerini */2000000 olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanız Content-Range değerini */* olarak ayarlayın.

    Not: Sadece yüklemenin kesintiye uğramaması durumunda parçalar arasındaki durumu isteyebilirsiniz. Bu, örneğin eski tarayıcılar için yükleme ilerleme göstergelerini göstermek istediğinizde yararlıdır.

  2. Yüklenen bayt sayısını alabilirsiniz. Yanıtı durum sorgusundan işleme koyun. Sunucu, yanıtında şu ana kadar hangi baytları aldığını belirtmek için Range üstbilgisini kullanır. Örneğin, 0-299999 üst bilgisinin Range üst bilgisi,dosyanın ilk 300.000 baytının alındığını gösterir.
  3. Kalan verileri yükleyin. Son olarak, isteği devam ettireceğinizi bildiğinize göre, kalan verileri veya mevcut parçayı gönderin. Geri kalan verileri her iki durumda da ayrı bir bölüm olarak ele almanız gerektiğini unutmayın. Bu nedenle, yüklemeyi devam ettirdiğinizde Content-Range üstbilgisini göndermeniz gerekir.
Örnek: Kesintili bir yüklemeyi devam ettirme

1) Yükleme durumunu isteyin.

Aşağıdaki istek, 2.000.000 bayt dosyasının mevcut konumunun bilinmediğini belirtmek için Content-Range üstbilgisini kullanır.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Yanıttan şimdiye kadar yüklenen bayt sayısını çıkarın.

Sunucunun yanıtı, dosyanın şimdiye kadarki ilk 43 baytı aldığını belirtmek için Range üstbilgisini kullanır. Devam eden yüklemeyi nereden başlatacağınızı 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 işlemi tamamlandıysa durum yanıtı 201 Created veya 200 OK olabilir. Bu durum, bağlantı tüm baytlar yüklendikten sonra ancak istemci sunucudan yanıt almadan önce bozulmuşsa olabilir.

3) Yükleme işlemini kaldığı yerden devam ettirin.

Aşağıdaki istek, dosyanın kalan baytlarını 43 bayttan başlayarak göndererek yükleme işlemini 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 gidermeyle ilgili bazı en iyi uygulamaların farkında olmak faydalıdır.

  • Aşağıdakiler dahil olmak üzere, bağlantı kesintileri veya 5xx hataları 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 üstel geri çekilme stratejisi kullanın. Bu hatalar, bir sunucu aşırı yüklüyse ortaya çıkabilir. Üstel geri çekilme, yüksek hacimli istek veya yoğun ağ trafiği gibi durumlarda bu tür sorunları gidermenize yardımcı olabilir.
  • Diğer istek türleri, eksponansiyel geri yükleme tarafından işlenmemelidir, ancak istek sayısını tekrar deneyebilirsiniz. Bu istekleri yeniden denediğinizde bu işlemlerin sayısını sınırlandırın. Örneğin, kodunuz bir hata bildirmeden önce en fazla on tekrarla sınırlandırabilir.
  • Sürdürülebilir yüklemeler yaparken yüklemenin tamamını baştan başlatarak 404 Not Found ve 410 Gone hatalarını giderin.

Eksponansiyel geri yükleme

Üstel geri yükleme, istemcinin başarısız olan bir isteği zaman içinde belirli bir sıklıkta yeniden denemesini sağlayan 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 eksponansiyel geri yükleme, bu hataların işlenmesi için iyi bir strateji olabilir. Buna karşılık, geçersiz ağ kimlik bilgileri veya dosya bulunamadı hataları gibi ağ hacmi veya yanıt süreleriyle ilgili hataları ele almak için alakalı bir strateji değildir.

Doğru bir şekilde kullanıldığında üstel geri çekilme, 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 eksponansiyel geri yükleme uygulama akışı aşağıdaki gibidir:

  1. API'ye istekte bulunun.
  2. HTTP 503 yanıtı alın. Bu, isteği yeniden denemeniz gerektiğini gösterir.
  3. 1 saniye + rastgele_sayı_millisaniye saniyeyi bekleyin ve isteği yeniden deneyin.
  4. HTTP 503 yanıtı alın. Bu, isteği yeniden denemeniz gerektiğini gösterir.
  5. 2 saniye + rastgele_sayı_millisaniye saniyeyi bekleyin ve isteği yeniden deneyin.
  6. HTTP 503 yanıtı alın. Bu, isteği yeniden denemeniz gerektiğini gösterir.
  7. 4 saniye bekleyin + rastgele_sayı_millisaniye; isteği yeniden deneyin.
  8. HTTP 503 yanıtı alın. Bu, isteği yeniden denemeniz gerektiğini gösterir.
  9. 8 saniye + rastgele_sayı_millisaniye saniye bekleyin ve isteği yeniden deneyin.
  10. HTTP 503 yanıtı alın. Bu, isteği yeniden denemeniz gerektiğini gösterir.
  11. 16 saniye + rastgele_sayı_millisaniye saniyeyi bekleyin ve isteği yeniden deneyin.
  12. Durdur. Hataları bildirin veya günlüğe kaydedin.

Yukarıdaki akışta, rastgele_sayı_millisaniye değeri 1000'den küçük veya 1000'e eşit, milisaniye cinsinden rastgele bir sayıdır. Küçük bir rastgele gecikme eklemek, yükü daha eşit sıklıkta dağıtmaya ve sunucuyu damgalama olasılığını önlemeye yardımcı olduğundan bu gereklidir. Rastgele_sayı_millisaniye değeri, her beklemeden sonra yeniden tanımlanmalıdır.

Not: Bekleme süresi her zaman (2 ^ n) + rastgele_sayı_millisaniyedir. Burada n, 0 olarak tanımlanan tek renkli bir tam sayıdır. n tam sayısı her iterasyon için 1'er artar (her istek).

Algoritma, n 5 olduğunda sonlandırılacak şekilde ayarlanmıştır. Bu tavan, müşterilerin sonsuz bir şekilde yeniden deneme yapmasını engeller ve bir isteğin "kurtarılamaz bir hata" olarak değerlendirilmesinden önce yaklaşık 32 saniyelik bir gecikme yaşanır. Özellikle uzun bir yükleme devam ediyorsa, maksimum sayıda daha fazla yeniden deneme yapılmasında bir sakınca yoktur. Ancak yeniden deneme gecikmesini, örneğin bir dakikadan kısa bir süre içinde sınırlandırdığınızdan emin olun.

API istemci kitaplığı kılavuzları