本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 管理本地部署和组件
<a name="ipc-local-deployments-components"></a>

**注意**  
此功能适用于 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的 v2.6.0 及更高版本。

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

要使用这些 IPC 操作，请将 [Greengrass CLI 组件](greengrass-cli-component.md)的 2.6.0 或更高版本作为依赖关系包含在自定义组件中。然后，您可以在自定义组件中使用 IPC 操作来执行以下操作：
+ 创建本地部署，以修改和配置核心设备上的 Greengrass 组件。
+ 重启并停止核心设备上的 Greengrass 组件。
+ 生成可用于登录[本地调试控制台](local-debug-console-component.md)的密码。

**Topics**
+ [最低 SDK 版本](#ipc-local-deployments-components-sdk-versions)
+ [Authorization](#ipc-local-deployments-components-authorization)
+ [CreateLocalDeployment](#ipc-operation-createlocaldeployment)
+ [ListLocalDeployments](#ipc-operation-listlocaldeployments)
+ [GetLocalDeploymentStatus](#ipc-operation-getlocaldeploymentstatus)
+ [ListComponents](#ipc-operation-listcomponents)
+ [GetComponentDetails](#ipc-operation-getcomponentdetails)
+ [RestartComponent](#ipc-operation-restartcomponent)
+ [StopComponent](#ipc-operation-stopcomponent)
+ [CreateDebugPassword](#ipc-operation-createdebugpassword)

## 最低 SDK 版本
<a name="ipc-local-deployments-components-sdk-versions"></a>

下表列出了可用于与 Greengrass CLI IPC 服务交互的最低版本。 SDKs 


| SDK | 最低版本 | 
| --- | --- | 
|  [AWS IoT Greengrass 组件 SDK（C、C\$1\$1、Rust）](https://github.com/aws-greengrass/aws-greengrass-component-sdk)  |  v1.0.0  | 
|  [AWS IoT Device SDK 适用于 Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK 适用于 Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK 适用于 C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK 适用于 JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Authorization
<a name="ipc-local-deployments-components-authorization"></a>

要在自定义组件中使用 Greengrass CLI IPC 服务，您必须定义允许组件管理本地部署和组件的授权策略。有关定义授权策略的信息，请参阅[授权组件执行 IPC 操作](interprocess-communication.md#ipc-authorization-policies)。

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`  |  允许组件生成用于登录[本地调试控制台组件](local-debug-console-component.md)的密码。  |  `*`  | 

**Example 示例授权策略**  
以下示例授权策略允许组件创建本地部署、查看所有本地部署和组件，以及重启并停止名为 `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
<a name="ipc-operation-createlocaldeployment"></a>

使用指定的组件配方、构件和运行时参数创建或更新本地部署。

此操作提供的功能与 Greengrass CLI 中的 [deployment create 命令](gg-cli-deployment.md#deployment-create)相同。

### 请求
<a name="ipc-operation-createlocaldeployment-request"></a>

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

`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/"
  ]
}
```
有关配置更新的更多信息，请参阅[更新组件配置](update-component-configurations.md)。

`componentToRunWithInfo`（Python：`component_to_run_with_info`）  
（可选）部署中每个组件的运行时配置。此配置包括拥有每个组件进程的系统用户以及要应用于每个组件的系统限制。此对象 (`ComponentToRunWithInfo`) 是一个包含以下键值对的映射：    
`key`  
组件名称。  
`value`  
组件的运行时配置。如果省略运行时配置参数，则 Core 软件将使用您在 Gre [engr](greengrass-nucleus-component.md) ass AWS IoT Greengrass 核心上配置的默认值。此对象 `RunWithInfo` 包含以下信息：    
`posixUser`（Python：`posix_user`）  
（可选）<a name="deployment-posix-user-definition"></a>用于在 Linux 核心设备上运行此组件的 POSIX 系统用户和（可选的）组。用户和组（如果已指定）必须存在于每台 Linux 核心设备上。使用以下格式指定由半角冒号（`:`）分隔的用户和组：`user:group`。组是可选的。如果您未指定群组，则 AWS IoT Greengrass Core 软件将使用该用户的主群组。有关更多信息，请参阅[配置运行组件的用户](configure-greengrass-core-v2.md#configure-component-user)。  
`windowsUser`（Python：`windows_user`）  
（可选）<a name="deployment-windows-user-definition"></a>用于在 Windows 核心设备上运行此组件的 Windows 用户。用户必须存在于每台 Windows 核心设备上，其用户名和密码必须存储在 LocalSystem 账户的凭据管理器实例中。有关更多信息，请参阅[配置运行组件的用户](configure-greengrass-core-v2.md#configure-component-user)。  
`systemResourceLimits`（Python：`system_resource_limits`）  
（可选）<a name="deployment-system-resource-limits-definition"></a>要应用于此组件进程的系统资源限制。您可以将系统资源限制应用于通用和非容器化 Lambda 组件。有关更多信息，请参阅[配置组件的系统资源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。  
AWS IoT Greengrass 目前不支持在 Windows 核心设备上使用此功能。  
此对象 `SystemResourceLimits` 包含以下信息：    
`cpus`  
（可选）<a name="system-resource-limits-cpu-definition-this"></a>此组件进程可在核心设备上使用的最大 CPU 时间。核心设备的总 CPU 时间等于 CPU 核心的设备数量。例如，在一台有 4 个 CPU 核心的核心设备上，您可以将此值设置为 `2`，以便将此组件进程限制为使用每个 CPU 核心的 50%。在一台有 1 个 CPU 核心的设备上，您可以将此值设置为 `0.25`，以便将此组件进程限制为使用 CPU 的 25%。如果将此值设置为大于 CPU 内核数的数字，则 AWS IoT Greengrass Core 软件不会限制组件的 CPU 使用率。  
`memory`  
（可选）<a name="system-resource-limits-memory-definition-this"></a>此组件进程可在核心设备上使用的最大 RAM 数量（以千字节表示）。

`groupName`（Python：`group_name`）  
（可选）此部署要针对的事物组的名称。

### 响应
<a name="ipc-operation-createlocaldeployment-response"></a>

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

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

## ListLocalDeployments
<a name="ipc-operation-listlocaldeployments"></a>

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

此操作提供的功能与 Greengrass CLI 中的 [deployment list 命令](gg-cli-deployment.md#deployment-list)相同。

### 请求
<a name="ipc-operation-listlocaldeployments-request"></a>

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

### 响应
<a name="ipc-operation-listlocaldeployments-response"></a>

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

`localDeployments`（Python：`local_deployments`）  
本地部署列表。此列表中的每个对象都是 `LocalDeployment` 对象，其中包含以下信息：  <a name="ipc-local-deployment-object-shape"></a>  
`deploymentId`（Python：`deployment_id`）  
本地部署的 ID。  
`status`  
本地部署的状态。此枚举 `DeploymentStatus` 包含以下值：  
+ `QUEUED`
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`

## GetLocalDeploymentStatus
<a name="ipc-operation-getlocaldeploymentstatus"></a>

获取本地部署的状态。

此操作提供的功能与 Greengrass CLI 中的 [deployment status 命令](gg-cli-deployment.md#deployment-status)相同。

### 请求
<a name="ipc-operation-getlocaldeploymentstatus-request"></a>

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

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

### 响应
<a name="ipc-operation-getlocaldeploymentstatus-response"></a>

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

`deployment`  
本地部署。此对象 `LocalDeployment` 包含以下信息：  <a name="ipc-local-deployment-object-shape"></a>  
`deploymentId`（Python：`deployment_id`）  
本地部署的 ID。  
`status`  
本地部署的状态。此枚举 `DeploymentStatus` 包含以下值：  
+ `QUEUED`
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`

## ListComponents
<a name="ipc-operation-listcomponents"></a>

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

此操作提供的功能与 Greengrass CLI 中的 [component list 命令](gg-cli-component.md#component-list)相同。

### 请求
<a name="ipc-operation-listcomponents-request"></a>

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

### 响应
<a name="ipc-operation-listcomponents-response"></a>

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

`components`  
核心设备上的根组件列表。此列表中的每个对象都是 `ComponentDetails` 对象，其中包含以下信息：  <a name="ipc-component-details-object-shape"></a>  
`componentName`（Python：`component_name`）  
组件名称。  
`version`  
组件版本。  
`state`  
组件的状态。此状态可能是以下状态之一：  
+ `BROKEN`
+ `ERRORED`
+ `FINISHED`
+ `INSTALLED`
+ `NEW`
+ `RUNNING`
+ `STARTING`
+ `STOPPING`  
`configuration`  
以 JSON 对象形式表示的组件配置。

## GetComponentDetails
<a name="ipc-operation-getcomponentdetails"></a>

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

此操作提供的功能与 Greengrass CLI 中的 [component details 命令](gg-cli-component.md#component-details)相同。

### 请求
<a name="ipc-operation-getcomponentdetails-request"></a>

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

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

### 响应
<a name="ipc-operation-getcomponentdetails-response"></a>

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

`componentDetails`（Python：`component_details`）  
组件的详细信息。此对象 `ComponentDetails` 包含以下信息：  <a name="ipc-component-details-object-shape"></a>  
`componentName`（Python：`component_name`）  
组件名称。  
`version`  
组件版本。  
`state`  
组件的状态。此状态可能是以下状态之一：  
+ `BROKEN`
+ `ERRORED`
+ `FINISHED`
+ `INSTALLED`
+ `NEW`
+ `RUNNING`
+ `STARTING`
+ `STOPPING`  
`configuration`  
以 JSON 对象形式表示的组件配置。

## RestartComponent
<a name="ipc-operation-restartcomponent"></a>

重启核心设备上的组件。

**注意**  
虽然您可以重启任何组件，但建议您仅重启[通用组件](develop-greengrass-components.md#component-types)。

此操作提供的功能与 Greengrass CLI 中的 [component restart 命令](gg-cli-component.md#component-restart)相同。

### 请求
<a name="ipc-operation-restartcomponent-request"></a>

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

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

### 响应
<a name="ipc-operation-restartcomponent-response"></a>

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

`restartStatus`（Python：`restart_status`）  
重启请求的状态。请求状态可能是以下状态之一：  
+ `SUCCEEDED`
+ `FAILED`

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

### 示例
<a name="ipc-operation-restartcomponent-examples"></a>

以下示例演示了如何在自定义组件代码中调用该操作。

------
#### [ Rust ]

**Example 示例：重启组件**  

```
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let component_name = "com.example.HelloWorld";

    sdk.restart_component(component_name)
        .expect("Failed to restart component");

    println!("Successfully requested restart for component: {component_name}");
}
```

------
#### [ C ]

**Example 示例：重启组件**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer component_name = GG_STR("com.example.HelloWorld");

    err = ggipc_restart_component(component_name);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to restart component: %.*s\n",
            (int) component_name.len,
            component_name.data
        );
        exit(-1);
    }

    printf(
        "Successfully requested restart for component: %.*s\n",
        (int) component_name.len,
        component_name.data
    );
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example 示例：重启组件**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view component_name = "com.example.HelloWorld";

    error = client.restart_component(component_name);
    if (error) {
        std::cerr << "Failed to restart component: " << component_name << "\n";
        exit(-1);
    }

    std::cout << "Successfully requested restart for component: "
              << component_name << "\n";
}
```

------

## StopComponent
<a name="ipc-operation-stopcomponent"></a>

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

**注意**  
虽然您可以停止任何组件，但建议您仅停止[通用组件](develop-greengrass-components.md#component-types)。

此操作提供的功能与 Greengrass CLI 中的 [component stop 命令](gg-cli-component.md#component-stop)相同。

### 请求
<a name="ipc-operation-stopcomponent-request"></a>

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

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

### 响应
<a name="ipc-operation-stopcomponent-response"></a>

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

`stopStatus`（Python：`stop_status`）  
停止请求的状态。请求状态可能是以下状态之一：  
+ `SUCCEEDED`
+ `FAILED`

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

## CreateDebugPassword
<a name="ipc-operation-createdebugpassword"></a>

生成可用于登录[本地调试控制台组件](local-debug-console-component.md)的随机密码。密码将在生成 8 小时后过期。

此操作提供的功能与 Greengrass CLI 中的[get-debug-password 命令](gg-cli-get-debug-password.md)相同。

### 请求
<a name="ipc-operation-createdebugpassword-request"></a>

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

### 响应
<a name="ipc-operation-createdebugpassword-response"></a>

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

`username`  
用于登录的用户名。

`password`  
用于登录的密码。

`passwordExpiration`（Python：`password_expiration`）  
密码过期的时间。

`certificateSHA256Hash`（Python：`certificate_sha256_hash`）  
启用 HTTPS 时本地调试控制台使用的自签名证书的 SHA-256 指纹。打开本地调试控制台时，使用此指纹验证证书是否合法以及连接是否安全。

`certificateSHA1Hash`（Python：`certificate_sha1_hash`）  
启用 HTTPS 时本地调试控制台使用的自签名证书的 SHA-1 指纹。打开本地调试控制台时，使用此指纹验证证书是否合法以及连接是否安全。