本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

**注意**  
此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.6.0 和更新版本。

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

若要使用這些 IPC 操作，請在自訂[元件中包含 2.6.0 版或更新版本的 Greengrass CLI ](greengrass-cli-component.md)元件做為相依性。然後，您可以在自訂元件中使用 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 for Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK for Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  1.5.3 版  | 
|  [AWS IoT Device SDK 適用於 C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  1.17.0 版  | 
|  [AWS IoT Device SDK for 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`


| 作業 | Description | Resources | 
| --- | --- | --- | 
|  `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 中的[部署建立命令](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`  
元件的執行時間組態。如果您省略執行時間組態參數，則 AWS IoT Greengrass Core 軟體會使用您在 [Greengrass 核](greengrass-nucleus-component.md)上設定的預設值。此物件 `RunWithInfo`包含下列資訊：    
`posixUser` (Python：`posix_user`)  
（選用） <a name="deployment-posix-user-definition"></a>POSIX 系統使用者和選用的群組，用於在 Linux 核心裝置上執行此元件。如果指定，使用者和群組必須存在於每個 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 帳戶的 Credentials Manager 執行個體中。如需詳細資訊，請參閱 [設定執行元件的使用者](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 數量上限 （以 KB 為單位）。

`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 中的[部署清單命令](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 中的[部署狀態命令](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 中的[元件清單命令](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 中的[元件詳細資訊命令](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 中的[元件重新啟動命令](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 中的[元件停止命令](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 指紋。當您開啟本機偵錯主控台時，請使用此指紋來驗證憑證是否合法且連線是否安全。