最低 SDK 版本 Authorization 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 Amazon IoT Device SDK CLI IPC 服务进行交互时必须使用的最低版本。

SDK	最低版本
Amazon IoT Device SDK适用于 Java v2	v1.2.10
Amazon IoT Device SDK适用于 Python v2	v1.5.3
Amazon IoT Device SDK适用于 C++ v2	v1.17.0
Amazon IoT Device SDK适用于 JavaScript v2	v1.12.0

Authorization

要在自定义组件中使用 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

组件的运行时配置。如果您省略运行时配置参数，则 Amazon IoT Greengrass Core 软件将使用您在 Greengras s 核上配置的默认值。此对象包含以下信息：RunWithInfo

posixUser（Python:posix_user）

（可选）用于在 Linux 核心设备上运行此组件的 POSIX 系统用户和（可选）组。用户和群组（如果已指定）必须存在于每台 Linux 核心设备上。使用以下格式指定由半角冒号（:）分隔的用户和组：user:group。组是可选的。如果您未指定群组，Amazon IoT GreengrassCore 软件将使用该用户的主群组。有关更多信息，请参阅。配置运行组件的用户

windowsUser（Python:windows_user）

（可选）用于在 Windows 核心设备上运行此组件的 Windows 用户。用户必须存在于每台 Windows 核心设备上，其名称和密码必须存储在LocalSystem账户的凭证管理器实例中。有关更多信息，请参阅。配置运行组件的用户

systemResourceLimits（Python:system_resource_limits）

（可选）适用于此组件进程的系统资源限制。您可以将系统资源限制应用于通用和非容器化 Lambda 组件。有关更多信息，请参阅。为组件配置系统资源限制

Amazon IoT Greengrass目前在 Windows 核心设备上不支持此功能。

此对象包含以下信息：SystemResourceLimits

cpus: （可选）此组件的进程可以在核心设备上使用的最大 CPU 时间。核心设备的总 CPU 时间等于 CPU 核心的设备数量。例如，在具有 4 个 CPU 内核的核心设备上，您可以将此值设置为，2将此组件的进程使用率限制为每个 CPU 内核的 50%。在具有 1 个 CPU 内核的设备上，可以将此值设置为，0.25将此组件的进程限制为 CPU 的使用率的 25%。如果您将此值设置为大于 CPU 内核数的数字，则 Amazon IoT Greengrass Core 软件不会限制组件的 CPU 使用率。
memory: （可选）此组件的进程可以在核心设备上使用的最大 RAM 量（以千字节为单位）。

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

组件的状态。此状态可以是以下状态之一：

RUNNING
ERRORED

configuration

组件的配置为 JSON 对象。

GetComponentDetails

获取核心设备上组件的版本、状态和配置。

此操作提供的功能与 Greengrass CLI 中的组件详细信息命令相同。

请求

此操作的请求具有以下参数：

componentName（Python:component_name）: 要获取的组件的名称。

响应

此操作的响应包含以下信息：

componentDetails（Python:component_details）

组件的详细信息。此对象包含以下信息：ComponentDetails

componentName（Python:component_name）

组件名称。

version

组件版本。

state

组件的状态。此状态可以是以下状态之一：

RUNNING
ERRORED

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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

与局部阴影互动

管理本地部署和组件

注意

主题

最低 SDK 版本

Authorization

例 授权策略示例

CreateLocalDeployment

请求

响应

ListLocalDeployments

请求

响应

GetLocalDeploymentStatus

请求

响应

ListComponents

请求

响应

GetComponentDetails

请求

响应

RestartComponent

注意

请求

响应

StopComponent

注意

请求

响应

CreateDebugPassword

请求

响应

例授权策略示例