最低 SDK 版本授權 CreateLocalDeployment ListLocalDeployments GetLocalDeploymentStatus ListComponents GetComponentDetails RestartComponent StopComponent CreateDebugPassword

管理本機部署和元件

注意

此功能適用於 2.6.0 版及更新的 Greengrass 核元件。

使用 Greengrass CLI IPC 服務來管理核心裝置上的本機部署和 Greengrass 元件。

若要使用這些 IPC 操作，請在您的自訂元件中包含 2.6.0 版或更新版本的 Greengrass CLI 元件做為相依性。然後，您可以在自訂元件中使用 IPC 操作來執行下列動作：

建立本機部署以修改和設定核心裝置上的 Greengrass 元件。
在核心裝置上重新啟動和停止 Greengrass 元件。
產生可用來登入本機偵錯主控台的密碼。

最低 SDK 版本

下表列出 AWS IoT Device SDK 您必須用來與 Greengrass CLI IPC 服務互動的最低版本。

SDK	最低版本
AWS IoT Device SDK 適用於 Java v2	v1.2.10
AWS IoT Device SDK for Python v2	1.5.3 版
AWS IoT Device SDK 適用於 C++ v2	1.17.0 版
AWS IoT Device SDK for JavaScript v2	v1.12.0

授權

若要在自訂元件中使用 Greengrass CLI IPC 服務，您必須定義授權政策，允許元件管理本機部署和元件。如需定義授權政策的資訊，請參閱授權元件來執行 IPC 操作。

Greengrass CLI 的授權政策具有下列屬性。

IPC 服務識別符： aws.greengrass.Cli

作業	描述	資源
`aws.greengrass#CreateLocalDeployment`	允許元件在核心裝置上建立本機部署。	`*`
`aws.greengrass#ListLocalDeployments`	允許元件列出核心裝置上的本機部署。	`*`
`aws.greengrass#GetLocalDeploymentStatus`	允許元件取得核心裝置上本機部署的狀態。	本機部署 ID，或 `*` 允許存取所有本機部署。
`aws.greengrass#ListComponents`	允許元件列出核心裝置上的元件。	`*`
`aws.greengrass#GetComponentDetails`	允許元件取得核心裝置上元件的詳細資訊。	元件名稱，例如 `com.example.HelloWorld`或 `*` 允許存取所有元件。
`aws.greengrass#RestartComponent`	允許元件重新啟動核心裝置上的元件。	元件名稱，例如 `com.example.HelloWorld`或 `*` 允許存取所有元件。
`aws.greengrass#StopComponent`	允許元件停止核心裝置上的元件。	元件名稱，例如 `com.example.HelloWorld`或 `*` 允許存取所有元件。
`aws.greengrass#CreateDebugPassword`	允許元件產生密碼，以使用登入本機偵錯主控台元件。	`*`

範例授權政策範例

下列範例授權政策允許元件建立本機部署、檢視所有本機部署和元件，以及重新啟動和停止名為的元件com.example.HelloWorld。


{
  "accessControl": {
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:1": {
        "policyDescription": "Allows access to create local deployments and view deployments and components.",
        "operations": [
          "aws.greengrass#CreateLocalDeployment",
          "aws.greengrass#ListLocalDeployments",
          "aws.greengrass#GetLocalDeploymentStatus",
          "aws.greengrass#ListComponents",
          "aws.greengrass#GetComponentDetails"
        ],
        "resources": [
          "*"
        ]
      }
    },
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:2": {
        "policyDescription": "Allows access to restart and stop the Hello World component.",
        "operations": [
          "aws.greengrass#RestartComponent",
          "aws.greengrass#StopComponent"
        ],
        "resources": [
          "com.example.HelloWorld"
        ]
      }
    }
  }
}

CreateLocalDeployment

使用指定的元件配方、成品和執行期引數建立或更新本機部署。

此操作提供與 Greengrass CLI 中的部署建立命令相同的功能。

請求

此操作的請求具有下列參數：

recipeDirectoryPath (Python：recipe_directory_path)

（選用）包含元件配方檔案之資料夾的絕對路徑。

artifactDirectoryPath (Python：artifact_directory_path)

（選用）資料夾的絕對路徑，其中包含要包含在部署中的成品檔案。成品資料夾必須包含下列資料夾結構：


/path/to/artifact/folder/component-name/component-version/artifacts

rootComponentVersionsToAdd (Python：root_component_versions_to_add)

（選用）要在核心裝置上安裝的元件版本。此物件 ComponentToVersionMap是包含下列鍵值對的映射：

key: 元件的名稱。
value: 元件的版本。

rootComponentsToRemove (Python：root_components_to_remove)

（選用）從核心裝置解除安裝的元件。指定清單，其中每個項目都是元件的名稱。

componentToConfiguration (Python：component_to_configuration)

（選用）部署中每個元件的組態更新。此物件 ComponentToConfiguration是包含下列鍵值對的映射：

key

元件的名稱。

value

元件的組態更新 JSON 物件。JSON 物件必須具有下列格式。


{ 
  "MERGE": {
    "config-key": "config-value"
  },
  "RESET": [
    "path/to/reset/"
  ]
}

如需組態更新的詳細資訊，請參閱更新元件組態。

componentToRunWithInfo (Python：component_to_run_with_info)

（選用）部署中每個元件的執行時間組態。此組態包含擁有每個元件程序的系統使用者，以及要套用至每個元件的系統限制。此物件 ComponentToRunWithInfo是包含下列鍵值對的映射：

key

元件的名稱。

value

元件的執行時間組態。如果您省略執行時間組態參數， AWS IoT Greengrass Core 軟體會使用您在 Greengrass 核上設定的預設值。此物件 RunWithInfo包含下列資訊：

posixUser (Python：posix_user)

（選用） POSIX 系統使用者和選用的群組，用於在 Linux 核心裝置上執行此元件。如果指定，使用者和群組必須存在於每個 Linux 核心裝置上。以下列格式指定使用者和群組，並以冒號 (:) 分隔：user:group。群組為選用項目。如果您未指定群組，則 AWS IoT Greengrass Core 軟體會使用使用者的主要群組。如需詳細資訊，請參閱設定執行元件的使用者。

windowsUser (Python：windows_user)

（選用）用來在 Windows 核心裝置上執行此元件的 Windows 使用者。使用者必須存在於每個 Windows 核心裝置上，且其名稱和密碼必須存放在 LocalSystem 帳戶的 Credentials Manager 執行個體中。如需詳細資訊，請參閱設定執行元件的使用者。

systemResourceLimits (Python：system_resource_limits)

（選用）要套用至此元件程序的系統資源限制。您可以將系統資源限制套用至一般和非容器 Lambda 元件。如需詳細資訊，請參閱設定元件的系統資源限制。

AWS IoT Greengrass 目前不支援 Windows 核心裝置上的此功能。

此物件 SystemResourceLimits包含下列資訊：

cpus: （選用）此元件程序可在核心裝置上使用的 CPU 時間上限。核心裝置的 CPU 總時間等於裝置的 CPU 核心數。例如，在具有 4 個 CPU 核心的核心裝置上，您可以將此值設定為 2，以將此元件的程序限制為每個 CPU 核心 50% 的用量。在具有 1 個 CPU 核心的裝置上，您可以將此值設定為 0.25，以將此元件的程序限制為 CPU 的 25% 用量。如果您將此值設定為大於 CPU 核心數量的數字，則 AWS IoT Greengrass Core 軟體不會限制元件的 CPU 使用量。
memory: （選用）此元件的程序可在核心裝置上使用的 RAM 數量上限（以 KB 為單位）。

groupName (Python：group_name)

（選用）此部署的目標物件群組名稱。

回應

此操作的回應具有下列資訊：

deploymentId (Python：deployment_id): 請求建立的本機部署 ID。

ListLocalDeployments

取得最近 10 個本機部署的狀態。

此操作提供與 Greengrass CLI 中的部署清單命令相同的功能。

請求

此操作的請求沒有任何參數。

回應

此操作的回應具有下列資訊：

localDeployments (Python：local_deployments)

本機部署的清單。此清單中的每個物件都是LocalDeployment物件，其中包含下列資訊：

deploymentId (Python：deployment_id)

本機部署的 ID。

status

本機部署的狀態。此列舉 DeploymentStatus具有下列值：

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

GetLocalDeploymentStatus

取得本機部署的狀態。

此操作提供與 Greengrass CLI 中的部署狀態命令相同的功能。

請求

此操作的請求具有下列參數：

deploymentId (Python：deployment_id): 要取得的本機部署 ID。

回應

此操作的回應具有下列資訊：

deployment

本機部署。此物件 LocalDeployment包含下列資訊：

deploymentId (Python：deployment_id)

本機部署的 ID。

status

本機部署的狀態。此列舉 DeploymentStatus具有下列值：

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

ListComponents

取得核心裝置上每個根元件的名稱、版本、狀態和組態。根元件是您在部署中指定的元件。此回應不包含安裝為其他元件相依性的元件。

此操作提供與 Greengrass CLI 中的元件清單命令相同的功能。

請求

此操作的請求沒有任何參數。

回應

此操作的回應具有下列資訊：

components

核心裝置上的根元件清單。此清單中的每個物件都是ComponentDetails物件，其中包含下列資訊：

componentName (Python：component_name)

元件的名稱。

version

元件的版本。

state

元件的狀態。此狀態可以是下列其中一項：

BROKEN
ERRORED
FINISHED
INSTALLED
NEW
RUNNING
STARTING
STOPPING

configuration

元件的組態做為 JSON 物件。

GetComponentDetails

取得核心裝置上元件的版本、狀態和組態。

此操作提供與 Greengrass CLI 中的元件詳細資訊命令相同的功能。

請求

此操作的請求具有下列參數：

componentName (Python：component_name): 要取得的元件名稱。

回應

此操作的回應具有下列資訊：

componentDetails (Python：component_details)

元件的詳細資訊。此物件 ComponentDetails包含下列資訊：

componentName (Python：component_name)

元件的名稱。

version

元件的版本。

state

元件的狀態。此狀態可以是下列其中一項：

BROKEN
ERRORED
FINISHED
INSTALLED
NEW
RUNNING
STARTING
STOPPING

configuration

元件的組態做為 JSON 物件。

RestartComponent

重新啟動核心裝置上的元件。

注意

雖然您可以重新啟動任何元件，但我們建議您僅重新啟動一般元件。

此操作提供與 Greengrass CLI 中的元件重新啟動命令相同的功能。

請求

此操作的請求具有下列參數：

componentName (Python：component_name): 元件的名稱。

回應

此操作的回應具有下列資訊：

restartStatus (Python：restart_status)

重新啟動請求的狀態。請求狀態可以是下列其中一項：

SUCCEEDED
FAILED

message

如果請求失敗，則顯示為什麼元件無法重新啟動的訊息。

StopComponent

在核心裝置上停止元件的程序。

注意

雖然您可以停止任何元件，但我們建議您僅停止一般元件。

此操作提供與 Greengrass CLI 中的元件停止命令相同的功能。

請求

此操作的請求具有下列參數：

componentName (Python：component_name): 元件的名稱。

回應

此操作的回應具有下列資訊：

stopStatus (Python：stop_status)

停止請求的狀態。請求狀態可以是下列其中一項：

SUCCEEDED
FAILED

message

如果請求失敗，則顯示為什麼元件無法停止的訊息。

CreateDebugPassword

產生隨機密碼，您可以用來登入本機偵錯主控台元件。密碼會在產生後 8 小時過期。

此操作在 Greengrass CLI 中提供與 get-debug-password 命令相同的功能。

請求

此操作的請求沒有任何參數。

回應

此操作的回應具有下列資訊：

username: 用來登入的使用者名稱。
password: 用來登入的密碼。
passwordExpiration (Python：password_expiration): 密碼過期的時間。
certificateSHA256Hash (Python：certificate_sha256_hash): 啟用 HTTPS 時，本機偵錯主控台使用的自我簽署憑證的 SHA-256 指紋。當您開啟本機偵錯主控台時，請使用此指紋來驗證憑證是否合法，以及連線是否安全。
certificateSHA1Hash (Python：certificate_sha1_hash): 啟用 HTTPS 時，本機偵錯主控台使用的自我簽署憑證的 SHA-1 指紋。當您開啟本機偵錯主控台時，請使用此指紋來驗證憑證是否合法，以及連線是否安全。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

與本機陰影互動

驗證和授權用戶端裝置

管理本機部署和元件

注意

主題

最低 SDK 版本

授權

範例 授權政策範例

CreateLocalDeployment

請求

回應

ListLocalDeployments

請求

回應

GetLocalDeploymentStatus

請求

回應

ListComponents

請求

回應

GetComponentDetails

請求

回應

RestartComponent

注意

請求

回應

StopComponent

注意

請求

回應

CreateDebugPassword

請求

回應

範例授權政策範例