Delta güncelleştirmeleri (Önizleme)
Delta güncelleştirmeleri, yalnızca iki tam güncelleştirme, bir kaynak görüntü ve hedef görüntü arasındaki değişiklikleri temsil eden küçük güncelleştirmeler oluşturmanıza olanak tanır. Bu yaklaşım, özellikle kaynak ve hedef güncelleştirmeler arasında yalnızca birkaç değişiklik varsa, bir cihaza güncelleştirme indirmek için kullanılan bant genişliğini azaltmak için idealdir.
Not
IoT Hub için Azure Cihaz Güncelleştirmesi'ndeki delta güncelleştirme özelliği şu anda genel önizleme aşamasındadır.
IoT Hub için Cihaz Güncelleştirmesi'nde değişiklik güncelleştirmelerini kullanma gereksinimleri
- Kaynak ve hedef güncelleştirme dosyaları SWUpdate (SWU) biçiminde olmalıdır.
- Her SWUpdate dosyasında Ext2, Ext3 veya Ext4 dosya sistemini kullanan bir ham görüntü olmalıdır.
Delta oluşturma işlemi, en iyi deltayı oluşturmak için gzip sıkıştırmasını kullanarak hedef SWU güncelleştirmesini yeniden sıkıştırıyor. Yeniden sıkıştırılan hedef SWU güncelleştirmesini, oluşturulan delta güncelleştirme dosyasıyla birlikte Cihaz Güncelleştirmesi hizmetine aktarırsınız.
Delta işlemci bileşeni için Cihaz Güncelleştirmesi aracı yapılandırması
Cihaz Güncelleştirme hizmetinden değişiklik güncelleştirmelerini indirip yüklemek için, cihazınızın güncelleştirme işleyicisi ve delta işlemci bileşeninin mevcut ve yapılandırılmış olduğu Cihaz Güncelleştirmesi aracısına ihtiyacı vardır.
Cihaz Güncelleştirme aracısı
Cihaz Güncelleştirmesi aracısı , indirme, yükleme ve yeniden başlatma eylemleri dahil olmak üzere cihazdaki güncelleştirme işlemini düzenler . Cihaz Güncelleştirmesi aracısını bir cihaza eklemek ve kullanmak üzere yapılandırmak için bkz . Cihaz Güncelleştirmesi aracısı sağlama. Aracı sürüm 1.0 veya üzerini kullanın.
Güncelleştirme işleyicisi
Güncelleştirme işleyicisi, gerçek güncelleştirme yüklemesini gerçekleştirmek için Cihaz Güncelleştirme aracısı ile tümleşir. Değişiklik güncelleştirmeleri için, değiştirmek istediğiniz kendi SWUpdate güncelleştirme işleyiciniz yoksa güncelleştirme işleyicisiyle microsoft/swupdate:2
başlayın.
Delta işlemci
Azure/iot-hub-device-update-delta konumundaki delta işlemcisi , değişiklik dosyası indirildikten sonra cihazınızda özgün SWU görüntü dosyasını yeniden oluşturur, böylece güncelleştirme işleyiciniz SWU dosyasını yükleyebilir. Delta işlemci bileşenini cihaz görüntünüze eklemek ve kullanmak üzere yapılandırmak için adresinden Ubuntu 20.04 ve üzeri https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0için bir Debian paketi indirebilirsiniz.
Başka bir dağıtım kullanıyorsanız, bunun yerine kaynaktan delta işlemcisi oluşturmak için CMAKE'yi kullanmak için README.md yönergelerini izleyin. Buradan, paylaşılan nesneyi /usr/lib dizinine aşağıdaki gibi kopyalayarak doğrudan libadudiffapi.so yükleyin:
sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig
Cihazınıza kaynak SWU görüntü dosyası ekleme
Delta güncelleştirme dosyası bir cihaza indirildikten sonra, daha önce cihazda önbelleğe alınmış geçerli <source_archive>
bir dosyayla karşılaştırılır. Bu işlem, delta güncelleştirmesinin tam hedef görüntüyü yeniden oluşturmasını sağlar.
Bu önbelleğe alınmış görüntüyü doldurmanın en basit yolu, Cihaz Güncelleştirme hizmeti aracılığıyla cihaza tam görüntü güncelleştirmesi içeri aktarmak ve dağıtmaktır. Cihaz, Cihaz Güncelleştirme aracısı sürüm 1.0 veya üzeri ve delta işlemcisi ile yapılandırılmışsa aracı, yüklü SWU dosyasını daha sonra delta güncelleştirme kullanımı için otomatik olarak önbelleğe alır.
Bunun yerine doğrudan cihazınızdaki kaynak görüntüyü önceden doldurmayı istiyorsanız, görüntünün beklendiği yol şeklindedir <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>
. Varsayılan olarak, <BASE_SOURCE_DOWNLOAD_CACHE_PATH>
/var/lib/adu/sdc/<provider yoludur>.
provider
değeri, provider
kaynak SWU dosyasının updateId değeridir.
ENCODED_HASH
, ikilinin SHA256'sının base64 onaltılık dizesidir, ancak base64 onaltılık dizeye kodlama yaptıktan sonra karakterleri şu şekilde kodlar:
-
+
olarak kodlanmışoctets _2B
-
/
olarak kodlanmışoctets _2F
-
=
olarak kodlanmışoctets _3D
DiffGen aracını kullanarak delta güncelleştirme oluşturma
Fark Oluşturma (DiffGen) aracını kullanarak delta güncelleştirmeleri oluşturabilirsiniz.
Ortam önkoşulları
DiffGen ile deltalar oluşturmadan önce, ortam makinesine birkaç şey indirip yüklemeniz gerekir. İdeal olarak bir Ubuntu 20.04 Linux ortamı kullanın veya Windows kullanıyorsanız Linux için Windows Alt Sistemi.
Aşağıdaki tabloda gereken içerik, nereden alınacağı ve gerekirse önerilen yükleme gösterilmektedir.
İkili adı | Nereden edinileceği | Yükleme |
---|---|---|
DiffGen | Azure/iot-hub-device-update-delta GitHub deposu | Delta güncelleştirmeleri oluşturmak için kullanılacak makinedeki işletim sistemi veya dağıtımla eşleşen sürümü indirin. |
. NETCore çalışma zamanı, sürüm 8.0.0 | Terminal veya paket yöneticileri aracılığıyla | Linux'a .NET yükleyin. Yalnızca çalışma zamanı gereklidir. |
DiffGen kullanarak delta güncelleştirme oluşturma
DiffGen aracı aşağıdaki gerekli bağımsız değişkenler ve söz dizimi ile çalışır:
DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>
Yukarıdaki komut, dosyasını oluşturan <recompressed_target_file>
recompress_tool.py betiğini çalıştırır. DiffGen daha sonra fark oluşturmak için hedef dosya olarak yerine <target_archive>
öğesini kullanır<recompressed_target_file>
. içindeki <recompressed_target_archive>
görüntü dosyaları gzip ile sıkıştırılır.
SWU dosyalarınız imzalıysa, DiffGen komutunda bağımsız değişkeni de gerektirir <signing_command>
:
DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"
İmzalama komut dizesi parametresine sahip DiffGenTool, recompress_and_sign_tool.py betiğini çalıştırır. Bu betik, oluşturur <recompressed_target_file>
. Ayrıca bu betik, sw-description.sig dosyası oluşturmak için arşivdeki sw-description dosyasını da imzalar.
Giriş kaynak dosyası ile yeniden sıkıştırılmış ve yeniden imzalanmış bir hedef dosya arasında fark oluşturmak için Azure/iot-hub-device-update-delta GitHub deposundaki örnek sign_file.sh betiğini kullanabilirsiniz. Betiği açın, özel anahtar dosyanıza yol eklemek için düzenleyin ve kaydedin. Örnek kullanım için Örnekler bölümüne bakın.
Aşağıdaki tabloda bağımsız değişkenler daha ayrıntılı olarak açıklanmaktadır:
Bağımsız değişken | Açıklama |
---|---|
<source_archive> |
DiffGen'in deltayı oluşturmak için başlangıç noktası olarak kullandığı temel görüntü. Önemli: Bu görüntü, örneğin önceki bir güncelleştirmeden önbelleğe alınmış olarak cihazda bulunan görüntüyle aynı olmalıdır. |
<target_archive> |
Deltanın cihazı güncelleştirdiğinde görüntü. |
<output_path> |
Oluşturulan delta dosyasının istenen adı da dahil olmak üzere, oluşturma işleminden sonra delta dosyasının yerleştirildiği konak makinedeki yol. Yol yoksa araç bunu oluşturur. |
<log_folder> |
Konak makinede günlüklerin oluşturulacağı yol. Bu konumu çıkış yolunun alt klasörü olarak tanımlamak en iyisidir. Yol yoksa araç bunu oluşturur. |
<working_folder> |
Delta oluşturma sırasında ikincil dosyaları ve diğer çalışma dosyalarını yerleştirmek için makinedeki yol. Bu konumu çıkış yolunun alt klasörü olarak tanımlamak en iyisidir. Yol yoksa araç bunu oluşturur. |
<recompressed_target_archive> |
konak makinesinde oluşturulacak <recompressed_target_file> yol.
<recompressed_target_file> , fark oluşturma için hedef dosya olarak yerine <target_archive> kullanılır. DiffGen aracı çağrılmadan önce bu yol varsa, üzerine yazılır. Bu dosyayı çıkış yolunun bir alt klasöründe tanımlamak en iyisidir. |
"<signing_command>" (isteğe bağlı) |
içinde <recompressed_target_archive> sw-description dosyasını imzalamak için özelleştirilebilir bir komut. Yeniden sıkıştırılan arşivdeki sw-description dosyası, imzalama komutu için giriş parametresi olarak kullanılır. DiffGen, .sig ekli girişin adını kullanarak imzalama komutunun yeni bir imza dosyası oluşturmasını bekler.Komutun tamamını tek bir parametre olarak geçirmek için parametresini çift tırnak işaretiyle çevrelemelisiniz. Ayrıca, karakteri imzalamak için kullanılan bir anahtar yolda kullanmaktan ~ kaçının ve bunun yerine tam giriş yolunu kullanın. Örneğin, ~/keys/priv.pem yerine /home/USER/keys/priv.pem kullanın. |
DiffGen örnekleri
Aşağıdaki örnekler Linux için Windows Alt Sistemi'de /mnt/o/temp dizininde çalışır.
Aşağıdaki kod, giriş kaynak dosyası ile yeniden sıkıştırılan hedef dosya arasında bir fark oluşturur:
sudo ./DiffGenTool
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu
SWU dosyanız imzalıysa kullanmanız gereken imzalama parametresini de kullanıyorsanız, daha önce bahsedilen örnek sign_file.sh betiğini kullanabilirsiniz. Betiği açın, özel anahtar dosyanıza yol eklemek için düzenleyin, betiği kaydedin ve DiffGen'i aşağıdaki gibi çalıştırın.
Aşağıdaki kod, giriş kaynak dosyası ile yeniden sıkıştırılmış ve yeniden imzalanan hedef dosya arasında fark oluşturur:
sudo ./DiffGenTool
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu
/mnt/o/temp/<path to script>/<sign_file>.sh
Oluşturulan delta güncelleştirmesi içeri aktarma
Cihaz Güncelleştirme hizmetine delta güncelleştirmesini içeri aktarmanın temel işlemi, diğer güncelleştirmeler ile aynıdır. Henüz yapmadıysanız, IoT Hub için Azure Cihaz Güncelleştirmesi'ne aktarılacak güncelleştirmeyi hazırlama makalesini gözden geçirmeyi unutmayın.
İçeri aktarma bildirimini oluşturma
Bir güncelleştirmeyi Cihaz Güncelleştirmesi hizmetine aktarmak için bir içeri aktarma bildirim dosyasına sahip olmanız veya oluşturmanız gerekir. Daha fazla bilgi için bkz . Güncelleştirmeleri Cihaz Güncelleştirmesi'ne aktarma.
Delta güncelleştirmeleri için içeri aktarma bildirim dosyaları, DiffGen aracının oluşturduğu aşağıdaki dosyalara başvurmalıdır:
-
<recompressed_target_file>
SWU görüntüsü -
<delta file>
Delta güncelleştirme özelliği, sürüm 5 veya sonraki bir içeri aktarma bildirimi gerektiren ilgili dosyalar olarak adlandırılan bir özellik kullanır. İlgili dosyalar özelliğini kullanmak için, içeri aktarma bildiriminize relatedFiles ve downloadHandler nesnelerini eklemeniz gerekir.
Dosya adı, dosya boyutu ve sha256 karması dahil olmak üzere delta güncelleştirme dosyası hakkındaki bilgileri belirtmek için nesnesini kullanırsınız relatedFiles
. En önemlisi, delta güncelleştirme özelliğine özgü aşağıdaki iki özelliği de belirtmeniz gerekir:
"properties": {
"microsoft.sourceFileHashAlgorithm": "sha256",
"microsoft.sourceFileHash": "<source SWU image file hash>"
}
Her iki özellik de delta güncelleştirmenizi oluştururken DiffGen aracına giriş olarak kullandığınız özelliklere özeldir <source image file>
. İçeri aktarma bildirimi, kaynak görüntüyü içeri aktarmasanız bile kaynak SWU görüntüsüyle ilgili bilgilere ihtiyaç duyar. Cihazdaki delta bileşenleri, delta güncelleştirmesini indirdikten sonra bu görüntüyü cihazda bulmak için kaynak görüntüyle ilgili bu meta verileri kullanır.
downloadHandler
Cihaz Güncelleştirmesi aracısının delta güncelleştirmesini ilgili dosyalar özelliğini kullanarak nasıl düzenleneceğini belirtmek için nesnesini kullanın. Değişiklik işlevselliği için Cihaz Güncelleştirmesi aracısının kendi sürümünü özelleştirmediğiniz sürece aşağıdakileri downloadHandler
kullanın:
"downloadHandler": {
"id": "microsoft/delta:1"
}
Delta güncelleştirmeniz için bir içeri aktarma bildirimi oluşturmak için Azure CLI az iot du update init v5
komutunu kullanabilirsiniz. Daha fazla bilgi için bkz . Temel içeri aktarma bildirimi oluşturma.
--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'
Oluşturduğunuz içeri aktarma bildirimi JSON dosyasını dosya uzantısı .importmanifest.json kaydedin.
Azure portalını kullanarak dışarı aktarma
İçeri aktarma bildiriminizi oluşturduktan sonra IoT Hub için Cihaz Güncelleştirmesi'ne güncelleştirme ekleme başlığı altında yer alan yönergeleri izleyerek delta güncelleştirmesini içeri aktarın. İçeri aktarma işlemine aşağıdaki öğeleri eklemeniz gerekir:
- Önceki adımlarda daha önce oluşturduğunuz *importmanifest.json dosyası
-
<recompressed_target_file>
DiffGen aracının oluşturduğu SWU görüntüsü - Oluşturulan
<delta file>
DiffGen aracı
Cihazlara delta güncelleştirme dağıtımı
Azure portalındaki delta güncelleştirmesi dağıtım deneyimi, normal bir görüntü güncelleştirmesi dağıtmakla aynıdır. Daha fazla bilgi için bkz . Cihaz Güncelleştirmesini kullanarak güncelleştirme dağıtma.
Delta güncelleştirmeniz için dağıtımı oluşturduktan sonra Cihaz Güncelleştirme hizmeti ve istemcisi, dağıttığınız her cihaz için geçerli bir değişiklik güncelleştirmesi olup olmadığını otomatik olarak belirler. Geçerli bir delta bulurlarsa delta güncelleştirmesini indirip bu cihaza yüklerler.
Geçerli bir değişiklik güncelleştirmesi bulamazsa, tam görüntü güncelleştirmesi (yeniden sıkıştırılan hedef SWU görüntüsü) geri dönüş olarak indirilir. Bu yaklaşım, güncelleştirmeyi dağıttığınız tüm cihazların uygun sürüme ulaşabilmesini sağlar.
Delta güncelleştirme dağıtımı için üç olası sonuç vardır:
- Delta güncelleştirmesi başarıyla yüklendi ve cihaz yeni sürümde.
- Delta güncelleştirmesi kullanılamıyordu veya yüklenemedi, ancak tam görüntünün geri dönüş yüklemesi başarılı oldu ve cihaz yeni sürümde.
- Hem delta hem de geri dönüş yüklemeleri başarısız oldu ve cihaz hala eski sürümde.
Hangi hata sonucunun oluştuğuna karar vermek için, başarısız durumdaki herhangi bir cihazı seçerek hata kodu ve genişletilmiş hata koduyla yükleme sonuçlarını görüntüleyebilirsiniz. Gerekirse birden çok başarısız cihazdan da günlük toplayabilirsiniz.
Delta güncelleştirmesi başarılı olursa, cihaz Başarılı durumunu gösterir.
Delta güncelleştirmesi başarısız olduysa ancak tam görüntüye geri dönüş başarılı olduysa, cihaz aşağıdaki hata durumunu gösterir:
-
resultCode
: <0'dan büyük değer> -
extendedResultCode
: <sıfır olmayan değer>
-
Başarısız güncelleştirme sorunlarını giderme
Başarısız güncelleştirmeler, aşağıdaki yönergeleri kullanarak yorumlayabileceğiniz bir hata durumu görüntüler. Result.h dosyasındaki Cihaz Güncelleştirme aracısı hatalarıyla başlayın.
Cihaz Güncelleştirmesi aracısından delta güncelleştirmeleri indirme işleyicisi işlevine özgü hatalar ile 0x9
başlar:
Bileşen | Ondalık | Onaltılık | Not |
---|---|---|---|
EXTENSION_MANAGER | 0 | 0x00 | Uzantı yöneticisi indirme işleyici mantığındaki hataları gösterir. Örnek: 0x900XXXXX |
EKLENTI | 1 | 0x01 | İndirme işleyicisi eklentisi paylaşılan kitaplıklarının kullanımıyla ilgili hataları gösterir. Örnek: 0x901XXXXX |
AYRILMIŞ | 2 - 7 | 0x02 - 0x07 | İndirme işleyicisi için ayrılmıştır. Örnek: 0x902XXXXX |
ORTAK | 8 | 0x08 | Delta indirme işleyici uzantısı üst düzey mantığındaki hataları gösterir. Örnek: 0x908XXXXX |
SOURCE_UPDATE_CACHE | 9 | 0x09 | Delta indirme işleyicisi uzantısı kaynak güncelleştirme önbelleğindeki hataları gösterir. Örnek: 0x909XXXXX |
DELTA_PROCESSOR | 10 | 0x0A | Delta işlemci API'sinden gelen hatalar için hata kodu. Örnek: 0x90AXXXXX |
Hata kodu result.h dosyasında yoksa, büyük olasılıkla Cihaz Güncelleştirmesi aracısından ayrı olarak delta işlemci bileşeninde bir hatadır. Öyleyse, extendedResultCode
onaltılık biçimdeki 0x90AXXXXX
negatif ondalık değeridir.
-
9
"Delta Tesisi" -
0A
is "Delta processor component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR) -
XXXXX
, Alan Yükleme Aracı (FIT) delta işlemcisinden alınan 20 bit hata kodudur
Hata kodu bilgilerine göre sorunu çözemiyorsanız daha fazla yardım almak için bir GitHub sorunu oluşturun.