Interazione con la configurazione dei componenti - AWS IoT Greengrass

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Interazione con la configurazione dei componenti

Il servizio IPC di configurazione dei componenti consente di effettuare le seguenti operazioni:

  • Ottieni e imposta i parametri di configurazione dei componenti.

  • Iscriviti agli aggiornamenti della configurazione dei componenti.

  • Convalida gli aggiornamenti della configurazione dei componenti prima che il nucleo li applichi.

Versioni SDK minime

La tabella seguente elenca le versioni minime di SDK per dispositivi AWS IoT da utilizzare per interagire con la configurazione dei componenti.

GetConfiguration

Ottiene un valore di configurazione per un componente sul dispositivo principale. Specificate il percorso chiave per il quale ottenere un valore di configurazione.

Richiesta

La richiesta di questa operazione ha i seguenti parametri:

componentName(Python:) component_name

(Facoltativo) Il nome del componente.

Il valore predefinito è il nome del componente che effettua la richiesta.

keyPath(Python:) key_path

Il percorso chiave verso il valore di configurazione. Specificate un elenco in cui ogni voce è la chiave per un singolo livello nell'oggetto di configurazione. Ad esempio, specificate di ["mqtt", "port"] ottenere il valore di port nella seguente configurazione.

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

Per ottenere la configurazione completa del componente, specificate un elenco vuoto.

Risposta

La risposta di questa operazione contiene le seguenti informazioni:

componentName(Python:) component_name

Il nome del componente.

value

La configurazione richiesta come oggetto.

Esempi

Gli esempi seguenti mostrano come chiamare questa operazione nel codice componente personalizzato.

Rust
Esempio Esempio: Get configuration
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
Esempio Esempio: Get configuration
#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)
Esempio Esempio: Get configuration
#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

Aggiorna un valore di configurazione per questo componente sul dispositivo principale.

Richiesta

La richiesta di questa operazione ha i seguenti parametri:

keyPath(Python:) key_path

(Facoltativo) Il percorso chiave del nodo contenitore (l'oggetto) da aggiornare. Specificate un elenco in cui ogni voce è la chiave per un singolo livello nell'oggetto di configurazione. Ad esempio, specificate il percorso della chiave ["mqtt"] e il valore { "port": 443 } di unione di cui impostare il valore port nella seguente configurazione.

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

Il percorso chiave deve specificare un nodo contenitore (un oggetto) nella configurazione. Se il nodo non esiste nella configurazione del componente, questa operazione lo crea e imposta il suo valore sull'oggetto invalueToMerge.

Il valore predefinito è la radice dell'oggetto di configurazione.

timestamp

L'ora attuale dell'epoca Unix in millisecondi. Questa operazione utilizza questo timestamp per risolvere gli aggiornamenti simultanei della chiave. Se la chiave nella configurazione del componente ha un timestamp maggiore di quello della richiesta, la richiesta ha esito negativo.

valueToMerge(Python:) value_to_merge

L'oggetto di configurazione da unire nella posizione specificata. keyPath Per ulteriori informazioni, consulta Aggiornamento delle configurazioni dei componenti.

Risposta

Questa operazione non fornisce alcuna informazione nella sua risposta.

Esempi

Gli esempi seguenti mostrano come chiamare questa operazione nel codice componente personalizzato.

Rust
Esempio Esempio: aggiornamento della configurazione
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
Esempio Esempio: aggiornamento della configurazione
#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)
Esempio Esempio: aggiornamento della configurazione
#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

Iscriviti per ricevere notifiche quando la configurazione di un componente viene aggiornata. Quando sottoscrivi una chiave, ricevi una notifica ogni volta che un elemento secondario di quella chiave si aggiorna.

Questa operazione è un'operazione di sottoscrizione in cui ti iscrivi a un flusso di messaggi di eventi. Per utilizzare questa operazione, definite un gestore di risposte di flusso con funzioni che gestiscono i messaggi di evento, gli errori e la chiusura dei flussi. Per ulteriori informazioni, consulta Iscriviti ai flussi di eventi IPC.

Tipo di messaggio di evento: ConfigurationUpdateEvents

Richiesta

La richiesta di questa operazione ha i seguenti parametri:

componentName(Python:) component_name

(Facoltativo) Il nome del componente.

Il valore predefinito è il nome del componente che effettua la richiesta.

keyPath(Python:) key_path

Il percorso chiave del valore di configurazione a cui sottoscrivere. Specificate un elenco in cui ogni voce è la chiave per un singolo livello nell'oggetto di configurazione. Ad esempio, specificate di ["mqtt", "port"] ottenere il valore di port nella seguente configurazione.

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

Per sottoscrivere gli aggiornamenti per tutti i valori nella configurazione del componente, specificate un elenco vuoto.

Risposta

La risposta di questa operazione contiene le seguenti informazioni:

messages

Il flusso di messaggi di notifica. Questo oggetto contiene ConfigurationUpdateEvents le seguenti informazioni:

configurationUpdateEvent(Python:) configuration_update_event

L'evento di aggiornamento della configurazione. Questo oggetto contiene ConfigurationUpdateEvent le seguenti informazioni:

componentName(Python:) component_name

Il nome del componente.

keyPath(Python:) key_path

Il percorso chiave del valore di configurazione che è stato aggiornato.

Esempi

Gli esempi seguenti mostrano come chiamare questa operazione nel codice componente personalizzato.

Rust
Esempio Esempio: sottoscrizione agli aggiornamenti di configurazione
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
Esempio Esempio: sottoscrizione agli aggiornamenti di configurazione
#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)
Esempio Esempio: sottoscrizione agli aggiornamenti di configurazione
#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

Iscriviti per ricevere notifiche prima degli aggiornamenti della configurazione di questo componente. Ciò consente ai componenti di convalidare gli aggiornamenti alla propria configurazione. Utilizzate l'SendConfigurationValidityReportoperazione per indicare al nucleo se la configurazione è valida o meno.

Importante

Le distribuzioni locali non notificano ai componenti gli aggiornamenti.

Questa operazione è un'operazione di sottoscrizione in cui ci si iscrive a un flusso di messaggi di eventi. Per utilizzare questa operazione, definite un gestore di risposte di flusso con funzioni che gestiscono i messaggi di evento, gli errori e la chiusura dei flussi. Per ulteriori informazioni, consulta Iscriviti ai flussi di eventi IPC.

Tipo di messaggio di evento: ValidateConfigurationUpdateEvents

Richiesta

La richiesta di questa operazione non ha parametri.

Risposta

La risposta di questa operazione contiene le seguenti informazioni:

messages

Il flusso di messaggi di notifica. Questo oggetto contiene ValidateConfigurationUpdateEvents le seguenti informazioni:

validateConfigurationUpdateEvent(Python:) validate_configuration_update_event

L'evento di aggiornamento della configurazione. Questo oggetto contiene ValidateConfigurationUpdateEvent le seguenti informazioni:

deploymentId(Python:) deployment_id

L'ID della AWS IoT Greengrass distribuzione che aggiorna il componente.

configuration

L'oggetto che contiene la nuova configurazione.

SendConfigurationValidityReport

Indica al nucleo se un aggiornamento della configurazione di questo componente è valido o meno. L'implementazione fallisce se dici al nucleus che la nuova configurazione non è valida. Utilizza l'SubscribeToValidateConfigurationUpdatesoperazione per sottoscrivere e convalidare gli aggiornamenti di configurazione.

Se un componente non risponde a una notifica di convalida dell'aggiornamento della configurazione, il nucleus attende il periodo di tempo specificato nella politica di convalida della configurazione della distribuzione. Dopo tale timeout, il nucleo procede con la distribuzione. Il timeout di convalida dei componenti predefinito è di 20 secondi. Per ulteriori informazioni, vedere Creare distribuzione e l'DeploymentConfigurationValidationPolicyoggetto che è possibile fornire quando si chiama l'CreateDeploymentoperazione.

Richiesta

La richiesta di questa operazione ha i seguenti parametri:

configurationValidityReport(Python:) configuration_validity_report

Il rapporto che indica al nucleo se l'aggiornamento della configurazione è valido o meno. Questo oggetto contiene ConfigurationValidityReport le seguenti informazioni:

status

Lo stato di validità. Questo enum ha ConfigurationValidityStatus i seguenti valori:

  • ACCEPTED— La configurazione è valida e il nucleo può applicarla a questo componente.

  • REJECTED— La configurazione non è valida e l'implementazione non riesce.

deploymentId(Python:) deployment_id

L'ID della AWS IoT Greengrass distribuzione che ha richiesto l'aggiornamento della configurazione.

message

(Facoltativo) Un messaggio che riporta il motivo per cui la configurazione non è valida.

Risposta

Questa operazione non fornisce alcuna informazione nella sua risposta.