本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Greengrass CLI 命令
Greengrass CLI 提供命令列界面，可在本機與 AWS IoT Greengrass 核心裝置互動。Greengrass CLI 命令使用以下格式。
```
$ greengrass-cli [arguments]
```
根據預設， `/greengrass/v2/bin/` 資料夾中的`greengrass-cli`可執行檔會與 `/greengrass/v2` 資料夾中執行 AWS IoT Greengrass 的核心軟體版本互動。如果您呼叫未放置在此位置的可執行檔，或您想要在不同位置與 AWS IoT Greengrass Core 軟體互動，則必須使用下列其中一種方法來明確指定您要互動之 AWS IoT Greengrass Core 軟體的根路徑：
+ 將 `GGC_ROOT_PATH` 環境變數設為 `/greengrass/v2`。
+ 將`--ggcRootPath /greengrass/v2`引數新增至您的命令，如下列範例所示。
```
greengrass-cli --ggcRootPath /greengrass/v2 [arguments]
```
您可以搭配任何命令使用下列引數：
+ 使用 `--help` 以取得特定 Greengrass CLI 命令的相關資訊。
+ 使用 `--version` 以取得 Greengrass CLI 版本的相關資訊。
本節說明 Greengrass CLI 命令，並提供這些命令的範例。每個命令的摘要會顯示其引數及其用量。選用引數以方括號顯示。
**Topics**
+ [元件](gg-cli-component.md)
+ [部署](gg-cli-deployment.md)
+ [日誌](gg-cli-logs.md)
+ [get-debug-password](gg-cli-get-debug-password.md)
# 元件
使用 `component`命令與核心裝置上的本機元件互動。
**子命令**
+ [詳細資訊](#component-details)
+ [列出](#component-list)
+ [重新啟動](#component-restart)
+ [stop](#component-stop)
## 詳細資訊
擷取一個元件的版本、狀態和組態。
**概要**
```
greengrass-cli component details --name
```
**Arguments (引數)**
`--name`、`-n`。 元件名稱。
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli component details --name MyComponent
Component Name: MyComponent
Version: 1.0.0
State: RUNNING
Configuration: null
```
## 列出
擷取裝置上安裝的每個元件的名稱、版本、狀態和組態。
**概要**
```
greengrass-cli component list
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli component list
Components currently running in Greengrass:
Component Name: FleetStatusService
Version: 0.0.0
State: RUNNING
Configuration: {"periodicUpdateIntervalSec":86400.0}
Component Name: UpdateSystemPolicyService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Nucleus
Version: 2.0.0
State: FINISHED
Configuration: {"awsRegion":"region","runWithDefault":{"posixUser":"ggc_user:ggc_group"},"telemetry":{}}
Component Name: DeploymentService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: TelemetryAgent
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Cli
Version: 2.0.0
State: RUNNING
Configuration: {"AuthorizedPosixGroups":"ggc_user"}
```
## 重新啟動
重新啟動元件。
**概要**
```
greengrass-cli component restart --names ,...
```
**Arguments (引數)**
`--names`、`-n`。 元件名稱。至少需要一個元件名稱。您可以指定其他元件名稱，以逗號分隔每個名稱。
**輸出**
無
## stop
停止執行元件。
**概要**
```
greengrass-cli component stop --names ,...
```
**Arguments (引數)**
`--names`、`-n`。 元件名稱。至少需要一個元件名稱。您可以視需要指定其他元件名稱，以逗號分隔每個名稱。
**輸出**
無
# 部署
使用 `deployment`命令與核心裝置上的本機元件互動。
若要監控本機部署的進度，請使用 `status`子命令。您無法使用 主控台監控本機部署的進度。
**子命令**
+ [建立](#deployment-create)
+ [取消](#deployment-cancel)
+ [列出](#deployment-list)
+ [status](#deployment-status)
## 建立
使用指定的元件配方、成品和執行期引數建立或更新本機部署。
**概要**
```
greengrass-cli deployment create
--recipeDir path/to/component/recipe
[--artifactDir path/to/artifact/folder ]
[--update-config {component-configuration}]
[--groupId ]
[--merge "="]...
[--runWith ":posixUser=[:]"]...
[--systemLimits "{component-system-resource-limits}]"]...
[--remove ,...]
[--failure-handling-policy ]
```
**Arguments (引數)**
+ `--recipeDir`、`-r`。 包含元件配方檔案之資料夾的完整路徑。
+ `--artifactDir`、`-a`。 資料夾的完整路徑，其中包含您要包含在部署中的成品檔案。成品資料夾必須包含下列目錄結構：
```
/path/to/artifact/folder///
```
+ `--update-config`、`-c`。 部署的組態引數，以 JSON 字串或 JSON 檔案的形式提供。JSON 字串的格式應該如下：
```
{ \
"componentName": { \
"MERGE": {"config-key": "config-value"}, \
"RESET": ["path/to/reset/"] \
} \
}
```
`MERGE` 和 區分`RESET`大小寫，且必須是大寫。
+ `--groupId`、`-g`。 部署的目標物件群組。
+ `--merge`、`-m`。 您要新增或更新的目標元件名稱和版本。您必須以 格式提供元件資訊`=`。為每個要指定的額外元件使用單獨的引數。如有需要，請使用 `--runWith`引數提供執行元件的 `posixGroup`、 `posixUser`和 `windowsUser`資訊。
+ `--runWith`。 執行一般或 Lambda 元件的 `posixUser``posixGroup`、 和 `windowsUser`資訊。您必須以 格式提供此資訊`:{posixUser|windowsUser}=[:<=posixGroup>]`。例如，您可以指定 **HelloWorld:posixUser=ggc\$1user:ggc\$1group**或 **HelloWorld:windowsUser=ggc\$1user**。為每個要指定的其他選項使用單獨的引數。
如需詳細資訊，請參閱[設定執行元件的使用者](configure-greengrass-core-v2.md#configure-component-user)。
+ `--systemLimits`。 系統資源限制，適用於核心裝置上的一般和非容器 Lambda 元件程序。您可以設定每個元件程序可以使用的 CPU 和 RAM 用量上限。指定序列化 JSON 物件或 JSON 檔案的檔案路徑。JSON 物件必須具有下列格式。
```
{ \
"componentName": { \
"cpus": cpuTimeLimit, \
"memory": memoryLimitInKb \
} \
}
```
您可以為每個元件設定下列系統資源限制：
+ `cpus` – 此元件的程序可在核心裝置上使用的 CPU 時間上限。核心裝置的 CPU 總時間等於裝置的 CPU 核心數。例如，在具有 4 個 CPU 核心的核心裝置上，您可以將此值設定為 `2`，以將此元件的程序限制為每個 CPU 核心的 50% 用量。在具有 1 個 CPU 核心的裝置上，您可以將此值設定為 `0.25`，以將此元件的程序限制為 CPU 的 25% 用量。如果您將此值設定為大於 CPU 核心數量的數字，則 AWS IoT Greengrass Core 軟體不會限制元件的 CPU 用量。
+ `memory` – 此元件的程序可在核心裝置上使用的 RAM 數量上限 （以 KB 為單位）。
如需詳細資訊，請參閱[設定元件的系統資源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。
此功能適用於 Linux 核心裝置上的 [Greengrass 核元件](greengrass-nucleus-component.md)和 Greengrass CLI 的 v2.4.0 和更新版本。目前 AWS IoT Greengrass 不支援 Windows 核心裝置上的此功能。
+ `--remove`。 您要從本機部署中移除的目標元件名稱。若要移除從雲端部署合併的元件，您必須以下列格式提供目標物件群組的群組 ID：
------
#### [ Greengrass nucleus v2.4.0 and later ]
```
--remove --groupId
```
------
#### [ Earlier than v2.4.0 ]
```
--remove --groupId thinggroup/
```
------
+ `--failure-handling-policy`。 定義部署失敗時所採取的動作。您可以指定兩個動作：
+ `ROLLBACK` –
+ `DO_NOTHING` –
此功能適用於 的 v2.11.0 和更新版本。 [Greengrass 核](greengrass-nucleus-component.md)
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli deployment create \
--merge MyApp1=1.0.0 \
--merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \
--remove MyApp3 \
--recipeDir recipes/ \
--artifactDir artifacts/
Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-ad89-5151213dfcbc
```
## 取消
取消指定的部署。
概要
```
greengrass-cli deployment cancel
-i
```
引數
`-i`。 要取消之部署的唯一識別符。部署 ID 會在 `create`命令的輸出中傳回。
輸出
+ 無
## 列出
擷取最近 10 個本機部署的狀態。
**概要**
```
greengrass-cli deployment list
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。根據您的部署狀態，輸出會顯示下列其中一個狀態值：`SUCCEEDED`、 `IN_PROGRESS`或 `FAILED`。
```
$ sudo greengrass-cli deployment list
44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED
Created on: 6/27/23 11:05 AM
```
## status
擷取特定部署的狀態。
**概要**
```
greengrass-cli deployment status -i
```
**Arguments (引數)**
`-i`。 部署的 ID。
**輸出**
下列範例顯示執行此命令時產生的輸出。根據您的部署狀態，輸出會顯示下列其中一個狀態值：`SUCCEEDED`、 `IN_PROGRESS`或 `FAILED`。
```
$ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc
44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED
Created on: 6/27/23 11:05 AM
Detailed Status:
Deployment Error Stack: List of error codes
Deployment Error Types: List of error types
Failure Cause: Cause
```
# 日誌
使用 `logs`命令來分析核心裝置上的 Greengrass 日誌。
**子命令**
+ [get](#logs-get)
+ [list-keywords](#logs-list-keywords)
+ [list-log-files](#logs-list-log-files)
## get
收集、篩選和視覺化 Greengrass 日誌檔案。此命令僅支援 JSON 格式的日誌檔案。您可以在 核組態中指定[記錄格式](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format)。
**概要**
```
greengrass-cli logs get
[--log-dir path/to/a/log/folder]
[--log-file path/to/a/log/file]
[--follow true | false ]
[--filter ]
[--time-window , ]
[--verbose ]
[--no-color ]
[--before ]
[--after ]
[--syslog ]
[--max-long-queue-size ]
```
**Arguments (引數)**
+ `--log-dir`、`-ld`。 要檢查日誌檔案的目錄路徑，例如 **`/greengrass/v2`/logs**。請勿與 搭配使用`--syslog`。為每個要指定的額外目錄使用單獨的引數。您必須使用 `--log-dir`或 中的至少一個`--log-file`。您也可以在單一命令中使用兩個引數。
+ `--log-file`、`-lf`。 您要使用的日誌目錄路徑。為每個要指定的額外目錄使用單獨的引數。您必須使用 `--log-dir`或 中的至少一個`--log-file`。您也可以在單一命令中使用兩個引數。
+ `--follow`、`-fol`。 在日誌更新發生時顯示日誌更新。Greengrass CLI 會繼續執行並從指定的日誌讀取。如果您指定時段，則 Greengrass CLI 會在所有時段結束後停止監控日誌。
+ `--filter`、`-f`。 要用作篩選條件的關鍵字、規則運算式或鍵值對。將此值提供為字串、規則表達式或索引鍵/值對。為每個要指定的額外篩選條件使用單獨的引數。
評估時，單一引數中指定的多個篩選條件會由 OR 運算子分隔，而其他引數中指定的篩選條件則會與 AND 運算子合併。例如，如果您的命令包含 `--filter "installed" --filter "name=alpha,name=beta"`，則 Greengrass CLI 將篩選和顯示包含關鍵字`installed`和具有 `alpha`或 值的`name`金鑰的日誌訊息`beta`。
+ `--time-window`、`-t`。 要顯示日誌資訊的時間範圍。您可以同時使用確切的時間戳記和相對位移。您必須以 格式提供此資訊`,`。如果您未指定開始時間或結束時間，則該選項的值會預設為目前的系統日期和時間。為每個要指定的額外時段使用單獨的引數。
Greengrass CLI 支援下列時間戳記格式：
+ `yyyy-MM-DD`，例如 `2020-06-30`。當您使用此格式時，時間預設為 00：00：00。
`yyyyMMDD`，例如 `20200630`。當您使用此格式時，時間預設為 00：00：00。
`HH:mm:ss`，例如 `15:30:45`。當您使用此格式時，日期預設為目前的系統日期。
`HH:mm:ssSSS`，例如 `15:30:45`。當您使用此格式時，日期預設為目前的系統日期。
`YYYY-MM-DD'T'HH:mm:ss'Z'`，例如 `2020-06-30T15:30:45Z`。
`YYYY-MM-DD'T'HH:mm:ss`，例如 `2020-06-30T15:30:45`。
`yyyy-MM-dd'T'HH:mm:ss.SSS`，例如 `2020-06-30T15:30:45.250`。
相對偏移會指定與目前系統時間的時段偏移。Greengrass CLI 支援下列格式的相對偏移：`+|-[h|hr|hours][valuem|min|minutes][value]s|sec|seconds`。
例如，下列引數指定目前時間 1 小時到 2 小時 15 分鐘之間的時間範圍`--time-window -2h15min,-1hr`。
+ `--verbose`。 顯示日誌訊息中的所有欄位。請勿與 搭配使用`--syslog`。
+ `--no-color`、`-nc`。 移除顏色編碼。日誌訊息的預設顏色編碼使用粗體紅色文字。僅支援類似 UNIX 的終端機，因為它使用 ANSI 逸出序列。
+ `--before`、`-b`。 在相符的日誌項目前面顯示的行數。預設值為 0。
+ `--after`、`-a`。 在相符的日誌項目之後顯示的行數。預設值為 0。
+ `--syslog`。 使用 RFC3164 定義的 syslog 通訊協定來處理所有日誌檔案。請勿搭配 `--log-dir`和 使用 `--verbose`。syslog 通訊協定使用以下格式：`"<$Priority>$Timestamp $Host $Logger ($Class): $Message"`。如果您未指定日誌檔案，則 Greengrass CLI 會從下列位置讀取日誌訊息：`/var/log/messages`、 `/var/log/syslog`或 `/var/log/system.log`。
AWS IoT Greengrass 目前不支援 Windows 核心裝置上的此功能。
+ `--max-log-queue-size`、`-m`。 要配置到記憶體的日誌項目數目上限。使用此選項可最佳化記憶體用量。預設為 100。
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli logs get --verbose \
--log-file /greengrass/v2/logs/greengrass.log \
--filter deployment,serviceName=DeploymentService \
--filter level=INFO \
--time-window 2020-12-08T01:11:17,2020-12-08T01:11:22
2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.DeploymentService: Current deployment finished. {DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService, currentState=RUNNING}
2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL}, ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc
```
## list-keywords
顯示建議的關鍵字，您可以用來篩選日誌檔案。
**概要**
```
greengrass-cli logs list-keywords [arguments]
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli logs list-keywords
Here is a list of suggested keywords for Greengrass log:
level=$str
thread=$str
loggerName=$str
eventType=$str
serviceName=$str
error=$str
```
```
$ sudo greengrass-cli logs list-keywords --syslog
Here is a list of suggested keywords for syslog:
priority=$int
host=$str
logger=$str
class=$str
```
## list-log-files
顯示位於指定目錄中的日誌檔案。
**概要**
```
greengrass-cli logs list-log-files [arguments]
```
**Arguments (引數)**
`--log-dir`、`-ld`。 要檢查日誌檔案的目錄路徑。
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/
/greengrass/v2/logs/aws.greengrass.Nucleus.log
/greengrass/v2/logs/main.log
/greengrass/v2/logs/greengrass.log
Total 3 files found.
```
# get-debug-password
使用 `get-debug-password`命令來為[本機偵錯主控台元件](local-debug-console-component.md) () 列印隨機產生的密碼`aws.greengrass.LocalDebugConsole`。密碼會在產生後 8 小時過期。
**概要**
```
greengrass-cli get-debug-password
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ sudo greengrass-cli get-debug-password
Username: debug
Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
Password expires at: 2021-04-01T17:01:43.921999931-07:00
The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console.
Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints.
SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B
SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1
```