本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 準備 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:<{{packageName}}>:version:<{{versionName}}>: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"] ```