最低 SDK 版本 GetConfiguration UpdateConfiguration SubscribeToConfigurationUpdate SubscribeToValidateConfigurationUpdates SendConfigurationValidityReport

與元件組態互動

元件組態 IPC 服務可讓您執行下列動作：

取得並設定元件組態參數。
訂閱元件組態更新。
在套用核心之前驗證元件組態更新。

主題

最低 SDK 版本
GetConfiguration
UpdateConfiguration
SubscribeToConfigurationUpdate
SubscribeToValidateConfigurationUpdates
SendConfigurationValidityReport

最低 SDK 版本

下表列出 AWS IoT Device SDK 您必須用來與元件組態互動的最低版本。

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

GetConfiguration

取得核心裝置上元件的組態值。您可以指定要取得組態值的金鑰路徑。

請求

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

componentName (Python：component_name)

（選用）元件的名稱。

預設為發出請求的元件名稱。

keyPath (Python：key_path)

組態值的金鑰路徑。指定清單，其中每個項目都是組態物件中單一層級的金鑰。例如，指定 ["mqtt", "port"] 在下列組態port中取得的值。


{
  "mqtt": {
    "port": 443
  }
}

若要取得元件的完整組態，請指定空白清單。

回應

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

componentName (Python：component_name): 元件的名稱。
value: 請求的組態做為物件。

範例

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

Rust

範例範例：取得組態


use core::mem::MaybeUninit;
use gg_sdk::{Sdk, UnpackedObject};

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

    // Get a configuration value at key path ["mqtt", "port"]
    let mut buf = [MaybeUninit::uninit(); 1024];

    let value = sdk
        .get_config(&["mqtt", "port"], None, &mut buf)
        .expect("Failed to get configuration");

    if let UnpackedObject::I64(port) = value.unpack() {
        println!("Configuration value: {port}");
    }
}

C

範例範例：取得組態


#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <inttypes.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);
    }

    // Get a configuration value at key path ["mqtt", "port"]
    uint8_t response_mem[1024];
    GgObject value;

    err = ggipc_get_config(
        GG_BUF_LIST(GG_STR("mqtt"), GG_STR("port")),
        NULL, // component_name (NULL = current component)
        GG_BUF(response_mem),
        &value
    );
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to get configuration.\n");
        exit(-1);
    }

    if (gg_obj_type(value) == GG_TYPE_I64) {
        printf("Configuration value: %" PRId64 "\n", gg_obj_into_i64(value));
    } else if (gg_obj_type(value) == GG_TYPE_BUF) {
        GgBuffer buf = gg_obj_into_buf(value);
        printf("Configuration value: %.*s\n", (int) buf.len, buf.data);
    } else {
        printf("Configuration value is of unexpected type.\n");
    }
}

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);
    }

    // Get a configuration value at key path ["mqtt", "port"]
    std::array key_path = { gg::Buffer { "mqtt" }, gg::Buffer { "port" } };
    int64_t value = 0;

    error = client.get_config(key_path, std::nullopt, value);
    if (error) {
        std::cerr << "Failed to get configuration.\n";
        exit(-1);
    }

    std::cout << "Configuration value: " << value << "\n";
}

UpdateConfiguration

更新核心裝置上此元件的組態值。

請求

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

keyPath (Python：key_path)

（選用）要更新的容器節點 ( 物件）的金鑰路徑。指定清單，其中每個項目都是組態物件中單一層級的金鑰。例如，指定金鑰路徑["mqtt"]和合併值{ "port": 443 }，以在下列組態port中設定的值。


{
  "mqtt": {
    "port": 443
  }
}

金鑰路徑必須在組態中指定容器節點（物件）。如果節點不存在於元件的組態中，此操作會建立節點，並將其值設定為中的物件valueToMerge。

預設為組態物件的根。

timestamp

目前的 Unix epoch 時間，以毫秒為單位。此操作使用此時間戳記來解析金鑰的並行更新。如果元件組態中的索引鍵的時間戳記大於請求中的時間戳記，則請求會失敗。

valueToMerge (Python：value_to_merge)

要在您在中指定的位置合併的組態物件keyPath。如需詳細資訊，請參閱更新元件組態。

回應

此操作不會在其回應中提供任何資訊。

範例

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

SubscribeToConfigurationUpdate

訂閱以在元件的組態更新時接收通知。當您訂閱金鑰時，當該金鑰的任何子項更新時，您會收到通知。

此操作是您訂閱事件訊息串流的訂閱操作。若要使用此操作，請使用處理事件訊息、錯誤和串流關閉的函數來定義串流回應處理常式。如需詳細資訊，請參閱訂閱 IPC 事件串流。

事件訊息類型： ConfigurationUpdateEvents

請求

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

componentName (Python：component_name)

（選用）元件的名稱。

預設為發出請求的元件名稱。

keyPath (Python：key_path)

要訂閱之組態值的金鑰路徑。指定清單，其中每個項目都是組態物件中單一層級的金鑰。例如，指定 ["mqtt", "port"] 在下列組態port中取得的值。


{
  "mqtt": {
    "port": 443
  }
}

若要訂閱元件組態中所有值的更新，請指定空白清單。

回應

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

messages

通知訊息的串流。此物件 ConfigurationUpdateEvents包含下列資訊：

configurationUpdateEvent (Python：configuration_update_event)

組態更新事件。此物件 ConfigurationUpdateEvent包含下列資訊：

componentName (Python：component_name): 元件的名稱。
keyPath (Python：key_path): 已更新之組態值的金鑰路徑。

範例

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

Rust

範例範例：訂閱組態更新


use gg_sdk::Sdk;
use std::{thread, time::Duration};

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

    // Subscribe to configuration updates for key path ["mqtt"]
    let callback = |component_name: &str, key_path: &[&str]| {
        println!(
            "Received configuration update for component: {component_name}"
        );
        println!("Key path: {key_path:?}");
    };

    let _sub = sdk
        .subscribe_to_configuration_update(None, &["mqtt"], &callback)
        .expect("Failed to subscribe to configuration updates");

    println!("Successfully subscribed to configuration updates.");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}

C

範例範例：訂閱組態更新


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

static void on_subscription_response(
    void *ctx,
    GgBuffer component_name,
    GgList key_path,
    GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    printf(
        "Received configuration update for component: %.*s\n",
        (int) component_name.len,
        component_name.data
    );

    printf("Key path: [");
    for (size_t i = 0; i < key_path.len; i++) {
        if (i > 0) {
            printf(", ");
        }
        GgObject *obj = &key_path.items[i];
        if (gg_obj_type(*obj) == GG_TYPE_BUF) {
            GgBuffer key = gg_obj_into_buf(*obj);
            printf("\"%.*s\"", (int) key.len, key.data);
        }
    }
    printf("]\n");
}

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);
    }

    // Subscribe to configuration updates for key path ["mqtt"]
    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_configuration_update(
        NULL, // component_name (NULL = current component)
        GG_BUF_LIST(GG_STR("mqtt")),
        on_subscription_response,
        NULL,
        &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to subscribe to configuration updates.\n");
        exit(-1);
    }

    printf("Successfully subscribed to configuration updates.\n");

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the stream.
    ggipc_close_subscription(handle);
}

C++ (Component SDK)

範例範例：訂閱組態更新


#include <gg/ipc/client.hpp>
#include <unistd.h>
#include <iostream>

class ResponseHandler : public gg::ipc::ConfigurationUpdateCallback {
    void operator()(
        std::string_view component_name,
        gg::List key_path,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        std::cout << "Received configuration update for component: "
                  << component_name << "\n";
        std::cout << "Key path: [";
        for (size_t i = 0; i < key_path.size(); i++) {
            if (i > 0) {
                std::cout << ", ";
            }
            std::cout << "\"" << get<gg::Buffer>(key_path[i]) << "\"";
        }
        std::cout << "]\n";
    }
};

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

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

    // Subscribe to configuration updates for key path ["mqtt"]
    std::array key_path = { gg::Buffer { "mqtt" } };

    static ResponseHandler handler;
    error = client.subscribe_to_configuration_update(
        key_path, std::nullopt, handler
    );
    if (error) {
        std::cerr << "Failed to subscribe to configuration updates.\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to configuration updates.\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}

SubscribeToValidateConfigurationUpdates

訂閱以在此元件的組態更新之前接收通知。這可讓元件驗證其自身組態的更新。使用 SendConfigurationValidityReport操作來告知核心組態是否有效。

重要

本機部署不會通知更新元件。

事件訊息類型： ValidateConfigurationUpdateEvents

請求

此操作的請求沒有任何參數。

回應

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

messages

通知訊息的串流。此物件 ValidateConfigurationUpdateEvents包含下列資訊：

validateConfigurationUpdateEvent (Python：validate_configuration_update_event)

組態更新事件。此物件 ValidateConfigurationUpdateEvent包含下列資訊：

deploymentId (Python：deployment_id): 更新元件的 AWS IoT Greengrass 部署 ID。
configuration: 包含新組態的物件。

SendConfigurationValidityReport

告知核心此元件的組態更新是否有效。如果您告訴 nucleus 新組態無效，則部署會失敗。使用 SubscribeToValidateConfigurationUpdates操作來訂閱以驗證組態更新。

如果元件未回應驗證組態更新通知，則 nucleus 會等待您在部署的組態驗證政策中指定的時間量。逾時之後，核會繼續進行部署。預設元件驗證逾時為 20 秒。如需詳細資訊，請參閱建立部署和您可以在呼叫 CreateDeployment 操作時提供的 DeploymentConfigurationValidationPolicy 物件。

請求

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

configurationValidityReport (Python：configuration_validity_report)

此報告會告知 nucleus 組態更新是否有效。此物件 ConfigurationValidityReport包含下列資訊：

status

有效性狀態。此列舉 ConfigurationValidityStatus具有下列值：

ACCEPTED – 組態有效，且核可以套用到此元件。
REJECTED – 組態無效且部署失敗。

deploymentId (Python：deployment_id)

請求組態更新的 AWS IoT Greengrass 部署 ID。

message

（選用）報告組態為何無效的訊息。

回應

此操作不會在其回應中提供任何資訊。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

與元件生命週期互動

擷取秘密值

與元件組態互動

主題

最低 SDK 版本

GetConfiguration

請求

回應

範例

範例範例：取得組態

範例範例：取得組態

範例範例：取得組態

UpdateConfiguration

請求

回應

範例

範例範例：更新組態

範例範例：更新組態

範例範例：更新組態

SubscribeToConfigurationUpdate

請求

回應

範例

範例範例：訂閱組態更新

範例範例：訂閱組態更新

範例範例：訂閱組態更新

SubscribeToValidateConfigurationUpdates

重要

請求

回應

SendConfigurationValidityReport

請求

回應