翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# コンポーネント設定とやり取り
<a name="ipc-component-configuration"></a>

コンポーネント設定 IPC サービスでは以下のことが行えます。
+ コンポーネント設定パラメータを取得および設定します。
+ コンポーネント設定の更新をサブスクライブします。
+ コンポーネント設定の更新を、nucleus が適用する前に検証します。

**Topics**
+ [最小 SDK バージョン](#ipc-component-configuration-sdk-versions)
+ [GetConfiguration](#ipc-operation-getconfiguration)
+ [UpdateConfiguration](#ipc-operation-updateconfiguration)
+ [SubscribeToConfigurationUpdate](#ipc-operation-subscribetoconfigurationupdate)
+ [SubscribeToValidateConfigurationUpdates](#ipc-operation-subscribetovalidateconfigurationupdates)
+ [SendConfigurationValidityReport](#ipc-operation-sendconfigurationvalidityreport)

## 最小 SDK バージョン
<a name="ipc-component-configuration-sdk-versions"></a>

次の表に、コンポーネント設定を操作するために使用 AWS IoT Device SDK する必要がある の最小バージョンを示します。


| SDK | 最小バージョン | 
| --- | --- | 
|  [AWS IoT Device SDK for Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK Python v2 用](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK C\$1\$1 v2 用](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK for JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## GetConfiguration
<a name="ipc-operation-getconfiguration"></a>

コアデバイス上のコンポーネントの設定値を取得します。設定値を取得するためのキーパスを指定します。

### リクエスト
<a name="ipc-operation-getconfiguration-request"></a>

このオペレーションのリクエストには以下のパラメータがあります。

`componentName` (Python: `component_name`)  <a name="ipc-configuration-request-component-name"></a>
(オプション) コンポーネントの名前。  
デフォルトでは、リクエストを実行するコンポーネントの名前になっています。

`keyPath` (Python: `key_path`)  
設定値へのキーパス。各エントリが設定オブジェクトの単一レベルのキーとなるリストを指定します。たとえば、以下の設定で `port` の値を取得するには、`["mqtt", "port"]` を指定します。  

```
{
  "mqtt": {
    "port": 443
  }
}
```
コンポーネントの完全な設定を取得するには、空のリストを指定します。

### 応答
<a name="ipc-operation-getconfiguration-response"></a>

このオペレーションのレスポンスには以下の情報が含まれます。

`componentName` (Python: `component_name`)  <a name="ipc-configuration-response-component-name"></a>
コンポーネントの名前。

`value`  
オブジェクトとしてリクエストされた設定。

### 例
<a name="ipc-operation-getconfiguration-examples"></a>

以下の例では、カスタムコンポーネントコードでこのオペレーションを呼び出す方法を示します。

------
#### [ Rust ]

**Example 例: 設定を取得する**  

```
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 ]

**Example 例: 設定を取得する**  

```
#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\$1\$1 (Component SDK) ]

**Example 例: 設定を取得する**  

```
#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
<a name="ipc-operation-updateconfiguration"></a>

コアデバイス上のこのコンポーネントの設定値を更新します。

### リクエスト
<a name="ipc-operation-updateconfiguration-request"></a>

このオペレーションのリクエストには以下のパラメータがあります。

`keyPath` (Python: `key_path`)  
(オプション) 更新するコンテナノード (オブジェクト) へのキーパス。各エントリが設定オブジェクトの単一レベルのキーとなるリストを指定します。たとえば、キーパス `["mqtt"]` とマージ値 `{ "port": 443 }` を指定して、以下の設定に `port` の値を設定します。  

```
{
  "mqtt": {
    "port": 443
  }
}
```
キーパスは、設定内のコンテナノード (オブジェクト) を指定する必要があります。コンポーネントの設定にノードが存在しない場合、このオペレーションによってノードが作成され、`valueToMerge` のオブジェクトにその値が設定されます。  
設定オブジェクトのルートに対するデフォルトです。

`timestamp`  
現在の UNIX エポック時間 (ミリ秒)。このオペレーションにおけるキーの同時更新の解決には、このタイムスタンプが使用されます。コンポーネント設定のキーのタイムスタンプがリクエストのタイムスタンプよりも大きい場合、リクエストは失敗します。

`valueToMerge` (Python: `value_to_merge`)  
`keyPath` で指定した場所でマージする設定オブジェクト。(詳細については、[コンポーネント設定の更新](update-component-configurations.md) を参照してください)。

### 応答
<a name="ipc-operation-updateconfiguration-response"></a>

このオペレーションはレスポンスで一切の情報を提供しません。

### 例
<a name="ipc-operation-updateconfiguration-examples"></a>

以下の例では、カスタムコンポーネントコードでこのオペレーションを呼び出す方法を示します。

------
#### [ Rust ]

**Example 例: 設定の更新**  

```
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 ]

**Example 例: 設定の更新**  

```
#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\$1\$1 (Component SDK) ]

**Example 例: 設定の更新**  

```
#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
<a name="ipc-operation-subscribetoconfigurationupdate"></a>

サブスクライブして、コンポーネントの設定更新時に通知を受け取るようにします。キーをサブスクライブすると、そのキーの子が更新されたとき通知を受けます。

<a name="ipc-subscribe-operation-note"></a>このオペレーションはサブスクリプションオペレーションで、イベントメッセージのストリームをサブスクライブするというものです。このオペレーションを使用するには、イベントメッセージ、エラー、およびストリームクロージャを処理する関数を使用して、ストリームレスポンスハンドラーを定義します。(詳細については、[IPC イベントストリームへのサブスクライブ](interprocess-communication.md#ipc-subscribe-operations) を参照してください)。

**イベントメッセージの種類:** `ConfigurationUpdateEvents`

### リクエスト
<a name="ipc-operation-subscribetoconfigurationupdate-request"></a>

このオペレーションのリクエストには以下のパラメータがあります。

`componentName` (Python: `component_name`)  <a name="ipc-configuration-request-component-name"></a>
(オプション) コンポーネントの名前。  
デフォルトでは、リクエストを実行するコンポーネントの名前になっています。

`keyPath` (Python: `key_path`)  
サブスクライブする設定値のキーパス。各エントリが設定オブジェクトの単一レベルのキーとなるリストを指定します。たとえば、以下の設定で `port` の値を取得するには、`["mqtt", "port"]` を指定します。  

```
{
  "mqtt": {
    "port": 443
  }
}
```
コンポーネント設定のすべての値の更新をサブスクライブするには、空のリストを指定します。

### 応答
<a name="ipc-operation-subscribetoconfigurationupdate-response"></a>

このオペレーションのレスポンスには以下の情報が含まれます。

`messages`  
通知メッセージのストリーム。このオブジェクト (`ConfigurationUpdateEvents`) には、次の情報が含まれます。    
`configurationUpdateEvent` (Python: `configuration_update_event`)  
設定更新イベント。このオブジェクト (`ConfigurationUpdateEvent`) には、次の情報が含まれます。    
`componentName` (Python: `component_name`)  <a name="ipc-configuration-response-component-name"></a>
コンポーネントの名前。  
`keyPath` (Python: `key_path`)  
更新された設定値へのキーパス。

### 例
<a name="ipc-operation-subscribetoconfigurationupdate-examples"></a>

以下の例では、カスタムコンポーネントコードでこのオペレーションを呼び出す方法を示します。

------
#### [ Rust ]

**Example 例: 設定更新をサブスクライブする**  

```
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 ]

**Example 例: 設定更新をサブスクライブする**  

```
#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\$1\$1 (Component SDK) ]

**Example 例: 設定更新をサブスクライブする**  

```
#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
<a name="ipc-operation-subscribetovalidateconfigurationupdates"></a>

サブスクライブして、このコンポーネントの設定更新より前に通知を受け取るようにします。これにより、コンポーネントは各自の設定に対し更新を検証できます。[SendConfigurationValidityReport](#ipc-operation-sendconfigurationvalidityreport) オペレーションを使用して、設定が有効かどうかを nucleus に伝えます。

**重要**  
ローカルデプロイは、コンポーネントに更新を通知しません。

<a name="ipc-subscribe-operation-note"></a>このオペレーションはサブスクリプションオペレーションで、イベントメッセージのストリームをサブスクライブするというものです。このオペレーションを使用するには、イベントメッセージ、エラー、およびストリームクロージャを処理する関数を使用して、ストリームレスポンスハンドラーを定義します。(詳細については、[IPC イベントストリームへのサブスクライブ](interprocess-communication.md#ipc-subscribe-operations) を参照してください)。

**イベントメッセージの種類:** `ValidateConfigurationUpdateEvents`

### リクエスト
<a name="ipc-operation-subscribetovalidateconfigurationupdates-request"></a>

このオペレーションのリクエストはパラメータを持ちません。

### 応答
<a name="ipc-operation-subscribetovalidateconfigurationupdates-response"></a>

このオペレーションのレスポンスには以下の情報が含まれます。

`messages`  
通知メッセージのストリーム。このオブジェクト (`ValidateConfigurationUpdateEvents`) には、次の情報が含まれます。    
`validateConfigurationUpdateEvent` (Python: `validate_configuration_update_event`)  
設定更新イベント。このオブジェクト (`ValidateConfigurationUpdateEvent`) には、次の情報が含まれます。    
`deploymentId` (Python: `deployment_id`)  
コンポーネントを更新する AWS IoT Greengrass デプロイの ID。  
`configuration`  
新しい設定を含むオブジェクト。

## SendConfigurationValidityReport
<a name="ipc-operation-sendconfigurationvalidityreport"></a>

このコンポーネントの設定更新が有効かどうかを nucleus に伝えます。新しい設定が有効でないことを nucleus に伝えると、デプロイは失敗します。[SubscribeToValidateConfigurationUpdates](#ipc-operation-subscribetovalidateconfigurationupdates) オペレーションを使用して、設定更新の検証をサブスクライブします。

コンポーネントが設定更新の検証の通知に応答しない場合、nucleus はデプロイの設定検証ポリシーで指定した時間だけ待機します。これがタイムアウトした後、nucleus はデプロイを続行します。デフォルトのコンポーネント検証のタイムアウトは 20 秒です。詳細については、[デプロイの作成](create-deployments.md) および [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) オペレーションを呼び出すときに提供できる [DeploymentConfigurationValidationPolicy](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_DeploymentConfigurationValidationPolicy.html) オブジェクトを参照してください。

### リクエスト
<a name="ipc-operation-sendconfigurationvalidityreport-request"></a>

このオペレーションのリクエストには以下のパラメータがあります。

`configurationValidityReport` (Python: `configuration_validity_report`)  
設定更新が有効かどうかを nucleus に伝えるレポート。このオブジェクト (`ConfigurationValidityReport`) には、次の情報が含まれます。    
`status`  
有効性のステータス。この列挙型 (`ConfigurationValidityStatus`) には以下の値があります。  
+ `ACCEPTED` - 設定が有効で、nucleus はこのコンポーネントに適用できます。
+ `REJECTED` - 設定が有効ではなく、デプロイが失敗します。  
`deploymentId` (Python: `deployment_id`)  
設定の更新をリクエストした AWS IoT Greengrass デプロイの ID。  
`message`  
(オプション) 設定が有効でないことの理由を報告するメッセージ。

### 応答
<a name="ipc-operation-sendconfigurationvalidityreport-response"></a>

このオペレーションはレスポンスで一切の情報を提供しません。