Play Games Services Publishing API ile görüntü yükleme

Play Games Services Publishing API, oyun kaynağı için resim yüklemenize olanak tanır.

Yükleme seçenekleri

Play Games Services Publishing API, belirli türde ikili verileri veya medyayı 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 veri türleri.

Yükleme isteği göndermek için aşağıdaki yöntemlerden birini kullanabilirsiniz. uploadType istek parametresini kullanarak kullandığınız yöntemi belirtin.

  • Basit yükleme: uploadType=media. 5 MB veya daha küçük dosyaların hızlı aktarımı için.

  • Çok parçalı yükleme: uploadType=multipart. Küçük dosyaların ve meta verilerin hızlı aktarımı için; dosyayı, tanımlayan 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öntemde, isteğe bağlı olarak meta veri içerebilen bir oturum başlatma isteği kullanırsınız. Bu strateji, yükleme başına bir ek HTTP isteği maliyeti karşılığında daha küçük dosyalar için de çalıştığından çoğu uygulamada kullanılabilecek iyi bir stratejidir.

Medya yüklerken ö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'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/games/v1configuration/images/resourceId/imageType/imageType

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

    Örnek: POST /games/v1configuration/images/resourceId/imageType/imageType

Basit yükleme

Dosya yüklemenin en basit yöntemi, basit bir yükleme isteği göndermektir. Aşağıdaki durumlardan biri geçerliyse bu seçenek iyi bir seçimdir:

  • Dosya, bağlantı başarısız olursa tamamı tekrar yüklenebilecek kadar küçük olmalıdır.

  • Gönderilecek meta veri yok. Bu kaynak için meta verileri ayrı bir istekle göndermeyi planlıyorsanız veya meta veri desteklenmiyorsa 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 gönderin ve uploadType=media sorgu parametresini ekleyin. Örnek:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

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

  • Content-Type. Publishing API referans bölümünde belirtilen, yöntemin kabul ettiği medya veri yükleme türlerinden birine ayarlanır.

  • Content-Length. Yüklediğiniz bayt sayısına ayarlayın. Blok halinde aktarım kodlaması kullanıyorsanız gerekli değildir.

Örnek: Basit yükleme

Aşağıdaki örnekte, Play Games Services Publishing API için basit bir yükleme isteğinin kullanımı gösterilmektedir.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

İstek başarılı olursa sunucu, tüm meta verilerle birlikte HTTP 200 OK durum kodunu döndürür. Örnek:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Çok parçalı yükleme

Yüklenecek verilerle birlikte göndermek istediğiniz meta veriler varsa tek bir multipart/related isteği gönderebilirsiniz. Gönderdiğiniz veriler, bağlantı başarısız olursa tamamının tekrar yüklenebilecek kadar küçükse bu seçenek 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 uploadType=multipart sorgu parametresini ekleyin. Örnek:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

Çok parçalı yükleme isteği gönderirken kullanılacak üst düzey HTTP başlıkları ş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 dizesi ekleyin.

-Content-Length. İstek gövdesinde bulunan 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, çok parçalı/ilgili 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ğin her bir parçası için ek bir Content-Type üst bilgisi gerekir:

  • Meta veri bölümü: İlk sırada gelmelidir ve Content-Type, kabul edilen meta veri biçimlerinden biriyle eşleşmelidir.

  • Medya bölümü: İkinci sırada gelmelidir ve Content-Type, yöntemin kabul ettiği medya MIME türlerinden biriyle eşleşmelidir.

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

Örnek: Çok parçalı yükleme

Aşağıdaki örnekte, Play Games Services Publishing API için çok parçalı yükleme isteği gösterilmektedir.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG 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

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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. Bu özellik ö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. Yükleme URI'sine, varsa meta verileri içeren ilk bir istek gönderin.

  2. Devam ettirilebilir oturum URI'sini kaydedin. İlk istek yanıtında döndürülen oturum URI'sini kaydedin. Bu URI'yi bu oturumdaki diğer istekler için kullanacaksınız. Dosyayı yükleyin.

  3. Medya dosyasını devam ettirilebilir oturum URI'sine gönderin.

Ayrıca, devam ettirilebilir yükleme özelliğini kullanan uygulamaların, kesintiye uğrayan bir yüklemeyi devam ettirmek için kod içermesi gerekir. Yükleme işlemi kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yüklemeyi o noktadan itibaren devam ettirin.

Devam ettirilebilir oturum başlatma

Devam ettirilebilir bir yükleme başlatmak için yöntemin /upload URI'sine POST veya PUT isteği gönderin ve uploadType=resumable sorgu parametresini ekleyin. Örnek:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

Bu başlatma isteği için içerik ya boştur ya da yalnızca meta verileri içerir. Yüklemek istediğiniz dosyanın gerçek içeriğini sonraki isteklerde 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. Bu istek 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. Blok 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ı için Publishing API referansına bakın.

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

Aşağıdaki örnekte, Play Games Services Publishing API için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Yanıtın nasıl ele alınacağı sonraki bölümde açıklanmıştır.

Devam ettirilebilir oturum URI'sini kaydetme

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 başlığı, bu oturumda 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 istek için verilen yanıtı aşağıda bulabilirsiniz:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?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 istekler için kullanabileceğiniz oturum URI'sini kopyalayıp kaydedin.

Dosyayı yükleme

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 arasında Content-Length bulunur. Bu değeri, bu istekte yüklediğiniz bayt sayısına (genellikle yükleme dosyası boyutu) ayarlayın.

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

Mevcut örnekte 2.000.000 baytlık PNG dosyasının tamamını yüklemek için devam ettirilebilir bir istek verilmiştir.

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

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 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ında olduğu gibi bağımsız istekler için sabit bir zaman sınırı olduğunda yararlı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 da olanak tanır.

Verileri parçalara ayırarak yüklüyorsanız tam dosya yüklemeleri için gerekli Content-Length başlığının yanı sıra Content-Range başlığı da gereklidir:

  • Content-Length. Son istekte olduğu gibi, parça boyutuna veya daha azına ayarlanır.

  • Content-Range: Yüklediğiniz dosyanın hangi baytlarını göstereceğini ayarlayın. Örneğin, Content-Range: bytes 0-524287/2000000, 2.000.000 baytlık bir dosyanın ilk 524.288 baytını (256 x 1024 x 2) sağladığınızı gösterir.

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. Kesintiye uğrayan bir yüklemeyi devam ettirmek için aşağıdakileri yapın:

  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 başlıkları, dosyadaki mevcut konumun bilinmediğini belirten bir Content-Range başlığı 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 parametresini */* olarak ayarlayın.

  2. Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, yanıtında Range üstbilgisini kullanarak şu ana kadar hangi baytları aldığını belirtir. Örneğin, 0-299999 değerine sahip bir Range başlığı,dosyanın ilk 300.000 baytının alındığını gösterir.

  3. Kalan verileri yükleyin. Son olarak, isteği nereden devam ettireceğinizi bildiğinize göre kalan verileri veya mevcut parçayı gönderin. Her iki durumda da kalan verileri ayrı bir parça olarak ele almanız gerektiğini unutmayın. Bu nedenle, yüklemeye devam ettiğ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 üstbilgisini kullanır.

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

  2. Yanıttan şu ana kadar yüklenen bayt sayısını ayıklayın. Sunucunun yanıtında, dosyanın ilk 43 baytını aldığını belirtmek için Range başlığı 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

  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

Hata işleme

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 5xx hataları nedeniyle başarısız olan yüklemeleri devam ettirin ya da tekrar deneyin:

    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

  • Yükleme isteklerinin 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. Üretken geri çekilme, istek hacminin yüksek olduğu veya ağ trafiğinin yoğun olduğu dönemlerde bu tür sorunları azaltmaya yardımcı olabilir.

  • Diğer istek türleri üstel geri çekilme ile ele alınmamalıdır ancak bunların bir kısmını tekrar deneyebilirsiniz. Bu istekleri yeniden denediğinizde, yeniden deneme sayısını sınırlayın. Örneğin, kodunuz bir hatayı bildirmeden önce on veya daha az yeniden denemeyle sınırlanabilir.

  • Devam ettirilebilir yüklemeler yaparken tüm yüklemeyi baştan başlatarak 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 artan bir süre boyunca düzenli olarak 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 bu hataları ele almak için üstel geri çekilme 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 hataları ele almak için alakalı bir strateji değildir.

Doğru ş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ı ortamlardaki isteklerin veri hızını en üst düzeye çıkarır.

Basit eksponansiyel geri yüklemeyi 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 + random_number_milliseconds bekleyip isteği yeniden deneyin.
  8. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 response alırsınız.
  9. 8 saniye + random_number_milliseconds bekleyip isteği yeniden deneyin.
  10. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 response alırsınız.
  11. 16 saniye + random_number_milliseconds bekleyip isteği yeniden deneyin.
  12. Durdur. Hata bildirme veya hata günlüğe kaydetme

Yukarıdaki listede random_number_milliseconds, 1000'den küçük veya 1000'e eşit rastgele bir milisaniye sayısıdır. Küçük bir rastgele gecikme eklemek, yükü daha eşit şekilde dağıtmaya ve sunucunun tıkanmasını önlemeye yardımcı olduğundan bu işlem gereklidir. random_number_milliseconds değerinin her bekleme işleminden sonra yeniden tanımlanması gerekir.

Algoritma, n 5 olduğunda sonlandırılacak şekilde ayarlanmıştır. Bu tavan, istemcilerin sonsuz sayıda yeniden denemesini engeller ve bir isteğin "kurtarılamaz hata" olarak değerlendirilmesinden önce toplam 32 saniyelik bir gecikmeye neden olur. Özellikle uzun bir yükleme işlemi devam ediyorsa daha fazla sayıda yeniden deneme ayarlayabilirsiniz. Tekrar deneme süresini makul bir değere (ör. bir dakikadan kısa) ayarladığınızdan emin olun.

API istemci kitaplığı kılavuzları