管理本機部署和元件 - AWS IoT Greengrass
最低 SDK 版本AuthorizationCreateLocalDeploymentListLocalDeploymentsGetLocalDeploymentStatusListComponentsGetComponentDetailsRestartComponentStopComponentCreateDebugPassword

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

管理本機部署和元件

注意

此功能適用於 Greengrass 核元件的 v2.6.0 和更新版本。

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

若要使用這些 IPC 操作，請在自訂元件中包含 2.6.0 版或更新版本的 Greengrass CLI 元件做為相依性。然後，您可以在自訂元件中使用 IPC 操作來執行下列動作：

  • 建立本機部署以修改和設定核心裝置上的 Greengrass 元件。

  • 在核心裝置上重新啟動和停止 Greengrass 元件。

  • 產生可用來登入本機偵錯主控台的密碼。

最低 SDK 版本

下表列出 AWS IoT Device SDK 您必須用來與 Greengrass CLI IPC 服務互動的 最低版本。

SDK 最低版本

AWS IoT Device SDK for Java v2

v1.2.10

AWS IoT Device SDK for Python v2

1.5.3 版

AWS IoT Device SDK 適用於 C++ v2

1.17.0 版

AWS IoT Device SDK for JavaScript v2

v1.12.0

Authorization

若要在自訂元件中使用 Greengrass CLI IPC 服務，您必須定義授權政策，允許您的元件管理本機部署和元件。如需定義授權政策的資訊，請參閱 授權元件執行 IPC 操作。

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

允許元件產生密碼，以用來登入本機偵錯主控台元件。

*
範例範例授權政策

下列範例授權政策允許元件建立本機部署、檢視所有本機部署和元件，以及重新啟動和停止名為 的元件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

元件的執行時間組態。如果您省略執行時間組態參數，則 AWS IoT Greengrass Core 軟體會使用您在 Greengrass 核上設定的預設值。此物件 RunWithInfo包含下列資訊：

posixUser (Python：posix_user)

（選用） POSIX 系統使用者和選用的群組，用於在 Linux 核心裝置上執行此元件。如果指定，使用者和群組必須存在於每個 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 數量上限 （以 KB 為單位）。

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

元件的狀態。此狀態可以是下列其中一項：

  • BROKEN

  • ERRORED

  • FINISHED

  • INSTALLED

  • NEW

  • RUNNING

  • STARTING

  • STOPPING

configuration

元件的組態做為 JSON 物件。

GetComponentDetails

取得核心裝置上元件的版本、狀態和組態。

此操作提供與 Greengrass CLI 中的元件詳細資訊命令相同的功能。

請求

此操作的請求具有下列參數：

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 中的元件重新啟動命令相同的功能。

請求

此操作的請求具有下列參數：

componentName (Python：component_name)

元件的名稱。

回應

此操作的回應包含下列資訊：

restartStatus (Python：restart_status)

重新啟動請求的狀態。請求狀態可以是下列其中一項：

  • SUCCEEDED

  • FAILED

message

說明如果請求失敗，為何元件無法重新啟動的訊息。

範例

下列範例示範如何在自訂元件程式碼中呼叫此操作。

Rust
範例範例：重新啟動元件
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
範例範例：重新啟動元件
#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++ (Component SDK)
範例範例：重新啟動元件
#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

在核心裝置上停止元件的程序。

注意

雖然您可以停止任何元件，但我們建議您僅停止一般元件。

此操作提供與 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 指紋。當您開啟本機偵錯主控台時，請使用此指紋來驗證憑證是否合法且連線安全。