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ürlerdeki ikili verileri veya medyaları yüklemenize olanak tanır. Yükleyebileceğiniz verilerin özellikleri, medya yüklemelerini destekleyen tüm yöntemlerin referans sayfasında belirtilir:

  • Maksimum yükleme dosyası boyutu: Bu yöntemle depolayabileceğiniz maksimum veri miktarı.

  • Kabul edilen medya MIME türleri: Bu yöntemle depolayabileceğiniz ikili veri türleri.

Yükleme isteklerini aşağıdaki yöntemlerden herhangi biriyle yapabilirsiniz. uploadType istek parametresiyle kullandığınız yöntemi belirtin.

  • Kolay yükleme: uploadType=media. Daha küçük dosyaların (ör. 5 MB veya daha az) hızlı aktarımı için.

  • Çok parçalı yükleme: uploadType=multipart. Daha küçük dosyaların ve meta verilerin hızlı aktarımı için kullanılır. Dosyayı, meta verileriyle birlikte tek bir istekte aktarır.

  • Yüklemeye devam etme: uploadType=resumable. Özellikle daha büyük dosyalar için güvenilir aktarım sağlar. Bu yöntemde, isteğe bağlı olarak meta veriler içerebilen bir oturum başlatma isteği kullanırsınız. Bu, çoğu uygulama için iyi bir stratejidir. Yükleme başına bir ek HTTP isteği maliyetiyle daha küçük dosyalar için de çalışır.

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" önekine 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 herhangi bir veri alanı 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ğinde bulunmaktır. Aşağıdaki durumlardan biri geçerliyse bu seçenek iyi bir tercihtir:

  • Bağlantı başarısız olursa dosya, tamamı 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ılamıyorsa 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. Örneğin:

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

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

  • Content-Type. Yayınlama API'si referansında belirtilen, yöntemin kabul ettiği yükleme medya 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, 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, HTTP 200 OK durum kodunu ve tüm meta verileri döndürür. Örneğin:

HTTP/1.1 200
Content-Type: application/json

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

Çok parçalı yükleme

Yüklemek istediğiniz verilerle birlikte göndermek istediğiniz meta veriler varsa tek bir multipart/related isteği oluşturabilirsiniz. Gönderdiğiniz veriler, bağlantı başarısız olursa tekrar yüklenmeye 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 gönderin ve uploadType=multipart sorgu parametresini ekleyin. Örneğin:

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

Çok parçalı yükleme isteğinde bulunurken kullanılacak üst düzey HTTP başlıkları şunlardır:

-Content-Type. multipart/related 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 ayarlanır. İsteğin medya kısmı, bu yöntem için belirtilen maksimum dosya boyutundan küçük olmalıdır.

İsteğin gövdesi, multipart/related içerik türü olarak biçimlendirilmiştir RFC2387 ve tam olarak iki bölüm içerir. Parçalar bir sınır dizesiyle tanımlanır ve son sınır dizesini iki kısa çizgi izler.

Çok parçalı isteğin her bölümü için ek bir Content-Type üstbilgisi 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 sırada olmalı 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ın boyut sınırları için Yayınlama API'si referansına bakın.

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

Aşağıdaki örnekte, Play Games Hizmetleri Publishing API'si için çok parçalı bir 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, HTTP 200 OK durum kodunu ve tüm meta verileri 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şlemine devam etmenize olanak tanır. Özellikle büyük dosyalar aktarıyorsanız ve ağ kesintisi veya başka bir iletim hatası olasılığı yüksekse (ör. mobil istemci uygulamasından yükleme yaparken) bu özellik çok işinize yarar. 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ı da 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 isteği 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 URI'yi kullanacaksınız. Dosyayı yükleyin.

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

Ayrıca, devam ettirilebilir yüklemeyi kullanan uygulamalarda, kesintiye uğrayan yüklemeyi devam ettirecek kod bulunmalıdır. Yükleme işlemi kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yüklemeye bu noktadan itibaren devam edin.

Devam ettirilebilir bir oturum başlatma

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

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

Bu başlatma isteğinde metin 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 istekte aşağıdaki HTTP üstbilgilerini 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 verilerinin bayt sayısı olarak 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 ayarlayın.

  • Content-Length. Bu ilk isteğin gövdesinde sağlanan bayt sayısına ayarlanır. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.

Yüklenen dosyalar için kabul edilen medya MIME türlerinin ve boyut sınırlarının her yöntemdeki listesi için Publishing API referansına bakın.

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

Aşağıdaki örnekte, Play Games Hizmetleri Yayınlama API'si 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 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ımda verilen isteğe ilişkin yanıt:

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ükleme işlemini yapmak veya yükleme durumunu sorgulamak için HTTP uç noktası olarak kullanacağınız oturum URI'sidir.

Oturum URI'sini kopyalayıp kaydedin. Böylece, sonraki isteklerde kullanabilirsiniz.

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 şöyledir:

PUT session_uri

Devam ettirilebilir dosya yükleme istekleri oluşturulurken kullanılacak HTTP başlıkları şunlardır: Content-Length. Bunu, bu isteğe yüklediğiniz bayt sayısına (genellikle yükleme dosyasının boyutu) ayarlayın.

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

Mevcut örnek için 2.000.000 baytlık PNG dosyasının tamamını yüklemeye yönelik devam ettirilebilir bir istek aşağıda 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 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 başlıklı makalede belirtilen prosedürü uygulayın.

Dosyayı parçalar halinde yükleme

Devam ettirilebilir yüklemeler sayesinde 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çalama kullanmanız gerekebilir. Bu, belirli Google App Engine istek sınıflarında olduğu gibi, bağımsız istekler için sabit bir süre sınırı olduğunda faydalıdır. Ayrıca, yükleme ilerleme durumu desteği varsayılan olarak bulunmayan eski tarayıcılarda yükleme ilerleme durumu göstergeleri sağlama gibi işlemler yapmanıza da olanak tanır.

Verileri parçalar halinde yüklüyorsanız tam dosya yüklemeleri için gerekli olan 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 küçük bir değere ayarlayın.

  • Content-Range: Yüklediğiniz dosyadaki hangi baytların gösterileceğini ayarlayın. Örneğin, Content-Range: bytes 0-524287/2000000, 2.000.000 baytlık bir dosyada ilk 524.288 baytı (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 alınmadan önce sonlandırılırsa veya sunucudan HTTP 503 Service Unavailable yanıtı alırsanız kesintiye uğrayan yüklemeye devam etmeniz 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'i */* 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, Range başlığı 0-299999,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 değerlendirmeniz gerektiğini ve yüklemeye devam ettiğinizde Content-Range üstbilgisini göndermeniz gerektiğini unutmayın.

Örnek: Kesintiye uğrayan bir yüklemeyi devam ettirme

  1. Yükleme durumunu isteyin. Aşağıdaki istek, 2.000.000 baytlık dosyada geçerli 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. Şu ana kadar yüklenen bayt sayısını yanıttan ayıklayın. Sunucunun yanıtı, dosyanın ilk 43 baytının alındığını belirtmek için Range başlığını kullanır. Devam ettirilen yüklemenin nereden başlatılacağını belirlemek için Range üstbilgisinin üst değerini kullanın.

    HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

  3. Yüklemeye kaldığı yerden devam edin. Aşağıdaki istek, dosyanın kalan baytlarını 43. bayttan başlayarak göndererek yüklemeye devam eder.

    PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Hata işleme

Medya yüklerken hata işleme ile ilgili bazı en iyi uygulamaları bilmek faydalıdır.

  • Aşağıdakiler de 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 herhangi bir 5xx sunucu hatası döndürülürse eksponansiyel geri yükleme stratejisi kullanın. Bu hatalar, bir sunucu aşırı yüklendiğinde ortaya çıkabilir. Üstel geri çekilme, yüksek istek hacmi veya yoğun ağ trafiği dönemlerinde bu tür sorunların hafifletilmesine yardımcı olabilir.

  • Diğer istek türleri üstel geri çekilme ile işlenmemelidir ancak yine de bazılarını yeniden deneyebilirsiniz. Bu istekleri yeniden denerken deneme sayısını sınırlayın. Örneğin, kodunuz bir hatayı bildirmeden önce yeniden deneme sayısını on veya daha az ile sınırlayabilir.

  • Yüklemenin tamamını baştan başlatarak devam ettirilebilir yükleme yaparken 404 Not Found ve 410 Gone hatalarını giderin.

Eksponansiyel geri yükleme

Eksponansiyel geri yükleme, ağ uygulamaları için standart bir hata işleme stratejisidir. Bu stratejide istemci, başarısız olan bir isteği belirli aralıklarla tekrar denerken her deneme arasındaki süreyi artırır. Çok sayıda istek veya yoğun ağ trafiği nedeniyle sunucu hatalar döndürüyorsa bu hataları işlemek için üstel geri çekilme iyi bir strateji olabilir. Bununla birlikte, geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları gibi ağ hacmi ya da yanıt süreleriyle ilgili olmayan hatalarla başa çıkmak için uygun bir strateji değildir.

Üstel geri çekilme, doğru kullanıldığında 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üklemeyi uygulama akışı aşağıdaki gibidir:

  1. API'ye istek gönderme
  2. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  3. 1 saniye + random_number_milliseconds bekleyin ve 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 bekleyin ve 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 bekleyin ve isteği yeniden deneyin.
  8. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 response alın.
  9. 8 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  10. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 response alın.
  11. 16 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  12. Durdur. Hata bildirme veya günlüğe kaydetme

Yukarıdaki listede random_number_milliseconds, 1.000'den küçük veya 1.000'e eşit rastgele bir milisaniye sayısıdır. Küçük bir rastgele gecikme eklemek, yükün daha eşit şekilde dağıtılmasına ve sunucunun aşırı yüklenmesini önlemeye yardımcı olduğundan bu gereklidir. random_number_milliseconds değeri her beklemeden sonra yeniden tanımlanmalıdır.

Algoritma, n 5 olduğunda sonlandırılacak şekilde ayarlanmıştır. Bu sınır, istemcilerin sonsuza kadar yeniden denemesini önler ve bir isteğin "kurtarılamayan bir hata" olarak kabul edilmesinden önce toplamda yaklaşık 32 saniyelik bir gecikmeye neden olur. Maksimum yeniden deneme sayısının yüksek olması, özellikle uzun bir yükleme işlemi devam ediyorsa sorun teşkil etmez. Ancak yeniden deneme gecikmesini makul bir süreyle (ör. bir dakikadan kısa) sınırladığınızdan emin olun.

API istemci kitaplığı kılavuzları