구성 요소 구성과 연동 - AWS IoT Greengrass

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

구성 요소 구성과 연동

구성 요소 구성 IPC 서비스를 사용하여 다음을 수행할 수 있습니다.

  • 구성 요소 구성 파라미터를 가져오고 설정합니다.

  • 구성 요소 구성 업데이트를 구독합니다.

  • nucleus에서 구성 요소 구성 업데이트를 적용하기 전에 검증합니다.

최소 SDK 버전

다음 표에는 구성 요소 구성과 상호 작용하는 데 사용해야 AWS IoT Device SDK 하는의 최소 버전이 나열되어 있습니다.

GetConfiguration

코어 디바이스의 구성 요소에 대한 구성 값을 가져옵니다. 구성 값을 가져올 키 경로를 지정합니다.

요청

이 작업의 요청에서는 다음 파라미터를 사용합니다.

componentName(Python: component_name)

(선택 사항) 구성 요소의 이름입니다.

기본값은 요청을 하는 구성 요소의 이름입니다.

keyPath(Python: key_path)

구성 값의 키 경로입니다. 각 항목이 구성 객체에서 단일 수준에 대한 키인 목록을 지정합니다. 예를 들어 다음 구성에서 port의 값을 가져오려면 ["mqtt", "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)

(선택 사항) 업데이트할 컨테이너 노드(객체)의 키 경로입니다. 각 항목이 구성 객체에서 단일 수준에 대한 키인 목록을 지정합니다. 예를 들어 다음 구성에서 port의 값을 설정하려면 키 경로 ["mqtt"] 및 병합 값 { "port": 443 }을 지정합니다.

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

키 경로는 구성의 컨테이너 노드(객체)를 지정해야 합니다. 노드가 구성 요소의 구성에 없는 경우 이 작업은 노드를 생성하고 해당 값을 valueToMerge의 객체로 설정합니다.

기본값은 구성 객체의 루트입니다.

timestamp

현재 Unix epoch 시간(밀리초)입니다. 이 작업은 이 타임스탬프를 사용하여 키에 대한 동시 업데이트를 해결합니다. 구성 요소 구성의 키의 타임스탬프가 요청의 타임스탬프보다 크면 요청이 실패합니다.

valueToMerge(Python: value_to_merge)

keyPath에서 지정하는 위치에서 병합할 구성 객체입니다. 자세한 내용은 구성 요소 구성 업데이트 단원을 참조하십시오.

응답

이 작업의 응답에는 어떠한 정보도 제공하지 않습니다.

예제

다음 예제에서는 사용자 지정 구성 요소 코드에서 이 작업을 직접 호출하는 방법을 보여줍니다.

Rust
예예: 구성 업데이트
use gg_sdk::Sdk; fn main() { let sdk = Sdk::init(); sdk.connect().expect("Failed to establish IPC connection"); // Update configuration value at key path ["mqtt", "port"] to 443 sdk.update_config(&["mqtt", "port"], None, 443) .expect("Failed to update configuration"); println!("Successfully updated configuration."); }
C
예예: 구성 업데이트
#include <gg/error.h> #include <gg/ipc/client.h> #include <gg/object.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); } // Update configuration value at key path ["mqtt", "port"] to 443 err = ggipc_update_config( GG_BUF_LIST(GG_STR("mqtt"), GG_STR("port")), NULL, // timestamp (NULL = current time) gg_obj_i64(443) ); if (err != GG_ERR_OK) { fprintf(stderr, "Failed to update configuration.\n"); exit(-1); } printf("Successfully updated configuration.\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); } // Update configuration value at key path ["mqtt", "port"] to 443 std::array key_path = { gg::Buffer { "mqtt" }, gg::Buffer { "port" } }; error = client.update_config(key_path, 443); if (error) { std::cerr << "Failed to update configuration.\n"; exit(-1); } std::cout << "Successfully updated configuration.\n"; }

SubscribeToConfigurationUpdate

구성 요소의 구성이 업데이트될 때 알림을 수신하려면 구독합니다. 키를 구독하는 경우 해당 키의 하위 키가 업데이트되면 알림을 받습니다.

이 작업은 이벤트 메시지 스트림을 구독하는 구독 작업입니다. 이 작업을 사용하려면 이벤트 메시지, 오류 및 스트림 종료를 처리하는 함수를 사용하여 스트림 응답 핸들러를 정의합니다. 자세한 내용은 IPC 이벤트 스트림 구독 단원을 참조하십시오.

이벤트 메시지 유형: ConfigurationUpdateEvents

요청

이 작업의 요청에서는 다음 파라미터를 사용합니다.

componentName(Python: component_name)

(선택 사항) 구성 요소의 이름입니다.

기본값은 요청을 하는 구성 요소의 이름입니다.

keyPath(Python: key_path)

구독할 구성 값의 키 경로입니다. 각 항목이 구성 객체에서 단일 수준에 대한 키인 목록을 지정합니다. 예를 들어 다음 구성에서 port의 값을 가져오려면 ["mqtt", "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 작업을 사용하면 구성이 유효한지 여부를 nucleus에 알립니다.

중요

로컬 배포에서는 업데이트에 대해 구성 요소에 알리지 않습니다.

이 작업은 이벤트 메시지 스트림을 구독하는 구독 작업입니다. 이 작업을 사용하려면 이벤트 메시지, 오류 및 스트림 종료를 처리하는 함수를 사용하여 스트림 응답 핸들러를 정의합니다. 자세한 내용은 IPC 이벤트 스트림 구독 단원을 참조하십시오.

이벤트 메시지 유형: ValidateConfigurationUpdateEvents

요청

이 작업의 요청에는 파라미터가 없습니다.

응답

이 작업의 응답에는 다음 정보가 포함됩니다.

messages

알림 메시지의 스트림입니다. 이 객체 ValidateConfigurationUpdateEvents에는 다음 정보가 포함됩니다.

validateConfigurationUpdateEvent(Python: validate_configuration_update_event)

구성 업데이트 이벤트입니다. 이 객체 ValidateConfigurationUpdateEvent에는 다음 정보가 포함됩니다.

deploymentId(Python: deployment_id)

구성 요소를 업데이트하는 AWS IoT Greengrass 배포의 ID입니다.

configuration

새 구성을 포함하는 객체입니다.

SendConfigurationValidityReport

이 구성 요소에 대한 구성 업데이트가 유효한지 여부를 nucleus에 알립니다. 새 구성이 유효하지 않다고 nucleus에 알리면 배포가 실패합니다. SubscribeToValidateConfigurationUpdates 작업을 사용하면 구성 업데이트 검증을 구독할 수 있습니다.

구성 요소가 구성 업데이트 검증 알림에 응답하지 않으면 nucleus는 배포의 구성 검증 정책에 지정한 시간을 기다립니다. 이 제한 시간이 지나면 nucleus는 배포를 진행합니다. 기본 구성 요소 검증 제한 시간은 20초입니다. 자세한 내용은 배포 만들기 섹션 및 CreateDeployment 작업을 직접 호출할 때 제공할 수 있는 DeploymentConfigurationValidationPolicy 객체를 참조하세요.

요청

이 작업의 요청에서는 다음 파라미터를 사용합니다.

configurationValidityReport(Python: configuration_validity_report)

구성 업데이트가 유효한지 여부를 nucleus에 알려주는 보고서입니다. 이 객체 ConfigurationValidityReport에는 다음 정보가 포함됩니다.

status

유효성 상태입니다. 이 열거형 ConfigurationValidityStatus의 값은 다음과 같습니다.

  • ACCEPTED - 구성이 유효하며 nucleus가 이 구성 요소에 적용할 수 있습니다.

  • REJECTED - 구성이 유효하지 않고 배포가 실패합니다.

deploymentId(Python: deployment_id)

구성 업데이트를 요청한 AWS IoT Greengrass 배포의 ID입니다.

message

(선택 사항) 구성이 유효하지 않은 이유를 보고하는 메시지입니다.

응답

이 작업의 응답에는 어떠한 정보도 제공하지 않습니다.