Bagikan melalui

Gunakan fitur file terkait untuk mereferensikan beberapa file pembaruan

  • Artikel

Gunakan fitur file terkait saat Anda perlu mengekspresikan hubungan antara file pembaruan yang berbeda dalam satu pembaruan.

Saat mengimpor pembaruan ke Pembaruan Perangkat untuk IoT Hub, manifes impor yang berisi metadata tentang payload pembaruan diperlukan. Metadata tingkat file dalam manifes impor dapat menjadi daftar datar file payload pembaruan dalam kasus yang paling sederhana. Namun, untuk skenario yang lebih canggih, fitur file terkait menyediakan cara bagi Anda untuk menentukan hubungan antara beberapa file pembaruan.

Saat membuat manifes impor menggunakan fitur file terkait, Anda dapat menambahkan kumpulan file terkait ke satu atau beberapa file payload utama Anda. Contoh konsep ini adalah fitur pembaruan delta Pembaruan Perangkat, yang menggunakan file terkait untuk menentukan pembaruan delta yang terkait dengan file gambar lengkap. Dalam skenario delta, fitur file terkait memungkinkan pembaruan gambar dan delta lengkap untuk keduanya diimpor sebagai tindakan pembaruan tunggal, dan kemudian salah satu dapat disebarkan ke perangkat. Namun, fitur file terkait tidak terbatas pada pembaruan delta, karena dirancang untuk diperluas oleh pelanggan kami tergantung pada skenario unik mereka sendiri.

Fitur file terkait tersedia untuk manifes impor versi 5 atau yang lebih baru.

Saat Anda menambahkan file terkait ke manifes impor, sertakan informasi berikut:

  • Detail file

    Tentukan file terkait dengan memberikan nama file, ukuran, dan hash.

  • Handler unduhan

    Tentukan cara memproses file terkait ini untuk menghasilkan file target. Anda menentukan pendekatan pemrosesan dengan menyertakan downloadHandler properti dalam manifes impor Anda. Termasuk downloadHandler diperlukan jika Anda menentukan koleksi relatedFiles yang tidak kosong dalam file elemen . Anda dapat menentukan downloadHandler menggunakan properti sederhana id . Handler id Unduh memiliki batas 64 karakter ASCII.

  • Properti file terkait

    Anda dapat memberikan metadata tambahan untuk handler pembaruan di perangkat Anda untuk mengetahui cara menginterpretasikan dan menggunakan file yang telah Anda tentukan sebagai file terkait dengan benar. Metadata ini ditambahkan sebagai bagian properties dari tas properti ke file objek dan relatedFile .

Untuk informasi selengkapnya tentang skema impor untuk file terkait, lihat objek relatedFiles.

Contoh manifes impor berikut menunjukkan bagaimana fitur file terkait digunakan untuk mengimpor pembaruan delta. Dalam contoh ini, Anda dapat melihat bahwa di bagian files , ada gambar lengkap yang ditentukan (full-image-file-name) dengan properties item. Item pada properties gilirannya memiliki item terkait relatedFiles di bawahnya. Di dalam bagian , relatedFiles Anda dapat melihat bagian lain properties untuk file pembaruan delta (delta-from-v1-file-name), dan juga downloadHandler item dengan daftar yang sesuai id (microsoft/delta:1).

Catatan

Contoh ini menggunakan pembaruan delta untuk menunjukkan cara mereferensikan file terkait. Jika Anda ingin menggunakan pembaruan delta sebagai fitur, pelajari selengkapnya dalam dokumentasi pembaruan delta.

    {
      "updateId": {
        // provider, name, version
      },
      "compatibility": [
        {
          // manufacturer, model, etc.
        }
      ],
      "instructions": {
        "steps": [
          // Inline steps...
        ]
      },
      "files": [
        {  
          // standard file properties
          "fileName": "full-image-file-name",
          "sizeInBytes": 12345,
          "hashes": {
            "SHA256": "full-image-file-hash"
          },
          "mimeType": "application/octet-stream",
          // new properties
          "properties  ": {},
          "relatedFiles": [
            {
              // delta from version 1.0.0.0
              // standard file properties
              "fileName": "delta-from-v1-file-name",
              "sizeInBytes": 1234,
              "hashes": {
                "SHA256": "delta-from-v1-file-hash"
              },
              "mimeType": "application/octet-stream",
              // new properties
              "properties": {
                "microsoft.sourceFileHash": "delta-source-file-hash",
                "microsoft.sourceFileHashAlgorithm": "sha256"
              }
            }  
          ],
          // handler to download/process our related files
      "downloadHandler": {
        "id": "microsoft/delta:1"
      }
    }
  ],
  "createdDateTime": "2021-12-01T01:12:21Z",
  "manifestVersion": "5.0"
    }

Perintah az iot du init v5 untuk membuat manifes impor mendukung parameter opsional --related-file .

Parameter --related-file mengambil path kunci dan properties :

--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>"}'

Contohnya:

az iot du update init v5 \
--update-provider Microsoft --update-name myBundled --update-version 2.0 \
--compat manufacturer=Contoso model=SpaceStation \
--step handler=microsoft/script:1 properties='{"arguments": "--pre"}' description="Pre-install script" \
--file path=/my/update/scripts/preinstall.sh downloadHandler=microsoft/delta:1 \
--related-file path=/my/update/scripts/related_preinstall.json properties='{"microsoft.sourceFileHashAlgorithm": "sha256"}' \
--step updateId.provider=Microsoft updateId.name=SwUpdate updateId.version=1.1 \
--step handler=microsoft/script:1 properties='{"arguments": "--post"}' description="Post-install script" \
--file path=/my/update/scripts/postinstall.sh

Langkah berikutnya