Resimler Yükleniyor

Play Games Services Publishing API ile oyun kaynakları için resim yükleyebilirsiniz.

Yükleme seçenekleri

Play Games Services Publishing API ile belirli türlerdeki ikili verileri veya medyaları yükleyebilirsiniz. Yükleyebileceğiniz verilerin özellikleri, medya yüklemelerini destekleyen tüm yöntemler için 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öntemi kullanarak depolayabileceğiniz ikili veri 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. 5 MB veya daha küçük boyutlu dosyaların daha hızlı aktarılması için.
  • Çok parçalı yükleme: uploadType=multipart. Küçük boyutlu dosyaların ve meta verilerin hızlı aktarımı için tek bir istekte dosyayı açıklayan meta veriler ile birlikte.
  • Devam ettirilebilir yükleme: uploadType=resumable. Özellikle büyük dosyalarda önemli olan güvenilir aktarım için. Bu yöntemle, isteğe bağlı olarak meta verileri içerebilen bir oturum başlatma isteği kullanırsınız. Yükleme başına bir HTTP isteği karşılığında daha küçük dosyalarda da çalıştığından bu yöntem, çoğu uygulama için iyi bir stratejidir.

Medya yüklerken özel bir URI kullanırsınız. Aslında, 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'sidir. Medya verilerini 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'yı 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 durumlarda bu seçenek sizin için uygundur:

  • Bağlantı başarısız olursa dosyanın 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 desteklenen ya da kullanılabilir bir meta veri yoksa bu durum geçerli olabilir.

Basit yüklemeyi kullanmak için yöntemin /upload URI'sine POST veya PUT isteğinde bulunun ve sorgu parametresini uploadType=media 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 üstbilgileri şunlardır:

  • Content-Type. API referansında belirtilen yöntemin kabul edilen yükleme medya veri türlerinden birine ayarlanır.
  • Content-Length. Yüklediğiniz baytların sayısını girin. Parçalı aktarım kodlamasını 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ği kullanılmaktadır.

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, 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
}

Ç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 olduğu takdirde tamamen tekrar yüklenebilecek kadar küçükse bu iyi bir seçenektir.

Çok parçalı yüklemeyi kullanmak için yöntemin /upload URI'sine bir POST veya PUT isteğinde bulunun ve sorgu parametresini (uploadType=multipart) ekleyin. Örneğin:

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

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

  • Content-Type. Çok parçalı/alakalı olarak ayarlayın ve isteğin parçalarını 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 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ü [RFC2387] olarak biçimlendirilir ve tam olarak iki bölüm içerir. 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 bir bölümü için ek bir Content-Type üst bilgisi gerekir:

  1. Meta veri bölümü: Önce meta veri gelmeli 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 ettiği medya MIME türlerinden biriyle eşleşmelidir.

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

Not: Meta veri bölümünü oluşturmak veya güncellemek için, ilişkili verileri yüklemeden standart kaynak uç noktasına POST veya PUT isteği göndermeniz yeterlidir: https://www.googleapis.com/games/v1configuration/images/resourceId/imageType/imageType

Ö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, 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 arızası veri akışını kesintiye uğrattıktan sonra bir yükleme işlemini devam ettirmenize olanak tanır. Bu, özellikle büyük dosyaları aktardığınız durumlarda ve örneğin bir mobil istemci uygulamasından yükleme yaparken ağ kesintisi veya başka bir iletim hatasının yüksek olması durumunda yararlıdır. Ayrıca, büyük dosya yüklemelerini baştan başlatmanıza gerek olmadığı için ağ arızaları 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. Meta verileri içeren yükleme URI'sine (varsa) 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 oturumu, kalan istekler için kullanırsınız.
  3. Dosyayı yükleyin. Medya dosyasını devam ettirilebilir oturum URI'sine gönderin.

Buna ek olarak, devam ettirilebilen yükleme kullanan uygulamaların kesilen bir yüklemeyi devam ettirmek için koda sahip olması gerekir. Yükleme kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve bu noktadan itibaren yüklemeyi 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 (uploadType=resumable) ekleyin. Örneğin:

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

Bu başlatma isteği için gövde boş veya yalnızca meta verileri içeriyor; sonraki isteklerde, yüklemek istediğiniz dosyanın asıl içeriğini aktaracaksınız.

İlk istekle birlikte aşağıdaki HTTP başlıklarını 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 yükleme verilerinin bayt sayısı olarak ayarlayın. İstek şu anda bilinmiyorsa bu başlığı atlayabilirsiniz.
  • Meta veri sağlıyorsanız: 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 yöntemin kabul edilen medya MIME türlerinin listesi ve yüklenen dosyaların boyut sınırları için 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
}

Not: Meta veri içermeyen ilk devam ettirilebilir 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 kullanılacağı açıklanır.

2. Adım: Devam ettirilebilir 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'nızı belirten bir Location başlığı 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 isteğe ilişkin 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 üst bilgisinin 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 kullanabilmeniz 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:

PUT session_uri

Devam ettirilebilir dosya yükleme istekleri sırasında kullanılacak HTTP üstbilgileri Content-Length öğesini içerir. Bunu, bu istekte yüklediğiniz bayt sayısına (genellikle yükleme dosyasının boyutudur) 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üklemek için devam ettirilebilir bir isteği burada bulabilirsiniz.

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 meta verilerle birlikte HTTP 201 Created yanıtı verir. Devam ettirilebilir oturumun ilk isteği PUT ise mevcut bir kaynağı güncellemek için bu kaynakla ilişkilendirilen meta verilerle birlikte başarı yanıtı 200 OK olur.

Yükleme isteği kesilirse veya sunucudan HTTP 503 Service Unavailable ya da başka bir 5xx yanıtı alırsanız kesilen yüklemeyi devam ettirme bölümünde açıklanan prosedürü uygulayın.  


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 yaklaşım tercih edilmez. Ancak, tek bir istekte aktarılan veri miktarını azaltmak için parçalama özelliğini kullanmanız gerekebilir. Bu, belirli Google App Engine istek sınıflarında olduğu gibi, tek tek istekler için sabit bir zaman sınırı olduğunda yararlıdır. Ayrıca, varsayılan olarak yükleme ilerleme desteği olmayan eski tarayıcılar için yükleme ilerleme durumu göstergelerini sağlama gibi işlemler yapmanıza da olanak tanır.


Kesintiye uğramış bir yüklemeyi devam ettirme

Yükleme isteği yanıt almadan önce feshedilirse 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'sına boş bir PUT isteği göndererek yüklemenin mevcut durumunu sorgulayın. Bu istek için HTTP başlıkları, dosyadaki geçerli konumun bilinmediğini belirten bir Content-Range üst bilgisi içermelidir. Ö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 öğesini */* olarak ayarlayın.

    Not: Sadece yükleme işlemi kesintiye uğrarsa değil, parçalar arasında durum isteğinde bulunabilirsiniz. Bu özellik, örneğin eski tarayıcılar için yükleme ilerleme durumu göstergelerini göstermek istiyorsanız yararlıdır.

  2. Yüklenen bayt sayısını öğrenin. Durum sorgusundan yanıtı işleyin. Sunucu, yanıtında şimdiye kadar aldığı baytları belirtmek için Range üstbilgisini kullanır. Örneğin, 0-299999 üst bilgisinin Range üst bilgisi,dosyanın ilk 300.000 baytını alındığını gösterir.
  3. Kalan verileri yükleyin. Son olarak, isteği nerede devam ettireceğinizi öğrendiğinize göre, kalan verileri veya mevcut parçayı gönderin. Her iki durumda da kalan verileri ayrı bir grup olarak ele almanız gerektiğini unutmayın. Bu nedenle, yüklemeyi devam ettirdiğinizde Content-Range üstbilgisini göndermeniz gerekir.
Örnek: Kesilen 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 o ana kadar yüklenen bayt sayısını çıkarın.

Sunucunun yanıtı, dosyanın şu ana kadar ilk 43 baytını aldığını belirtmek için Range üstbilgisini kullanır. Devam ettirilen yüklemeyi nereden başlatacağı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 işlemi 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ı bozulduysa meydana gelebilir.

3) Yükleme işlemine kaldığı yerden devam edin.

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 işlemeyle ilgili bazı en iyi uygulamaları bilmeniz yararlı olacaktır.

  • Bağlantı kesintileri veya 5xx hataları nedeniyle başarısız olan yüklemeleri devam ettirin ya da yeniden deneyin. Örneğin:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Yükleme isteklerini devam ettirirken veya yeniden denerken 5xx sunucu hatası döndürülürse üstel geri yükleme stratejisi kullanın. Sunucu aşırı yüklenirken bu hatalar ortaya çıkabilir. Üstel geri çekilme, yoğun istek veya yoğun ağ trafiği dönemlerinde bu tür sorunları gidermeye yardımcı olabilir.
  • Diğer istek türleri eksponansiyel geri yükleme ile işlenmemelidir ancak bunların belirli bir sayısını yeniden deneyebilirsiniz. Bu istekleri yeniden denerken ilgili istek sayısını sınırlayın. Örneğin, kodunuz bir hatayı bildirmeden önce on deneme veya daha kısa sayıyla sınırlanabilir.
  • Devam ettirilebilir yüklemeler yaparken, yüklemenin tamamını baştan başlayarak 404 Not Found ve 410 Gone hatalarını giderin.

Eksponansiyel geri yükleme

Üstel geri yükleme, istemcinin başarısız bir isteği belirli bir süre boyunca düzenli olarak yeniden denediğiniz 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 çekilme, bu hataların işlenmesi için iyi bir strateji olabilir. Buna karşılık, ağ yetkilendirmesi veya yanıt süreleriyle ilgili olmayan hataları (ör. geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları) ele almak için uygun bir strateji değildir.

Doğru şekilde kullanıldığında eksponansiyel 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 performansını en üst düzeye çıkarır.

Basit üstel geri yükleme uygulama akışı aşağıdaki gibidir:

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

Yukarıdaki akışta rastgele_sayı_millisaniye, 1000'den küçük veya 1000'e eşit rastgele bir milisaniyedir. Küçük bir rastgele gecikmenin yüklenmesi, yükü daha eşit bir şekilde dağıtmaya ve sunucuya damgalanma olasılığını önlemeye yardımcı olduğu için bu gereklidir. Rastgele_sayı_millisaniye değeri, her beklemeden sonra yeniden tanımlanmalıdır.

Not: Bekleme, her zaman (2 ^ n) + rastgele_sayı_millisaniyedir. Burada n başlangıçta 0 olarak tanımlanan tekdüze artan bir tam sayıdır. Her bir yineleme için n tam sayısı 1 artırılır (her istek).

Algoritma, n 5 olduğunda sonlanacak şekilde ayarlanmıştır. Bu tavan, müşterilerin süresiz olarak yeniden denemesini engeller ve bir isteğin "kurtarılamayan hata" olarak değerlendirilmesi yaklaşık 32 saniye gecikmeyle sonuçlanır. Özellikle uzun bir yükleme işlemi devam ediyorsa maksimum sayıda yeniden deneme sayısı sorun oluşturmaz. Bu nedenle, yeniden deneme gecikmesini, örneğin bir dakikadan kısa bir süre içinde sınırlandırmanız yeterlidir.

API istemci kitaplığı kılavuzları