本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS IoT Device Management 軟體套件目錄 透過 AWS IoT Device Management 軟體套件目錄，您可以維護軟體套件及其版本的庫存。您可以將套件版本與個別物件和 AWS IoT 動態物件群組建立關聯，並透過內部程序或[AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)進行部署。 軟體套件包含一或多個套件版本，它是可以部署為單一單元的檔案集合。套件版本可以包含韌體、作業系統更新、裝置應用程式、組態和安全性修補程式。軟體會隨著時間發展，您可以建立新套件版本並將其部署到您的機群。 AWS IoT 軟體套件中樞位於其中 AWS IoT Core。您可以使用該中樞集中註冊和維護軟體套件庫存和中繼資料，以建立軟體套件及其版本的目錄。您可以選擇根據裝置上部署的軟體套件和套件版本，對裝置進行分組。此功能可讓您將裝置端套件庫存保留為已命名影子、根據版本為裝置建立關聯和分組，並使用機群指標來視覺化跨機群的套件版本分佈。 若您已建立內部軟體部署系統，就能繼續使用該程序來部署套件版本。若您尚未建立部署程序，或若您偏好的話，建議您使用 [AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)，以使用軟體套件目錄中的功能。如需詳細資訊，請參閱[準備 AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html)。 **Topics** + [準備使用軟體套件目錄](preparing-to-use-software-package-catalog.md) + [準備安全性](preparing-security.md) + [準備機群索引](preparing-fleet-indexing.md) + [準備 AWS IoT 任務](preparing-jobs-for-service-package-catalog.md) + [開始使用軟體套件目錄](getting-started-with-software-package-catalog.md) # 準備使用軟體套件目錄 下節提供套件版本生命週期的概觀，以及使用 AWS IoT Device Management 軟體套件目錄的資訊。 ## 套件版本生命週期 套件版本可以經歷下列生命週期狀態：`draft`、`published`、和 `deprecated`。也可以為 `deleted`。 ![\[包含「草稿」、「已發佈」和「已棄用」的套件版本生命週期。也可以為「已刪除」。\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/images/package-catalog-version-lifecycle.png) + **草稿** 當您建立套件版本時，它處於 `draft` 狀態。此狀態表示軟體套件正在準備或不完整。 當套件版本處於此狀態時，您無法部署它。您可以編輯套件版本的描述、屬性和標籤。 您可以使用主控台或發出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) 或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API 操作，將 `draft` 狀態的套件版本轉換為 `published` 或 `deleted` 狀態。 + **已發佈** 當您的套件版本準備好部署時，請將套件版本轉換為 `published` 狀態。在此狀態下，您可以透過在主控台中編輯軟體套件或透過 [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html) API 操作，選擇將套件版本識別為預設版本。在此狀態下，您只能編輯描述和標籤。 您可以使用主控台或發出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) 或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API 操作，將 `published` 狀態的套件版本轉換為 `deprecated` 或 `deleted` 狀態。 + **已棄用** 若有新的套件版本可用，您可以將較早的套件版本轉換為 `deprecated`。您仍然可以使用已棄用的套件版本部署任務。您也可以將已棄用的套件版本命名為預設版本，並僅編輯描述和標籤。 考慮在版本過期`deprecated`時將套件版本轉換為 ，但您仍有使用舊版的 欄位中的裝置，或由於執行時間相依性而需要維護它。 您可以使用主控台或發出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) 或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API 操作，將 `deprecated ` 狀態的套件版本轉換為 `published` 或 `deleted` 狀態。 + **Deleted (已刪除)** 當您不需再使用套件版本，您可使用主控台或發出 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API 操作來刪除該套件版本。 **注意** 若您在有待處理任務參照套件版本時刪除該套件版本，當任務成功完成並嘗試更新預留已命名影子時，您會收到錯誤訊息。 若您要刪除的軟體套件版本已指定為預設套件版本，您必須先更新該套件，將其他版本指定為預設版本，或將該欄位保留為未指定狀態。您可以透過主控台或 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) ​API 操作來執行這項作業。(若要刪除作為預設版本的任何指定套件版本，請在發出 [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html) API 操作時將 [unsetDefaultVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html#iot-UpdatePackage-request-unsetDefaultVersion) 參數設定為 true)。 若您透過主控台刪除軟體套件，則會刪除與該套件相關聯的所有套件版本，除非某個套件版本已指定為預設版本。 ## 套件版本命名慣例 命名套件版本時，請務必規劃並套用邏輯命名策略，以便您和其他人員皆可輕易識別最新的套件版本和版本進度。建立套件版本時，您必須提供版本名稱，但策略和格式主要取決於您的商業案例。 根據最佳實務，建議您使用語意版本控制 [SemVer](https://semver.org/) 格式。例如，`1.2.3`，其中 `1` 是功能上不相容變更的主要版本，`2` 是功能上相容變更的主要版本，`3` 是修補程式版本 (用於錯誤修正)。如需詳細資訊，請參閱[語意版本控制 2.0.0](https://semver.org/)。如需套件版本名稱需求的詳細資訊，請參閱 AWS IoT API 參考指南中的 [versionName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax)。 ## 預設版本 您不一定要將版本設定為預設版本。您可以新增或移除預設套件版本。您也可以部署未指定為預設版本的套件版本。 套件版本在建立時會處於 `draft` 狀態，在您將套件版本轉換為「已發佈」之前，無法將其指定為預設版本。軟體套件目錄不會自動選取某個版本作為預設版本，也不會自動將較新的套件版本更新為預設版本。您必須透過主控台或發出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API 操作，自行為所選套件版本命名。 ## 版本屬性 版本屬性及其值皆包含套件版本的重要資訊。建議您定義套件或套件版本的一般用途屬性。例如，您可以為平台、架構、作業系統、發行日期、作者或 Amazon S3 URL 建立名稱/值配對。 當您使用 AWS IoT 任務文件建立任務時，您也可以選擇使用參考屬性值的替代變數 (`$parameter`)。如需詳細資訊，請參閱[準備 AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html)。 套件版本中使用的版本屬性不會自動新增至預留的具名影子，也無法直接透過機群索引編製索引或查詢。若要透過機群索引編製索引或查詢套件版本屬性，您可以在保留的具名影子中填入版本屬性。 我們建議保留具名影子擷取裝置報告屬性 中的版本屬性參數，例如操作系統和安裝時間。也可以透過機群索引對它們進行索引和查詢。 遵循特定命名慣例不需要版本屬性。您可以建立名稱/值配對，以滿足您的商業需求。套件版本上所有屬性的整體大小限制為 3 KB。如需詳細資訊，請參閱[軟體套件目錄軟體套件和套件版本限制](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#software_package_catalog_limits)。 **使用任務文件中的所有屬性** 您可以讓所有套件版本屬性自動新增至所選裝置的任務部署。若要在 API 或 CLI 命令中以程式設計方式自動使用所有套件版本屬性，請參閱下列任務文件範例： ``` "TestPackage": "${aws:iot:package:TestPackage:version:PackageVersion:attributes}" ``` ## 軟體物料清單 軟體物料清單 (SBOM) 提供軟體套件所有層面的中央儲存庫。除了存放軟體套件和套件版本之外，您還可以在軟體套件目錄中存放與每個套件版本相關聯的 AWS IoT Device Management 軟體物料清單 (SBOM)。軟體套件包含一或多個套件版本，每個套件版本都包含一或多個元件。您可以使用軟體物料清單來描述和編目支援特定套件版本合成的每個元件。支援的 軟體物料清單的業界標準為 SPDX 和 CycloneDX。第一次建立 SBOM 時，它會根據 SPDX 和 CycloneDX 產業標準格式進行驗證。如需 SPDX 的詳細資訊，請參閱[系統套件資料交換](https://spdx.dev/)。如需 CycloneDX 的詳細資訊，請參閱 [CycloneDX](https://cyclonedx.org/)。 軟體物料清單說明特定套件版本元件的所有層面，例如套件資訊、檔案資訊和其他相關中繼資料。請參閱以下 SPDX 格式的軟體物料清單文件結構範例： ![\[SPDX 格式的 SBOM 範例。\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/images/spdx-2.3-document.png) ### 軟體物料清單優點 在 Software Package Catalog 中為套件版本新增軟體物料清單的主要優點之一是漏洞管理。 **漏洞管理** 評估和減輕軟體元件中明顯安全風險的漏洞，對於保護裝置機群的完整性至關重要。透過為每個套件版本新增儲存在軟體套件目錄中的軟體物料清單，您可以使用自己的內部漏洞管理解決方案，根據裝置套件版本和 SBOM 了解哪些裝置存在風險，主動公開安全漏洞。您可以將修正部署到受影響的裝置，並保護您的裝置機群。 ### 軟體物料儲存帳單 每個軟體套件版本的軟體物料清單 (SBOM) 會使用 Amazon S3 版本控制功能存放在 Amazon S3 儲存貯體中。存放 SBOM 的 Amazon S3 儲存貯體必須位於建立套件版本的相同區域中。使用版本控制功能的 Amazon S3 儲存貯體會維護相同儲存貯體中物件的多個變體。如需在 Amazon S3 儲存貯體中使用版本控制的詳細資訊，請參閱[在 Amazon S3 儲存貯體中使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 **注意** 每個軟體套件版本可以連接多個 SBOM 檔案，但 SBOM 檔案必須存放在單一 zip 封存檔案中。 儲存貯體的特定 Amazon S3 金鑰和版本 ID 是用來唯一識別套件版本之軟體物料清單的每個版本。 **注意** 對於具有單一 SBOM 檔案的套件版本，您可以將該 SBOM 檔案存放在 Amazon S3 儲存貯體中做為 zip 封存檔案。 對於具有多個 SBOM 檔案的套件版本，您必須將所有 SBOM 檔案放在單一 zip 封存檔案中，然後將該 zip 封存檔案存放在 Amazon S3 儲存貯體中。 在這兩種情況下，存放在單一 zip 封存檔案中的所有 SBOM 檔案都會格式化為 SPDX 或 CycloneDX .json 檔案。 **許可政策** 為了 AWS IoT 做為指定主體來存取存放在 Amazon S3 儲存貯體中的 SBOM zip 封存檔案，您需要資源型許可政策。如需正確的資源型許可政策，請參閱下列範例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "s3:*", "Resource": "arn:aws:s3:::bucketName/*" } ] } ``` 如需資源型許可政策的詳細資訊，請參閱 [AWS IoT 資源型政策](security_iam_service-with-iam.md#security_iam_service-with-iam-resource-based-policies) **更新 SBOM** 您可以視需要更新軟體物料清單，以保護和增強裝置機群。每次在 Amazon S3 儲存貯體中更新軟體物料清單時，版本 ID 都會變更，而且您必須將新的 Amazon S3 儲存貯體 URL 與適當的軟體套件版本建立關聯。您會在 的套件版本頁面上的 **Amazon S3 物件版本 ID 欄中看到新的版本 ID** AWS 管理主控台。此外，您可以使用 API 操作`[GetPackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPackageVersion.html)`或 CLI 命令`[get-package-version](https://docs.aws.amazon.com/cli/latest/reference/iot/get-package-version.html)`來檢視新版本 ID。 **注意** 更新您的軟體物料清單，這將導致新的版本 ID，不會導致建立新的套件版本。 如需 Amazon S3 物件金鑰的詳細資訊，請參閱[建立物件金鑰名稱](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)。 ## 啟用 AWS IoT 機群索引 啟用 AWS IoT 機群索引是使用 AWS IoT Device Management 軟體套件目錄的必要條件。若要使用 Software Package Catalog 利用 AWS IoT 機群索引，請將預留的具名影子 (`$package`) 設定為您要為其編製索引的每個裝置的資料來源，並收集指標。如需預留具名影子的詳細資訊，請參閱 [預留已命名影子](#reserved-named-shadow)。 機群索引提供支援，讓 AWS IoT 物件可透過依軟體套件版本篩選的動態物件群組進行分組。例如，機群索引可以識別已安裝或未安裝特定套件版本、未安裝任何套件版本或符合特定名稱/值配對的物件。最後，機群索引提供標準和自訂指標，您可以用來深入了解裝置機群的狀態。如需詳細資訊，請參閱[準備機群索引](preparing-fleet-indexing.md)。 **注意** 啟用軟體套件目錄的機群索引會產生標準服務費用。如需詳細資訊，請參閱 [AWS IoT Device Management定價](https://aws.amazon.com/iot-device-management/pricing/)。 ## 預留已命名影子 預留已命名影子 `$package` 會反映安裝於裝置的軟體套件和套件版本狀態。機群索引使用預留已命名影子做為資料來源，以建立標準和自訂指標，讓您可以查詢機群狀態。如需詳細資訊，請參閱[準備機群索引](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html)。 預留已命名影子類似[已命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)，但其名稱為預先定義，無法變更。此外，預留已命名影子不會隨中繼資料更新，且只會使用 `version` 和 `attributes` 關鍵字。 更新包含其他關鍵字的請求，例如 `description`，會在 `rejected`主題下收到錯誤回應。如需詳細資訊，請參閱[裝置影子錯誤訊息](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-error-messages.html)。 當您透過主控台建立 AWS IoT 物件、 AWS IoT 任務成功完成並更新影子，以及發出 [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API 操作時，都可以建立。如需詳細資訊，請參閱《 AWS IoT Core 開發人員指南》中的 [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-rest-api.html#API_UpdateThingShadow)。 **注意** 索引預留已命名影子不會計入機群索引可以索引的已命名影子數量。如需詳細資訊，請參閱 [AWS IoT Device Management 機群索引限制和配額](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。此外，如果您選擇讓 AWS IoT 任務在任務成功完成時更新保留的具名影子，則 API 呼叫會計入您的 Device Shadow 和登錄操作，並可能產生費用。如需詳細資訊，請參閱 [AWS IoT Device Management 任務限制和配額](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#job-limits)和 [IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html) API 資料類型。 **`$package` 影子的結構** 預留已命名影子包含以下內容： ``` { "state": { "reported": { "": { "version": "", "attributes": { } } } }, "version" : 1 "timestamp" : 1672531201 } ``` 影子屬性會更新為下列資訊： + ``：已安裝軟體套件的名稱，此套件會以 [PackageName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html#API_CreatePackage_RequestSyntax) 參數更新。 + `version`：已安裝套件版本的名稱，此版本會以 [versionName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) 參數更新。 + `attributes`：由裝置儲存並依機群索引編製索引的選用中繼資料。這可讓客戶根據儲存的資料查詢其索引。 + `version`：影子的版本號碼。每次影子更新並開始於 `1` 時，皆會自動遞增。 + `timestamp`：顯示上次影子更新時間並以 [Unix 時間](https://en.wikipedia.org/wiki/Unix_time)記錄。 如需詳細了解已命名影子的格式和行為，請參閱 [AWS IoT Device Shadow 服務 訊息順序](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html#message-ordering)。 ## 刪除軟體套件及其套件版本 刪除軟體套件之前，請執行下列動作： + 確認套件及其版本並未主動部署。 + 先刪除所有相關版本。若其中一個版本為**預設版本**，您必須從套件中移除具名預設版本。因為您不一定要指定預設版本，移除預設版本並不會造成衝突。若要從軟體套件中移除預設版本，請透過主控台或使用 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API 操作來編輯套件。 只要沒有具名預設套件版本，您便可以使用主控台刪除軟體套件，且其所有套件版本也將一併刪除。若您使用 API 呼叫來刪除軟體套件，您必須先刪除套件版本再刪除軟體套件。 # 準備安全性 本節討論 AWS IoT Device Management 軟體套件目錄的主要安全需求。 ## 以資源為基礎的身分驗證 軟體套件目錄在更新機群上的軟體時，會使用以資源為基礎的授權來提升安全性。這表示您必須建立 AWS Identity and Access Management (IAM) 政策，授予對軟體套件和套件版本執行 `create`、`delete`、、 和 `read` `update``list`動作的權限，並參考您想要在 `Resources`區段中部署的特定軟體套件和套件版本。您也需要這些權限，以便更新[預留已命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。您可以在每個實體中納入 Amazon Resource Name (ARN) 來參考軟體套件和套件版本。 **注意** 若您希望該政策能授予套件版本 API 呼叫的權限 (例如 [CreatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html)、[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)、[DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html))，則您必須在政策中*同時*納入軟體套件和套件版本 ARN。若您希望該政策能授予軟體套件 API 呼叫的權限 (例如 [CreatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html)、[UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html) 和 [DeletePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackage.html))，則您在政策中僅能納入軟體套件 ARN。 請遵循下方說明，建構軟體套件和套件版本 ARN： + 軟體套件：`arn:aws:iot:::package//package` + 套件版本：`arn:aws:iot:::package//version/` **注意** 您可能會在此政策中納入其他相關權利。例如，您可以會納入 `job`、`thinggroup` 和 `jobtemplate` 的 ARN。如需詳細資訊和政策選項的完整清單，請參閱[使用 AWS IoT 任務保護使用者和裝置](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-security.html)。 例如，若您有如下名稱的軟體套件和套件版本： + AWS IoT 物件： `myThing` + 套件名稱：`samplePackage` + 版本 `1.0.0` 該政策看起來類似以下範例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:createPackage", "iot:createPackageVersion", "iot:updatePackage", "iot:updatePackageVersion" ], "Resource": [ "arn:aws:iot:us-east-1:111122223333:package/samplePackage", "arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/1.0.0" ] }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow" ], "Resource": "arn:aws:iot:us-east-1:111122223333:thing/myThing/$package" } ] } ``` ## AWS IoT 部署套件版本的任務權限 基於安全考量，您必須授予部署套件和套件版本的權限，並為允許部署的特定套件和套件版本命名。若要執行這項動作，您可以建立 IAM 角色和政策，以授予透過套件版本部署任務的權限。政策必須將目的地套件版本指定為資源。 **IAM 政策** IAM 政策授予建立任務的權限，其中包含在 `Resource` 區段中命名的套件和版本。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:CreateJob", "iot:CreateJobTemplate" ], "Resource":[ "arn:aws:iot:*:111122223333:job/", "arn:aws:iot:*:111122223333:thing//$package", "arn:aws:iot:*:111122223333:thinggroup/", "arn:aws:iot:*:111122223333:jobtemplate/", "arn:aws:iot:*:111122223333:package//version/" ] } ] } ``` **注意** 如果您想要部署解除安裝軟體套件和套件版本的任務，您必須授權套件版本為 的 ARN`$null`，如下列所示： ``` arn:aws:iot::111122223333:package//version/$null ``` ## AWS IoT 更新預留具名影子的任務權限 若要允許任務在完成時更新物件的預留已命名影子，您必須建立 IAM 角色和政策。您可以在 AWS IoT 控制台透過兩種方式執行此動作。第一，在控制台建立軟體套件時。若您看到**啟用套件管理的相依性**對話方塊，您可以選擇使用現有角色或建立新角色。或者，在 AWS IoT 主控台選擇**設定**，接著選擇**管理索引**以及**管理裝置套件和版本的索引**。 **注意** 如果您選擇讓 AWS IoT 任務服務在任務成功完成時更新保留的具名影子，則 API 呼叫會計入您的 **Device Shadow 和登錄操作**，並可能產生費用。如需詳細資訊，請參閱 [AWS IoT Core 定價](https://aws.amazon.com/iot-core/pricing/)。 使用**建立角色**選項時產生的角色名稱開頭為 `aws-iot-role-update-shadows` 且包含下列政策： **設定角色** **許可** 權限政策授予查詢和更新物件影子的權限。資源 ARN 中的 `$package` 參數則針對預留已命名影子。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:DescribeEndpoint", "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow" ], "Resource": [ "arn:aws:iot:us-east-1:111122223333:thing//$package" ] } ] } ``` **信任關係** 除了權限政策之外，角色也需要與 AWS IoT Core 的信任關係，以便實體擔任該角色並更新預留已命名影子。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` **設定使用者政策** **iam:PassRole 權限** 最後，當您呼叫 [ UpdatePackageConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageConfiguration.html) API 操作 AWS IoT Core 時，您必須擁有將角色傳遞至 的許可。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "iot:UpdatePackageConfiguration" ], "Resource": "arn:aws:iam::111122223333:role/" } ] } ``` ## AWS IoT 從 Amazon S3 下載的任務許可 任務文件會儲存於 Amazon S3。當您透過 AWS IoT 任務分派時，您會參考此檔案。您必須提供 AWS IoT Jobs 下載檔案 (`s3:GetObject`) 的權限。您還必須在 Amazon S3 和 AWS IoT 任務之間設定信任關係。如需建立這些政策的指示，請參閱[管理任務](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html)中的[預先簽章的 URL](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-presigned-URLs)。 ## 更新套件版本之軟體物料清單的許可 若要更新 `Draft`、 `Published`或 `Deprecated`生命週期狀態中套件版本的軟體物料清單，您需要 AWS Identity and Access Management 角色和政策，才能在 Amazon S3 中尋找新的軟體物料清單，並更新套件版本 AWS IoT Core。 首先，您會將更新的軟體物料清單放在版本控制的 Amazon S3 儲存貯體中，並使用包含的 `sboms` 參數呼叫 `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API 操作。接下來，您的授權委託人將擔任您建立的 IAM 角色，在 Amazon S3 中尋找更新的軟體物料清單，並在 中更新軟體套件目錄 AWS IoT Core 的套件版本。 執行此更新需要下列政策： **政策** + **信任政策** 與擔任 IAM 角色的授權委託人建立信任關係，以便從 Amazon S3 中的版本控制儲存貯體找到更新的軟體物料清單，並在其中更新套件版本 AWS IoT Core。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` + **許可政策**：存取 Amazon S3 版本控制的儲存貯體的政策，其中儲存套件版本的軟體物料清單，並更新套件版本 AWS IoT Core。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::awsexamplebucket1" ] } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:UpdatePackageVersion" ], "Resource": [ "arn:aws:iot:*:111122223333:package//version/" ] } ] } ``` + **傳遞角色許可**：當您呼叫 `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API 操作 AWS IoT Core 時，授予許可將 IAM 角色傳遞至 Amazon S3 的政策。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::awsexamplebucket1" ] } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "iot:UpdatePackageVersion" ], "Resource": "arn:aws:iam::111122223333:role/" } ] } ``` **注意** 您無法更新已轉換為`Deleted`生命週期狀態之套件版本的軟體物料清單。 如需為 AWS 服務建立 IAM 角色的詳細資訊，請參閱[建立角色以將許可委派給 AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。 如需建立 Amazon S3 儲存貯體並上傳物件的詳細資訊，請參閱[建立儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)和[上傳物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)。 # 準備機群索引 使用 AWS IoT 機群索引，您可以使用預留的具名影子 () 來搜尋和彙總資料`$package`。您也可以透過查詢 [預留已命名影子](preparing-to-use-software-package-catalog.md#reserved-named-shadow)和動態 AWS IoT 物件群組來分組物件。 [https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)例如，您可以找到哪些 AWS IoT 物件使用特定套件版本、未安裝特定套件版本，或未安裝任何套件版本的相關資訊。您可以組合屬性以獲得進一步分析。例如，識別具有特定版本且屬於特定物件類型的物件 （例如 1.0.0 版和 pump\$1sensor 的物件類型）。如需詳細資訊，請參閱[機群索引](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html)。 ## 將 `$package` 影子設定為資料來源 若要搭配使用機群索引與軟體套件目錄，您必須啟用機群索引、將已命名影子設定為資料來源，並定義 `$package` 為已命名影子篩選條件。若您尚未啟用機群索引，您可以在此程序中啟用。在主控台的 [AWS IoT Core](https://console.aws.amazon.com/iot/home) 開啟**設定**，選擇**管理索引**，接著選擇**新增已命名影子**、**新增裝置軟體套件和版本**，以及**更新**。如需詳細資訊，請參閱[管理物件索引](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#thing-index)。 或者，您也可以在建立第一個套件時啟用機群索引。當**啟用套件管理的相依性**對話方塊出現時，請選擇將裝置軟體套件和版本新增為資料來源至機群索引。透過此選項，您也可以啟用機群索引。 **注意** 啟用軟體套件目錄的機群索引會產生標準服務費用。如需詳細資訊，請參閱 [AWS IoT Device Management定價](https://aws.amazon.com/iot-device-management/pricing/)。 ## 控制台顯示的指標 ![\[標準指標影像\]](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/images/package-catalog-discovery-metrics.png) 在 AWS IoT 主控台軟體套件詳細資訊頁面上，**探索**面板會顯示透過`$package`影子擷取的標準指標。 + **目前版本分佈**圖顯示 10 個最新套件版本的裝置數量和百分比，這些套件版本與與此軟體套件相關聯的所有裝置中的 AWS IoT 物件相關聯。**注意：**若軟體套件的套件版本多於圖表中標示的版本，您在**其他**中會發現它們已分組。 + **歷史圖表**會顯示指定期間內，與所選套件版本相關聯的裝置數量。圖表一開始會是空白的，您可以選取最多 5 個套件版本並定義日期範圍和時間間隔。若要選取圖表的參數，請選擇**設定**。**歷史圖表**顯示的資料可能與**目前版本分佈**圖表不同，這是因為兩者顯示的套件版本數量不同，也因為**歷史圖表**可以選擇要分析哪些套件版本。**注意：**選取要進行視覺化的套件版本時，會計入機群指標限制的上限數量。如需詳細資訊，請參閱[機群索引限制和配額](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。 如需了解收集套件版本分佈的其他方法，請參閱[透過 `getBucketsAggregation` 收集套件版本分佈](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html#package-version-distribution)。 ## 查詢模式 軟體套件目錄的機群索引使用大多數標準支援的功能 （例如詞彙、片語和搜尋欄位）。不過，比較運算子 （例如，小於`<`和大於 `>`) 和`range`查詢不適用於保留的具名影子 (`$package`) `version`索引鍵。這些查詢可用於 `attributes`金鑰。如需詳細資訊，請參閱[查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。 ### 範例資料 **注意：**如需詳細了解預留已命名影子及其結構，請參閱[預留已命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。 在此範例中，第一部裝置名為 `AnyThing` 且已安裝下列套件： + 軟體套件：`SamplePackage` 套件版本：`1.0.0` 套件 ID：`1111` 影子如下所示： ``` { "state": { "reported": { "SamplePackage": { "version": "1.0.0", "attributes": { "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1", "packageID": "1111" } } } } } ``` 第二部裝置名為 `AnotherThing` 且已安裝下列套件： + 軟體套件：`SamplePackage` 套件版本：`1.0.0` 套件 ID：`1111` + 軟體套件：`OtherPackage` 套件版本：`1.2.5` 套件 ID：`2222` 影子如下所示： ``` { "state": { "reported": { "SamplePackage": { "version": "1.0.0", "attributes": { "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1", "packageID": "1111" } }, "OtherPackage": { "version": "1.2.5", "attributes": { "s3UrlForOtherPackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile2", "packageID": "2222" } }, } } } ``` ### 範例查詢 下表列出根據 `AnyThing` 和 `AnotherThing` 範例裝置影子的查詢範例。如需詳細資訊，請參閱[範例物件查詢](https://docs.aws.amazon.com/iot/latest/developerguide/example-queries.html)。 **FreeRTOS AWS IoT Device Tester 的最新版本** | **已請求的資訊** | **Query** | **結果** | | --- | --- | --- | | 已安裝特定套件版本的物件 | `shadow.name.$package.reported.SamplePackage.version:1.0.0` | `AnyThing`, `OtherThing` | | 未安裝特定套件版本的物件 | `NOT shadow.name.$package.reported.OtherPackage.version:1.2.5` | `AnyThing` | | 所使用套件版本的套件 ID 大於 1500 的任何裝置 | `shadow.name.$package.reported.*.attributes.packageID>1500"` | `OtherThing` | | 已安裝特定套件且安裝多個套件的物件 | `shadow.name.$package.reported.SamplePackage.version:1.0.0 AND shadow.name.$package.reported.totalCount:2` | `OtherThing` | ## 透過 `getBucketsAggregation` 收集套件版本分佈 除了 AWS IoT 主控台中的**探索**面板之外，您也可以使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html) API 操作取得套件版本分佈資訊。若要取得套件版本分佈資訊，您必須執行下列動作： + 在機群索引中為每個軟體套件定義自訂欄位。**注意：**建立自訂欄位會計入 [AWS IoT 機群索引服務配額](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。 + 自訂欄位的格式如下所示： `shadow.name.$package.reported..version` 如需詳細資訊，請參閱 AWS IoT 機群索引中的[自訂欄位](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#custom-field)區段。 # 準備 AWS IoT 任務 AWS IoT Device Management Software Package Catalog 透過替代參數擴展 AWS IoT 任務，並與 AWS IoT 機群索引、動態物件群組以及 AWS IoT 物件預留的具名影子整合。 **注意** 若要使用軟體套件目錄提供的所有功能，您必須建立這些 AWS Identity and Access Management (IAM) 角色和政策：[AWS IoT 部署套件版本的任務權限](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-deploy-versions)和[AWS IoT 更新預留具名影子的任務權限](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-update-reserved-named-shadow)。如需詳細資訊，請參閱[準備安全性](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html)。 ## AWS IoT 任務的替代參數 您可以使用替代參數做為 AWS IoT 任務文件中的預留位置。當任務服務遇到替換參數時，會將任務指向參數值的具名軟體版本屬性。您可以使用此程序建立單一任務文件，並透過一般用途屬性將中繼資料傳遞至任務。例如，您可以透過套件版本屬性將 Amazon Simple Storage Service (Amazon S3) URL、軟體套件 Amazon Resource Name (ARN) 或簽章傳遞至任務文件。 替代參數應該在任務文件中格式化，如下所示： + **軟體套件名稱和套件版本** + 之間的空字串`package::version`代表軟體套件名稱替換參數。之間的空字串`version::attribute`代表軟體套件版本替換參數。請參閱下列範例，以使用任務文件中的套件名稱和套件版本取代參數：`${aws:iot:package::version::attributes:}`。 + 任務文件將使用套件*版本詳細資訊中的版本 ARN* 自動填入這些取代參數。如果您使用 API 或 CLI 命令為單一套件部署建立任務或任務範本，則套件版本的*版本 ARN* 會以 `CreateJob`和 中的 `destinationPackageVersions` 參數表示`DescribeJob`。 + **軟體套件版本的所有屬性** + 請參閱下列範例，以了解在任務文件中使用軟體套件版本替換參數的所有屬性： `${aws:iot:package::version::attributes}` **注意** 套件名稱、套件版本和所有屬性替代參數可以一起使用。請參閱下列範例，以使用任務文件中所有三個替代參數： `${aws:iot:package::version::attributes}` 在下列範例中，有一個名為 的軟體套件，`samplePackage`並且有一個名為 `2.1.5` 的套件版本，具有下列屬性： + 名稱：`s3URL`，值：`https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile` + 此屬性會識別儲存於 Amazon S3 的程式碼檔案位置。 + 名稱：`signature`，值：`aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj` + 此屬性會提供裝置做為安全措施所需的程式碼簽章值。如需詳細資訊，請參閱[適用於任務的程式碼簽署](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-code-signing)。**注意：**此屬性僅為範例，不是軟體套件目錄或任務的必要部分。 針對 `s3URL`，任務文件參數的寫入方式如下： ``` { "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" } ``` 針對 `signature`，任務文件參數的寫入方式如下： ``` { "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" } ``` 完整的任務文件寫入方式如下： ``` { ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" }, ], "signature": [ "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" ] } } ``` 進行替換後，下列任務文件會部署至裝置： ``` { ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile" }, ], "signature": [ "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj" ] } } ``` **替代參數 （檢視之前和之後）** 替代參數使用各種旗標簡化任務文件的建立，例如`$default`預設套件版本。這樣就不需要為每個任務部署手動輸入特定套件版本中繼資料，因為這些旗標會在特定套件版本中自動填入參考的中繼資料。如需套件版本屬性的詳細資訊，例如`$default`預設套件版本的 ，請參閱 [準備任務文件和套件版本以進行部署](#preparing-to-deploy)。 在 中 AWS 管理主控台，在套件版本的任務部署期間，切換*部署指示檔案編輯器*視窗中的*預覽替代*按鈕，以檢視包含和不含替代參數的任務文件。 使用 `DescribeJob`和 `GetJobDocument` APIs中的「替代前」參數，您可以在移除替代參數之前和之後檢視 API 回應。請參閱下列使用 `DescribeJob`和 `GetJobDocument` APIs的範例： + `DescribeJob` + 預設檢視 ``` { "jobId": "", "description": "", "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"] } ``` + 取代檢視之前 ``` { "jobId": "", "description": "", "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"] } ``` + `GetJobDocument` + 預設檢視 ``` { "attributes": { "location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core", "signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI", "streamName": "mqtt-core", "fileId": "0" }, } ``` + 取代檢視之前 ``` { "attributes": "${aws:iot:package:TestPackage:version:$default:attributes}", } ``` 如需 AWS IoT 任務、建立任務文件和部署任務的詳細資訊，請參閱[任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)。 ## 準備任務文件和套件版本以進行部署 建立套件版本時，它處於 `draft` 狀態，表示它正在準備部署。若要準備套件版本以供部署，您必須建立任務文件、將文件儲存在任務可存取的位置 （例如 Amazon S3)，並確認套件版本具有您希望任務文件使用的屬性值。（注意：您只能在套件版本處於 `draft` 狀態時更新其屬性。) 當您為單一套件部署建立 AWS IoT 任務或任務範本時，您有下列選項可自訂您的任務文件： **部署指示檔案 (`recipe`)** + 套件版本的部署指示檔案包含部署指示，包括內嵌任務文件，用於將套件版本部署到多個裝置。檔案會將特定部署指示與套件版本建立關聯，以快速且有效率地進行任務部署。 在 中 AWS 管理主控台，您可以在建立新套件工作流程的*版本部署組態*索引標籤的*部署指示檔案預覽*視窗中建立 檔案。您可以利用 從*建議的檔案中使用 Start 從 AWS IoT *套件版本屬性 AWS IoT 自動產生指令檔案，或使用存放在 Amazon S3 儲存貯體中的現有任務文件*使用您自己的部署指令檔案*。 **注意** 如果您使用自己的任務文件，可以直接在*部署指示檔案預覽*視窗中更新，但不會自動更新存放在 Amazon S3 儲存貯體中的原始任務文件。 使用 AWS CLI 或 API 命令，例如 `CreatePackageVersion`、 `GetPackageVersion`或 時`UpdatePackageVersion`， `recipe`代表部署指令檔案，其中包含內嵌任務文件。 如需任務文件的詳細資訊，請參閱 [基本概念](key-concepts-jobs.md#basic-concepts-jobs)。 請參閱下列範例以取得 部署指示檔案，如 所示`recipe`： ``` { "packageName": "sample-package-name", "versionName": "sample-package-version", ... "recipe": "{...}" } ``` **注意** 當套件版本處於 `published` 狀態時，`recipe`可以更新 表示的部署指示檔案，因為它與套件版本中繼資料分開。它在任務部署期間變得不可變。 **`Artifact` 版本屬性** + 您可以在軟體套件版本`artifact`中使用版本屬性，為套件版本成品新增 Amazon S3 位置。使用 AWS IoT Jobs 觸發套件版本的任務部署時，任務文件中預先簽章的 URL 預留位置將使用 Amazon S3 儲存貯` ${aws:iot:package::version::artifact-location:s3-presigned-url}`體、儲存貯體金鑰和存放在 Amazon S3 儲存貯體中的檔案版本進行更新。儲存套件版本成品的 Amazon S3 儲存貯體所在區域必須與建立套件版本的區域相同。 **注意** 若要將相同檔案的多個物件版本儲存在 Amazon S3 儲存貯體中，您必須在儲存貯體上啟用版本控制。如需詳細資訊，請參閱在[儲存貯體上啟用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html)。 若要在使用 `CreatePackageVersion`或 `UpdatePackageVersion` API 操作時存取 Amazon S3 儲存貯體中的套件版本成品，您必須具有下列許可： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObjectVersion", "Resource": "arn:aws:s3:::bucket-name/key-name" } ] } ``` 如需 `CreatePackageVersion`和 `UpdatePackageVersion` API 操作`artifact`中版本屬性的詳細資訊，請參閱 [CreatePackageVersion](https://amazonaws.com/iot/latest/apireference/API_CreatePackageVersion.html) 和 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)。 請參閱下列範例，其中顯示建立新套件版本時`artifact`支援 Amazon S3 中成品位置的版本屬性： ``` { "packageName": "sample package name", "versionName": "1.0", "artifact": { "s3Location": { "bucket": "firmware", "key": "image.bin", "version": "12345" } } } ``` **注意** 當套件版本從`draft`狀態狀態更新為`published`狀態時，套件版本屬性和關節位置會變得不可變。若要更新此資訊，您需要建立新的套件版本，並在`draft`處於 狀態時執行這些更新。 **套件版本** + 預設軟體套件版本可以在軟體套件的可用版本中表示，以提供安全且穩定的套件版本。在使用 AWS IoT Jobs 將預設套件版本部署到裝置機群時，這可做為軟體套件的基準版本。建立任務以部署軟體`$default`套件的套件版本時，任務文件和新任務部署中的套件版本必須與 相符`$default`。任務部署中的套件版本由 表示`destinationPackageVersions`，適用於 API 和 CLI 命令，以及 `VersionARN`中的 AWS 管理主控台。任務文件中的套件版本由下列任務文件預留位置表示，如下所示： ``` arn:aws:iot::111122223333:package//version/$default ``` 若要使用預設套件版本建立任務或任務範本，請使用 `CreateJob`或 `CreateJobTemplate` API 命令中的 `$default`旗標，如下所示： ``` "$ aws iot create-job \ --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default" --document file://jobdoc.json ``` **注意** 參考預設版本的`$default`套件版本屬性是選用屬性，只有在透過 AWS IoT Jobs 參考任務部署的預設套件版本時才需要。 當您滿意套件版本時，請透過 AWS IoT 主控台中的軟體套件詳細資訊頁面或發出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API 操作來發佈套件版本。然後，您可以在透過 AWS IoT 主控台或發出 [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API 操作建立任務時參考套件版本。 ## 部署時命名套件和版本 若要將軟體套件版本部署至裝置，請確認任務文件中參考的軟體套件和套件版本符合 `CreateJob` API 操作中 `destinationPackageVersions` 參數中所述的軟體套件和套件版本。如果不相符，您會收到錯誤訊息，提示您使兩個參考相符。如需軟體套件目錄錯誤訊息的詳細資訊，請參閱 [對錯誤訊息進行一般故障診斷](software-package-catalog-troubleshooting.md#spc-general-troubleshooting)。 除了任務文件中參考的軟體套件和套件版本之外，您還可以在任務文件中未參考的 `CreateJob` API 操作中的 `destinationPackageVersions` 參數中包含其他軟體套件和套件版本。確保裝置的任務文件中包含必要的安裝資訊，以正確安裝其他軟體套件版本。如需 `CreateJob `API 操作的詳細資訊，請參閱 [CreateJob](https://amazonaws.com/iot/latest/apireference/API_CreateJob.html)。 ## 透過 AWS IoT 動態物件群組將任務設為目標 軟體套件目錄可與[機群索引](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html)、[AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)和[AWS IoT 動態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)搭配使用，以篩選並鎖定機群中的裝置，選取要部署至裝置的套件版本。您可以根據裝置目前的套件資訊執行機群索引查詢，並將這些物件設為 AWS IoT 任務的目標。您也可以發行軟體更新，但僅限符合資格的目標裝置。例如，您可以指定只要將組態部署到目前執行 `iot-device-client 1.5.09` 的裝置。如需詳細資訊，請參閱[建立動態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group)。 ## 預留已命名影子和套件版本 如果已設定， AWS IoT Jobs 可以在任務成功完成時更新物件的預留具名影子 (`$package`)。如此一來，您便不需要手動將套件版本與物件的預留已命名影子建立關聯。 在下列情況下，您可以選擇手動更新套件版本，或將其與物件的預留已命名影子建立關聯： + 您可以將物件註冊到 ， AWS IoT Core 而不關聯已安裝的套件版本。 + AWS IoT 任務未設定為更新物件的預留具名影子。 + 您可以使用內部程序將套件版本分派至您的機群，該程序不會在完成 AWS IoT Core 時更新。 **注意** 我們建議您使用 AWS IoT Jobs 來更新預留具名影子 () 中的套件版本`$package`。當 AWS IoT 工作也設定為更新影`$package`子時，透過其他程序 （例如手動或程式設計 API 呼叫） 更新影子中的版本參數，可能會導致裝置的實際版本與報告給預留具名影子的版本之間不一致。 您可以透過主控台或 [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API 操作，將套件版本新增或更新至物件的預留已命名影子 (`$package`)。如需詳細資訊，請參閱[將套件版本與 AWS IoT 物件建立關聯](https://docs.aws.amazon.com/iot/latest/developerguide/associating-package-version.html)。 **注意** 將套件版本與 AWS IoT 物件建立關聯並不會直接更新裝置軟體。您必須將套件版本部署至裝置，才能更新裝置軟體。 ## 解除安裝軟體套件及其套件版本 `$null` 是預留預留位置，提示 AWS IoT Jobs 服務從裝置的預留具名影子 中移除現有的軟體套件和套件版本`$package`。如需詳細資訊，請參閱[預留已命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。 若要使用此功能，請將 [destinationPackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html#iot-CreateJobTemplate-request-destinationPackageVersions) Amazon Resource Name (ARN) 結尾的版本名稱取代為 `$null`。之後，您必須指示您的服務從裝置中移除軟體。 授權的 ARN 使用以下格式： ``` arn:aws:iot::111122223333:package//version/$null ``` 例如 ``` $ aws iot create-job \ ... \ --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"] ``` # 開始使用軟體套件目錄 您可以透過 AWS 管理主控台、 AWS IoT Core API 操作和 AWS Command Line Interface () 來建置和維護 AWS IoT Device Management 軟體套件目錄AWS CLI。 **注意** 啟用 AWS IoT 機群索引是使用軟體套件目錄的必要條件。基本操作，例如在 中建立軟體套件版本 AWS 管理主控台 ，以及使用 `CreatePackage` API 命令，會在未啟用 AWS IoT 機群索引的情況下失敗。 如需搭配 Software Package Catalog 使用 AWS IoT 機群索引的詳細資訊，請參閱 [準備機群索引](preparing-fleet-indexing.md)。 **使用主控台** 若要使用 AWS 管理主控台，請登入 AWS 您的帳戶並導覽至 [AWS IoT Core](https://console.aws.amazon.com/iot/home)。在導覽窗格中，選擇**軟體套件**。然後，您可以從本章節建立管理套件及其版本。 **使用 API 或 CLI 操作** 您可以使用 AWS IoT Core API 操作來建立和管理 Software Package Catalog 功能。如需詳細資訊，請參閱 [AWS IoT API 參考](https://docs.aws.amazon.com/iot/latest/apireference/)和 [AWS SDK 與工具組](https://aws.amazon.com/developer/tools/)。這些 AWS CLI 命令也會管理您的目錄。如需詳細資訊，請參閱 [AWS IoT CLI 指令參考](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html)。 **Topics** + [建立軟體套件和套件版本](creating-package-and-version.md) + [透過 AWS IoT 任務部署套件版本](deploying-package-version.md) + [將套件版本與 AWS IoT 物件建立關聯](associating-package-version.md) # 建立軟體套件和套件版本 您可以使用下列步驟，透過 AWS 管理主控台建立套件和初始版本物件。 **若要建立軟體套件** 1. 登入 AWS 您的帳戶並導覽至 [AWS IoT 主控台](https://console.aws.amazon.com/iot/home)。 1. 在導覽窗格中，選擇**軟體套件**。 1. 在 **AWS IoT 軟體套件**頁面上，選擇**建立套件**。**啟用套件管理的相依性**對話方塊隨即出現。 1. 在**機群索引**下，選取**新增裝置軟體套件和版本**。這是軟體套件目錄的必要條件，並會提供機群的機群索引和指標。 1. 【選用】 如果您想要 AWS IoT 任務在任務成功完成時更新保留的具名影子，請選取**從任務自動更新影子**。如果您不希望 AWS IoT 任務進行此更新，請取消選取此核取方塊。 1. 【選用】 若要授予 AWS IoT 任務更新預留具名影子的權限，請在**選取角色**下選擇**建立角色**。如果您不希望 AWS IoT 任務進行此更新，則不需要此角色。 1. 建立或選取角色。 1. 若您**沒有此用途的角色**：顯示**建立角色**對話方塊時，請輸入**角色名稱**，然後選擇**建立**。 1. 若您**具有此用途的角色**：針對**選取角色**，請選擇您的角色，然後確定已選取**將政策附加至 IAM 角色**核取方塊。 1. 選擇**確認**。**建立新套件**頁面隨即出現。 1. 在**套件詳細資訊**下，輸入**套件名稱**。 1. 在**套件描述**下，輸入相關資訊協助您識別管理此套件。 1. [選用] 您可以使用標籤來協助您分類管理此套件。若要新增標籤，請展開**標籤**，選擇**新增**標籤，然後輸入金鑰-值配對。您最多可輸入 50 個標籤。如需詳細資訊，請參閱[標記您的 AWS IoT 資源](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html)。 **若要在建立新套件時新增套裝版本** 1. 在**初始版本**下，輸入**版本名稱**。 建議您使用 [SemVer 格式](https://semver.org/) (例如 `1.0.0.0`) 來專屬識別您的套件版本。您也可以使用更適合您使用案例的其他格式方式。如需詳細資訊，請參閱[套件版本生命週期](preparing-to-use-software-package-catalog.md#package-version-lifecycle)。 1. 在**版本描述**下，輸入相關資訊協助您識別管理此套件版本。 **注意** **預設版本**核取方塊會停用，因為套件版本是在 `draft` 狀態下建立的。您可以在建立套件版本之後，以及將狀態變更為 時，命名預設版本`published`。如需詳細資訊，請參閱[套件版本生命週期](preparing-to-use-software-package-catalog.md#package-version-lifecycle)。 1. [選用] 若要協助您管理此版本或將資訊傳送給您的裝置，請為**版本屬性**輸入一或多個名稱/值配對。為您輸入的每個名稱/值配對選擇**新增屬性**。如需詳細資訊，請參閱[版本屬性](preparing-to-use-software-package-catalog.md#version-attributes)。 1. [選用] 您可以使用標籤來協助您分類管理此套件。若要新增標籤，請展開**標籤**，選擇**新增**標籤，然後輸入金鑰-值配對。您最多可輸入 50 個標籤。如需詳細資訊，請參閱[標記您的 AWS IoT 資源](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html)。 1. 選擇**下一步**。 **將軟體物料清單與套件版本建立關聯 （選用）** 1. 在**步驟 3：SBOMs（選用）** 上，選擇預設 SBOM 檔案格式和驗證模式，用於驗證您的軟體物料清單，然後再與套件版本相關聯。 **** 1. 在**新增 SBOM 檔案**視窗中，輸入代表您版本控制的 Amazon S3 儲存貯體的 Amazon Resource Name (ARN)，如果預設類型無法運作，則輸入偏好的 SBOM 檔案格式。 **注意** 如果您的套件版本有多個軟體物料清單，您可以新增單一 SBOM 檔案或包含多個 SBOMs 的單一 zip 檔案。 1. 在**新增的 SBOM 檔案**視窗中，您可以檢視您為套件版本新增的 SBOM 檔案。 1. 選擇**建立套件和版本**。套件版本頁面隨即出現，您可以在**新增的 SBOM 檔案視窗中查看 SBOM 檔案**的驗證狀態。當 SBOM 檔案經過驗證`In progress`時，初始狀態將為 。 **注意** SBOM 檔案驗證狀態為 `Invalid file`、`Not started`、`Validated (CycloneDX)`、、 `In progress` `Validated (SPDX)`和驗證失敗原因。 # 透過 AWS IoT 任務部署套件版本 您可以使用下列步驟，透過 AWS 管理主控台部署套件版本。 **先決條件：** 開始之前，請執行以下動作： + 向 註冊 AWS IoT 物件 AWS IoT Core。如需將裝置新增至其中的指示 AWS IoT Core，請參閱[建立物件](https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing)。 + 【選用】 建立 AWS IoT 物件群組或動態物件群組，以您要部署套件版本的裝置為目標。如需相關指示建立物件群組，請參閱[建立靜態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html#create-thing-group)。如需相關指示建立動態物件群組，請參閱[建立動態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group)。 + 建立軟體套件和套件版本。如需詳細資訊，請參閱[建立軟體套件和套件版本](creating-package-and-version.md)。 + 建立任務文件。如需詳細資訊，請參閱[準備任務文件和套件版本以進行部署](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#preparing-to-deploy)。 **部署 AWS IoT 任務** 1. 在 [AWS IoT 主控台](https://console.aws.amazon.com/iot/home)上，選擇**軟體套件**。 1. 選擇您要部署的軟體套件。**軟體套件詳細資訊**頁面隨即顯示。 1. 在**版本**之下選擇您要部署的套件版本，然後選擇**部署任務版本**。 1. 若這是您第一次透過此入口網站部署任務，您會看到附有規範說明的對話方塊。請檢閱資訊，然後選擇**確認**。 1. 輸入部署操作的名稱，或在**名稱**欄位保留自動產生的名稱。 1. [選用] 在**描述**欄位中，輸入識別部署目的或內容的描述，或保留自動產生的資訊。 **注意：**建議您不要在任務名稱和描述欄位中使用個人識別資訊。 1. [選用] 新增任何要與此任務建立關聯的標籤。 1. 選擇**下一步**。 1. 在**任務目標**之下，選擇應負責接收任務的物件或物件群組。 1. 在**任務檔案**欄位中，指定任務文件 JSON 檔案。 1. 開啟**與套件目錄服務整合的任務**。 1. 選取任務文件中所指定的套件和版本。 **注意** 您必須選擇在任務文件中所指定的相同套件和套件版本。您可以納入更多項目，但該任務只會針對任務文件中包含的套件和版本發出指示。如需詳細資訊，請參閱[部署時命名套件和版本](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#naming-package-versions)。 1. 選擇**下一步**。 1. 在任務組態頁面上，選取任務組態對話方塊中下列任一任務類型： + **快照任務**：快照任務在目標裝置和群組上完成執行後即完成。 + **連續任務**：連續任務適用於物件群組，並在稍後新增至所指定目標群組的任何裝置上執行。 1. 在**其他組態 - 選用**對話方塊中，檢閱下列選用任務組態，並視需要進行選擇。如需詳細資訊，請參閱[任務推展、排程和中止組態](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-rollout-abort-scheduling)和[任務執行逾時和重試組態](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-timeout-retry)。 + 推展組態 + Scheduling configuration (排程組態) + 任務執行逾時組態 + 任務執行重試組態 + 中止組態 1. 檢視任務選擇，然後選擇**送出**。 建立任務後，主控台會產生 JSON 簽章，並將其放置在您的任務文件中。您可以使用 AWS IoT 主控台來檢視任務的狀態，或取消或刪除任務。若要管理任務，請前往[主控台的任務中心](https://console.aws.amazon.com/iot/home#/jobhub)。 # 將套件版本與 AWS IoT 物件建立關聯 在裝置上安裝軟體後，您可以將套件版本與 AWS IoT 物件的預留具名影子建立關聯。如果 AWS IoT 任務已設定為在任務部署並成功完成之後更新物件的預留具名影子，則您不需要完成此程序。如需詳細資訊，請參閱[預留已命名影子](preparing-to-use-software-package-catalog.md#reserved-named-shadow)。 **先決條件：** 開始之前，請執行以下動作： + 建立 AWS IoT 實物或實物，並透過 建立遙測 AWS IoT Core。如需詳細資訊，請參閱 [入門 AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)。 + 建立軟體套件和套件版本。如需詳細資訊，請參閱[建立軟體套件和套件版本](creating-package-and-version.md)。 + 在裝置上安裝套件版本軟體。 **注意** 將套件版本與 AWS IoT 物件建立關聯並不會在實體裝置上更新或安裝軟體。套件版本必須部署至裝置。 **將套件版本與 AWS IoT 物件建立關聯** 1. 在 [AWS IoT 主控台](https://console.aws.amazon.com/iot/home)瀏覽窗格中，展開**所有裝置**選單，然後選擇**物件**。 1. 從清單中識別您要更新的 AWS IoT 物件，然後選擇物件名稱以顯示其詳細資訊頁面。 1. 在**詳細資訊**區段中，選擇**套件和版本**。 1. 選擇**新增至套件和版本**。 1. 針對**選擇裝置套件**，選擇您想要的軟體套件。 1. 針對**選擇版本**，選擇您想要的軟體版本。 1. 選擇**新增裝置套件**。 套件和版本會顯示在**所選套件和版本**清單中。 1. 針對您要與此物件建立關聯的每個套件和版本重複這些步驟。 1. 完成後，請選擇**新增套件和版本詳細資訊**。**物件詳細資訊**頁面隨即開啟，您可以在清單中看到新的套件與版本。