Paket oluşturma

Yükleme seçenekleri

Android Over The Air API, yeni bir Paket kaynağı oluşturmak için paket verilerini yüklemenize olanak tanır. Bunlar, güncellemenin cihazlara yayınlanması için bir veya daha fazla yapılandırmayla ilişkilendirilebilecek OTA paketleridir.

Aşağıda açıklanan protokolleri uygulamak yerine kullanıp özgürce kullanabileceğiniz devam ettirilebilir paket yüklemelerini kolaylaştırmak için Linux ve Windows için bir ikili program sunuyoruz. Daha ayrıntılı bir entegrasyon isterseniz lütfen aşağıda açıklanan protokollerden birini kullanın.

Linux

Linux için Android Over The Air API v1 yükleyici istemcisini indirin.

Windows

Windows için Android Over The Air API v1 yükleyici istemcisini indirin.

Bunu kullanmak için önce bir hizmet hesabı oluşturmanız ve bu hesap için bir JSON anahtar dosyası almanız gerekir. Lütfen hesap oluşturmayla ilgili buradaki kılavuzumuza bakın.
İkili dosyayı ve anahtar dosyasını oluşturduktan sonra anahtar dosyasını, dağıtımınızı ve yüklediğiniz paketi belirtmek için komut satırı seçenekleriyle bu dosyayı çalıştırabilirsiniz. Tüm seçenekleri görmek için lütfen --help öğesini kullanın.

Yükleme Protokolleri

Aşağıdaki yöntemlerden birini kullanarak yükleme isteğinde bulunabilirsiniz. Kullandığınız yöntemi X-Goog-Upload-Protocol istek başlığıyla belirtin.

  • Çok parçalı yükleme: X-Goog-Upload-Protocol: multipart. Daha küçük dosyaların ve meta verilerin hızlıca aktarılması için dosyayı tanımlayan meta verilerle birlikte tek bir istekte aktarılır.
  • Devam ettirilebilir yükleme: X-Goog-Upload-Protocol: resumable. Güvenilir aktarım için özellikle büyük dosyalarda önemlidir. Bu yöntemle, isteğe bağlı olarak meta veri içerebilen bir oturum başlatma isteği kullanırsınız. Bu, yükleme başına fazladan bir HTTP isteğine denk gelen küçük dosyalarda da çalıştığından çoğu uygulama için iyi bir stratejidir.

Çok parçalı yükleme

Gönderdiğiniz veriler, bağlantı başarısız olursa tamamen tekrar yüklenecek kadar küçükse bu iyi bir seçimdir.

Çok parçalı yüklemeyi kullanmak için /upload/package URI'sına bir POST isteği gönderin ve X-Goog-Upload-Protocol öğesini multipart olarak ayarlayın.

Çok parçalı bir yükleme isteği oluştururken 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 dahil edin.
  • Content-Length. İstek gövdesindeki toplam bayt sayısına ayarlayın.

İ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 başlığı gerekir:

  1. Meta veri bölümü: Önce gelmelidir ve Content-Type, application/json olmalıdır.
  2. Medya bölümü: İkinci olarak gelmeli ve Content-Type, application/zip olmalıdır.

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

Aşağıdaki örnekte Android Over The Air API için çok parçalı bir yükleme isteği gösterilmektedir.

POST /upload/package HTTP/1.1
Host: androidovertheair.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=BOUNDARY
Content-Length: number_of_bytes_in_entire_request_body

--BOUNDARY
Content-Type: application/json; charset=UTF-8

{"deployment": "id", "package_title": "title" }
--BOUNDARY
Content-Type: application/zip; charset=UTF-8

Package ZIP
--BOUNDARY--

İstek başarılı olursa sunucu HTTP 200 OK durum kodunu döndürür.

HTTP/1.1 200

Bunu kolayca gerçekleştirmenin bir yolu curl ve oauth2l kullanmaktır. Aşağıda, hizmet anahtarı kullandığınızı varsayan bir örnek istek gösterilmektedir (daha fazla bilgi için yetkilendirme nasıl yapılır? bölümüne bakın).

Örnek curl isteği 
    JSON={"deployment": "id", "package_title": "title" }
    SERVICE_KEY_FILE=path to your service key json file
    curl \
    -H "$(./oauth2l header --json $SERVICE_KEY_FILE android_partner_over_the_air)" \
    -H "Host: androidovertheair.googleapis.com" \
    -H "X-Goog-Upload-Protocol: multipart" \
    -H "Content-Type: multipart/form-data" \
    -F "json=$JSON;type=application/json" \
    -F "data=@update.zip;type=application/zip" \
    androidovertheair.googleapis.com/upload/package

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ı veri akışını kesintiye uğrattıktan sonra yükleme işlemini devam ettirmenize olanak tanır. Bu özellik, büyük dosyalar aktarıyorsanız ve örneğin mobil istemci uygulamasından yükleme yaparken ağ kesintisi veya başka bir iletim hatası olasılığı yüksek olduğunda özellikle faydalıdır. Ayrıca, büyük dosya yüklemelerini baştan başlatmak zorunda kalmayacağınız için ağ kesintileri durumunda bant genişliği kullanımınızı da azaltabilir.

Devam ettirilebilir yükleme protokolü çeşitli komutlar kullanır:

  1. Devam ettirilebilir bir oturum başlatın. Meta verileri içeren ve benzersiz bir devam ettirilebilir yükleme konumu oluşturan yükleme URI'sine ilk istek yapın.
  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 kullanacaksınız.
  3. Dosyayı yükleyin. ZIP dosyasının tamamını veya bir kısmını devam ettirilebilir oturum URI'sine gönderin.

Ayrıca, devam ettirilebilir yüklemeyi kullanan uygulamaların, kesilen bir yüklemeyi devam ettirecek koda sahip olması gerekir. Yükleme kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yükleme işlemine bu noktadan başlayarak devam edin.

Not: Yükleme URI'sinin süresi 3 gün sonra dolar.

1. Adım: Devam ettirilebilir bir oturum başlatın

Devam ettirilebilir bir yükleme başlatmak için /upload/package URI'sına bir POST isteği gönderin ve X-Goog-Upload-Protocol öğesini resumable olarak ayarlayın.

Bu başlatma isteği için gövdenin yalnızca meta verileri içermesi gerekir. Yüklemek istediğiniz dosyanın gerçek içeriğini sonraki isteklerde aktarırsınız.

İlk istekle birlikte aşağıdaki HTTP üstbilgilerini kullanın:

  • X-Goog-Upload-Header-Content-Type. Bu, yüklenen dosyanın içerik türüdür ve application/zip olarak ayarlanmalıdır.
  • X-Goog-Upload-Command. start olarak ayarlayın
  • X-Goog-Upload-Header-Content-Length. Sonraki isteklerde aktarılacak yükleme verilerinin bayt sayısını ayarlayın. İstek sırasında uzunluk bilinmiyorsa bu başlığı çıkarabilirsiniz.
  • Content-Type. Bu, meta verilerin içerik türüdür ve application/json olarak ayarlanmalıdır.
  • Content-Length. Bu ilk isteğin gövdesinde sağlanan bayt sayısını ayarlayın.
Örnek: Devam ettirilebilir oturum başlatma isteği

Aşağıdaki örnekte, Android Over The Air API için nasıl devam ettirilebilir oturum başlatılacağı gösterilmektedir.

POST /upload/package HTTP/1.1
Host: android/over-the-air.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Goog-Upload-Command: start
X-Goog-Upload-Header-Content-Type: application/zip
X-Goog-Upload-Header-Content-Length: 2000000

{"deployment": "id", "package_title": "title" }

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 HTTP 200 OK durum koduyla yanıt verir. Ayrıca, devam ettirilebilir oturum URI'nızı belirten bir X-Goog-Upload-URL üst bilgisi sağlar. Aşağıdaki örnekte gösterilen X-Goog-Upload-URL başlığı, bu oturum için kullanılacak benzersiz yükleme kimliğini veren bir upload_id sorgu parametresi bölümü içerir. Yanıt, yükleme isteği geçerli ve kabul edilmişse active olacak bir X-Goog-Upload-Status üst bilgisi de içerir. Yükleme reddedildiyse bu durum final olabilir.

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

1. Adımdaki isteğin yanıtı aşağıda verilmiştir:

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-URL: androidovertheair.googleapis.com/?upload_id=xa298sd_sdlkj2
Content-Length: 0

Yukarıdaki örnek yanıtında gösterildiği gibi X-Goog-Upload-URL üst bilgisinin değeri, gerçek dosya yüklemeyi yapmak veya yükleme durumunu sorgulamak için HTTP uç noktası olarak kullanacağınız oturum URI'sidir.

Oturum URI'sini sonraki isteklerde kullanabilmek için 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 POST isteği gönderin. Yükleme isteğinin biçimi şu şekildedir:

POST session_uri

Devam ettirilebilir dosya yükleme istekleri oluşturulurken kullanılacak HTTP üstbilgileri şunlardır:

  1. Content-Length. Bunu, bu istekte yüklediğiniz bayt sayısı (genellikle yükleme dosyasının boyutu) olarak ayarlayın.
  2. X-Goog-Upload-Command. Bunu upload ve finalize olarak ayarlayın.
  3. X-Goog-Upload-Offset. Bu, baytların yazılması gereken ofseti belirtir. İstemcilerin baytları seri olarak yüklemesi gerektiğini unutmayın.
Örnek: Devam ettirilebilir dosya yükleme isteği

Mevcut örnek için 2.000.000 baytlık ZIP dosyasının tamamını yüklemek üzere devam ettirilebilir bir isteği burada görebilirsiniz.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0
Content-Length: 2000000
Content-Type: application/zip

bytes 0-1999999

İstek başarılı olursa sunucu bir HTTP 200 Ok ile yanıt verir.

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

Dosyayı parçalar halinde yükleme

Devam ettirilebilir yüklemelerle bir dosyayı parçalara bölebilir ve her bir parçayı sırayla yüklemek için bir dizi istek gönderebilirsiniz. Ek isteklerle ilişkili performans maliyetleri bulunduğundan ve genellikle gerekli olmadığından bu, tercih edilen yaklaşım değildir. İstemcilerin, yükün kalan tüm baytlarını yüklemesini ve her upload komutuna finalize komutunu eklemesini öneririz.

Bununla birlikte, herhangi bir tek istekte aktarılan veri miktarını azaltmak için bölmeyi kullanmanız gerekebilir. Ayrıca, varsayılan olarak yükleme ilerleme durumu 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.

Kesilen bir yüklemeyi devam ettirme

Yükleme isteği yanıt alınmadan sonlandırılır 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. X-Goog-Upload-Command değeri query olacak şekilde yükleme URI'sına bir istek göndererek yüklemenin mevcut durumunu sorgulayın.

    Not: Yalnızca yükleme kesintiye uğradığında değil, parçalar arasındaki durumu da isteyebilirsiniz. Bu, örneğin eski tarayıcılar için yükleme ilerleme durumunu göstermek istediğinizde yararlı olur.

  2. Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, şimdiye kadar kaç bayt aldığını belirtmek için yanıtında X-Goog-Upload-Size-Received üst bilgisini kullanır.
  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. Kalan verileri her iki durumda da ayrı bir yığın olarak işlemeniz gerektiğini unutmayın. Bu nedenle, yüklemeyi devam ettirdiğinizde X-Goog-Upload-Offset başlığını uygun ofsete ayarlamanız gerekir.
Örnek: Kesilen bir yüklemeyi devam ettirme

1) Yükleme durumunu isteyin.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: query

Tüm komutlarda olduğu gibi istemci, sorgu komutunun HTTP yanıtında X-Goog-Upload-Status üstbilgisini kontrol etmelidir. Başlık varsa ve değer active değilse yükleme zaten sonlandırılmıştır.

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

Sunucunun yanıtı, şimdiye kadar dosyanın ilk 43 baytını aldığını belirtmek için X-Goog-Upload-Size-Received üst bilgisini kullanır.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 42

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

Aşağıdaki istek, 43 bayttan başlayarak dosyanın kalan baytlarını göndererek yüklemeyi devam ettirir.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: upload, finalize
Content-Length: 1999957
X-Goog-Upload-Offset: 43

bytes 43-1999999

En iyi uygulamalar

Medya yüklerken, hata giderme ile ilgili bazı en iyi uygulamaları bilmeniz yararlı 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 yeniden deneyin:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Yükleme istekleri devam ettirildiğinde veya yeniden denendiğinde 5xx sunucu hatası döndürülürse üstel geri yükleme stratejisi kullanın. Bu hatalar, bir sunucu aşırı yükleniyorsa ortaya çıkabilir. Üstel geri çekilme, yüksek istek hacminin veya yoğun ağ trafiğinin olduğu dönemlerde bu tür sorunların hafifletilmesine yardımcı olabilir.
  • Diğer istek türleri üstel geri yükleme ile işlenmemelidir. Ancak yine de birkaçını yeniden deneyebilirsiniz. Bu istekleri yeniden denediğinizde, tekrar deneme sayısını sınırlayın. Örneğin, kodunuz bir hata bildirmeden önce 10 veya daha az yeniden denemeyle sınırlanabilir.
  • Devam ettirilebilir yüklemeler yaparken, tüm yükleme işlemini baştan başlatarak 404 Not Found hatalarını giderin.

Eksponansiyel geri yükleme

Üstel geri yükleme, istemcinin başarısız bir isteği giderek artan bir süre içinde düzenli olarak yeniden denediği, 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 üstel geri çekilme, bu hataları ele almak için iyi bir strateji olabilir. Bununla birlikte, geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları gibi ağ hacmi veya yanıt süreleriyle ilgili olmayan hataları ele almak için uygun bir strateji değildir.

Doğru kullanıldığında üstel geri yükleme özelliği, 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 istekte bulunun.
  2. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alın.
  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ın.
  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ın.
  7. 4 saniye +Random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  8. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alın.
  9. 8 saniye + rastgele_sayı_milisaniye cinsinden bekleyin ve isteği yeniden deneyin.
  10. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alın.
  11. 16 saniye + rastgele_sayı_milisaniye cinsinden bekleyin ve isteği yeniden deneyin.
  12. Durdur. Hata bildirin veya günlüğe kaydedin.

Yukarıdaki akışta, rastgele_sayı_milisaniye, 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ün daha eşit bir şekilde dağıtılmasına ve sunucunun damgalanma olasılığını ortadan kaldırmaya yardımcı olduğundan bu gereklidir. Rastgele_sayı_milisaniye değeri, her beklemenin ardından yeniden tanımlanmalıdır.

Not: Bekleme süresi her zaman (2 ^ n) + rastgele_sayı_millisaniyedir. 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 artar.

Algoritma, n 5 olduğunda sona erecek şekilde ayarlanır. Bu üst sınır, istemcilerin sonsuza kadar yeniden deneme yapmasını engeller ve bir istek "kurtarılamaz hata" olarak kabul edilmeden önce toplamda yaklaşık 32 saniyelik bir gecikmeyle sonuçlanır. Özellikle uzun bir yükleme işlemi devam ediyorsa maksimum yeniden deneme sayısının daha yüksek olması sorun teşkil etmez. Yine de yeniden deneme gecikmesini makul bir süre, örneğin bir dakikadan daha az bir süreyle sınırladığınızdan emin olun.