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

管理本機部署和元件

注意

此功能適用於 v2.6.0 及更高版 Greeng rass 核組件。

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

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

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

最低 SDK 版本

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

SDK	最低版本
AWS IoT Device SDK對於爪哇 V2	v1.2.10
AWS IoT Device SDK對於 Python V2	V1.5.3
AWS IoT Device SDK對於 C ++ 第 2	v1.17.0
AWS IoT Device SDK對於 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)

(選擇性) 包含元件 recipe 檔案之資料夾的絕對路徑。

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核心軟體會使用您在 Greengr ass 核心上設定的預設值。此物件RunWithInfo包含下列資訊：

posixUser(Python:posix_user)

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

windowsUser(Python:windows_user)

(選擇性) 用來在 Windows 核心裝置上執行此元件的 Windows 使用者。使用者必須存在於每個 Windows 核心裝置上，且其名稱和密碼必須儲存在 LocalSystem 帳戶的認證管理員執行個體中。如需詳細資訊，請參閱設定執行元件的使用者。

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核心軟體就不會限制元件的 CPU 使用率。
memory: (選擇性) 此元件的處理序可在核心裝置上使用的最大 RAM 容量 (以 KB 為單位)。

groupName(Python:group_name)

(選擇性) 要使用此部署作為目標的物群組名稱。

回應

此作業的回應包含下列資訊：

deploymentId(Python:deployment_id): 要求所建立之本機部署的識別碼。

ListLocalDeployments

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

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

請求

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

回應

此作業的回應包含下列資訊：

localDeployments(Python:local_deployments)

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

deploymentId(Python:deployment_id)

本機部署的識別碼。

status

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

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

GetLocalDeploymentStatus

取得本機部署的狀態。

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

請求

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

deploymentId(Python:deployment_id): 要取得之本機部署的識別碼。

回應

此作業的回應包含下列資訊：

deployment

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

deploymentId(Python:deployment_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

請求

回應

範例授權政策範例