本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 準備使用軟體套件目錄 下節提供套件版本生命週期的概觀，以及使用 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 呼叫來刪除軟體套件，您必須先刪除套件版本再刪除軟體套件。