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

管理本地部署和组件

注意

此功能适用于 Greengrass Nucleus 组件的 v2.6.0 及更高版本。

使用 Greengrass CLI IPC 服务来管理核心设备上的本地部署和 Greengrass 组件。

要使用这些 IPC 操作，请将 Greengrass CLI 组件的 2.6.0 或更高版本作为依赖关系包含在自定义组件中。然后，您可以在自定义组件中使用 IPC 操作来执行以下操作：

创建本地部署，以修改和配置核心设备上的 Greengrass 组件。
重启并停止核心设备上的 Greengrass 组件。
生成可用于登录本地调试控制台的密码。

最低 SDK 版本

下表列出了与 Greengrass CLI IPC 服务交互时必须使用的 AWS IoT Device SDK 最低版本。

SDK	最低版本
适用于 Java v2 的 AWS IoT Device SDK	v1.2.10
适用于 Python v2 的 AWS IoT Device SDK	v1.5.3
适用于 C++ v2 的 AWS IoT Device SDK	v1.17.0
适用于 JavaScript v2 的 AWS IoT Device SDK	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 中的 deployment create 命令相同。

请求

此操作的请求包含以下参数：

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 Nucleus 上配置的默认值。此对象 RunWithInfo 包含以下信息：

posixUser（Python：posix_user）

（可选）用于在 Linux 核心设备上运行此组件的 POSIX 系统用户和（可选的）组。用户和组（如果已指定）必须存在于每台 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 数量（以千字节表示）。

groupName（Python：group_name）

（可选）此部署要针对的事物组的名称。

响应

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

deploymentId（Python：deployment_id）: 该请求创建的本地部署的 ID。

ListLocalDeployments

获取最近 10 次本地部署的状态。

此操作提供的功能与 Greengrass CLI 中的 deployment list 命令相同。

请求

此操作的请求没有任何参数。

响应

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

localDeployments（Python：local_deployments）

本地部署列表。此列表中的每个对象都是 LocalDeployment 对象，其中包含以下信息：

deploymentId（Python：deployment_id）

本地部署的 ID。

status

本地部署的状态。此枚举 DeploymentStatus 包含以下值：

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

GetLocalDeploymentStatus

获取本地部署的状态。

此操作提供的功能与 Greengrass CLI 中的 deployment status 命令相同。

请求

此操作的请求包含以下参数：

deploymentId（Python：deployment_id）: 要获取的本地部署的 ID。

响应

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

deployment

本地部署。此对象 LocalDeployment 包含以下信息：

deploymentId（Python：deployment_id）

本地部署的 ID。

status

本地部署的状态。此枚举 DeploymentStatus 包含以下值：

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

ListComponents

获取核心设备上每个根组件的名称、版本、状态和配置。根组件是您在部署中指定的组件。此响应不包括作为其它组件的依赖关系安装的组件。

此操作提供的功能与 Greengrass CLI 中的 component list 命令相同。

请求

此操作的请求没有任何参数。

响应

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

components

核心设备上的根组件列表。此列表中的每个对象都是 ComponentDetails 对象，其中包含以下信息：

componentName（Python：component_name）

组件名称。

version

组件版本。

state

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

BROKEN
ERRORED
FINISHED
INSTALLED
NEW
RUNNING
STARTING
STOPPING

configuration

以 JSON 对象形式表示的组件配置。

GetComponentDetails

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

此操作提供的功能与 Greengrass CLI 中的 component details 命令相同。

请求

此操作的请求包含以下参数：

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 中的 component restart 命令相同。

请求

此操作的请求包含以下参数：

componentName（Python：component_name）: 组件名称。

响应

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

restartStatus（Python：restart_status）

重启请求的状态。请求状态可能是以下状态之一：

SUCCEEDED
FAILED

message

如果请求失败，则会显示一条消息，说明组件未能重启的原因。

StopComponent

停止核心设备上的组件进程。

注意

虽然您可以停止任何组件，但建议您仅停止通用组件。

此操作提供的功能与 Greengrass CLI 中的 component stop 命令相同。

请求

此操作的请求包含以下参数：

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 版本

授权

例 示例授权策略

CreateLocalDeployment

请求

响应

ListLocalDeployments

请求

响应

GetLocalDeploymentStatus

请求

响应

ListComponents

请求

响应

GetComponentDetails

请求

响应

RestartComponent

注意

请求

响应

StopComponent

注意

请求

响应

CreateDebugPassword

请求

响应

例示例授权策略