コンポーネントライフサイクルの操作 - AWS IoT Greengrass
最小 SDK バージョンAuthorizationUpdateStateSubscribeToComponentUpdatesDeferComponentUpdatePauseComponentResumeComponent

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

コンポーネントライフサイクルの操作

コンポーネントライフサイクルの IPC サービスを使用して、次を行います。

  • コアデバイスのコンポーネント状態の更新。

  • コンポーネント状態の更新のサブスクライブ。

  • デプロイ中に nucleus によりコンポーネントが停止され、更新が適用されることの防止。

  • コンポーネントのプロセスの一時停止と再開。

最小 SDK バージョン

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

SDK 最小バージョン

AWS IoT Device SDK for Java v2

v1.2.10

AWS IoT Device SDK Python v2 用

v1.5.3

AWS IoT Device SDK C++ v2 用

v1.17.0

AWS IoT Device SDK for JavaScript v2

v1.12.0

Authorization

カスタムコンポーネントから他のコンポーネントを一時停止または再開するには、コンポーネントが他のコンポーネントを管理できるようにする承認ポリシーを定義する必要があります。承認ポリシーの定義については、「コンポーネントに IPC オペレーションの実行を許可する」を参照してください。

コンポーネントライフサイクル管理の承認ポリシーには、次のプロパティがあります。

IPC サービス識別子: aws.greengrass.ipc.lifecycle

運用 説明 リソース

aws.greengrass#PauseComponent

コンポーネントが、指定したコンポーネントを一時停止できるようにします。

すべてのコンポーネントへのアクセスを許可するコンポーネント名または *。

aws.greengrass#ResumeComponent

コンポーネントが、指定したコンポーネントを再開できるようにします。

すべてのコンポーネントへのアクセスを許可するコンポーネント名または *。

*

コンポーネントが、指定したコンポーネントを一時停止および再開できるようにします。

すべてのコンポーネントへのアクセスを許可するコンポーネント名または *。

承認ポリシーの例

次の承認ポリシーの例を参照して、コンポーネントの承認ポリシーの設定に役立てることができます。

例承認ポリシーの例

次の承認ポリシーの例では、コンポーネントが、すべてのコンポーネントを一時停止および再開できるようにします。

{
  "accessControl": {
    "aws.greengrass.ipc.lifecycle": {
      "com.example.MyLocalLifecycleComponent:lifecycle:1": {
        "policyDescription": "Allows access to pause/resume all components.",
        "operations": [
          "aws.greengrass#PauseComponent",
          "aws.greengrass#ResumeComponent"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}

UpdateState

コアデバイスのコンポーネントの状態を更新します。

リクエスト

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

state

設定する状態。この列挙型 (LifecycleState) には以下の値があります。

  • RUNNING

  • ERRORED

応答

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

例

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

Rust
例例: 更新状態
use gg_sdk::{ComponentState, Sdk};

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

    // Update component state to RUNNING
    sdk.update_state(ComponentState::Running)
        .expect("Failed to update component state");

    println!("Successfully updated component state to RUNNING.");
}
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);
    }

    // Update component state to RUNNING
    err = ggipc_update_state(GG_COMPONENT_STATE_RUNNING);
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to update component state.\n");
        exit(-1);
    }

    printf("Successfully updated component state to RUNNING.\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 component state to RUNNING
    error = client.update_component_state(GG_COMPONENT_STATE_RUNNING);
    if (error) {
        std::cerr << "Failed to update component state.\n";
        exit(-1);
    }

    std::cout << "Successfully updated component state to RUNNING.\n";
}

SubscribeToComponentUpdates

AWS IoT Greengrass Core ソフトウェアがコンポーネントを更新する前に通知を受信するには、サブスクライブします。通知では、更新の一部として nucleus を再起動するかどうかを指定します。

nucleus は、デプロイのコンポーネント更新ポリシーがコンポーネントに通知するように指定されている場合のみ、更新通知を送信します。デフォルトの動作では、コンポーネントに通知を行います。詳細については、デプロイの作成 および CreateDeployment オペレーションを呼び出すときに提供できる DeploymentComponentUpdatePolicy オブジェクトを参照してください。

重要

更新前にローカルデプロイがコンポーネントに通知を行うことばありません。

このオペレーションはサブスクリプションオペレーションで、イベントメッセージのストリームをサブスクライブするというものです。このオペレーションを使用するには、イベントメッセージ、エラー、およびストリームクロージャを処理する関数を使用して、ストリームレスポンスハンドラーを定義します。(詳細については、IPC イベントストリームへのサブスクライブ を参照してください)。

イベントメッセージの種類: ComponentUpdatePolicyEvents

ヒント

チュートリアルに従って、条件付きでコンポーネントの更新を延期するコンポーネントを開発する方法を説明します。(詳細については、チュートリアル: コンポーネントの更新を延期する Greengrass コンポーネントを開発する を参照してください)。

リクエスト

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

応答

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

messages

通知メッセージのストリーム。このオブジェクト (ComponentUpdatePolicyEvents) には、次の情報が含まれます。

preUpdateEvent (Python: pre_update_event)

(オプション) nucleus がコンポーネントの更新を希望することを示すイベント。DeferComponentUpdate オペレーションで応答して更新を承認するか、コンポーネントを再起動する準備が整うまで延期するかを選択できます。このオブジェクト (PreComponentUpdateEvent) には、次の情報が含まれます。

deploymentId (Python: deployment_id)

コンポーネントを更新する AWS IoT Greengrass デプロイの ID。

isGgcRestarting (Python: is_ggc_restarting)

更新を適用するために nucleus を再起動する必要があるかどうか。

postUpdateEvent (Python: post_update_event)

(オプション) nucleus がコンポーネントを更新したことを示すイベント。このオブジェクト (PostComponentUpdateEvent) には、次の情報が含まれます。

deploymentId (Python: deployment_id)

コンポーネントを更新した AWS IoT Greengrass デプロイの ID。

注記

この機能を使用するには、Greengrass nucleus コンポーネントの v2.7.0 以降が必要です。

DeferComponentUpdate

SubscribeToComponentUpdates で検出したコンポーネントの更新を承認または延期します。コンポーネントが更新を進める準備ができているかどうか、nucleus が再度チェックするまで待機する時間を指定します。このオペレーションを使用して、コンポーネントが更新の準備ができていることを nucleus に通知することもできます。

コンポーネントがコンポーネント更新通知に応答しない場合、nucleus はデプロイのコンポーネント更新ポリシーで指定した時間だけ待機します。これがタイムアウトした後、nucleus はデプロイを続行します。デフォルトのコンポーネント更新のタイムアウトは 60 秒です。詳細については、デプロイの作成 および CreateDeployment オペレーションを呼び出すときに提供できる DeploymentComponentUpdatePolicy オブジェクトを参照してください。

ヒント

チュートリアルに従って、条件付きでコンポーネントの更新を延期するコンポーネントを開発する方法を説明します。(詳細については、チュートリアル: コンポーネントの更新を延期する Greengrass コンポーネントを開発する を参照してください)。

リクエスト

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

deploymentId (Python: deployment_id)

延期する AWS IoT Greengrass デプロイの ID。

message

(オプション) 更新を延期するコンポーネントの名前。

デフォルトでは、リクエストを実行するコンポーネントの名前になっています。

recheckAfterMs (Python: recheck_after_ms)

更新を延期する時間 (ミリ秒)。nucleus はこの時間だけ待機してから、SubscribeToComponentUpdates で発見できる別の PreComponentUpdateEvent を送信します。

0 を指定すると更新が承認されます。これにより、コンポーネントが更新の準備ができていることが nucleus に通知されます。

デフォルトは 0 ミリ秒で、これは更新を承認することを意味します。

応答

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

PauseComponent

この機能は、Greengrass nucleus コンポーネントの v2.4.0 以降で使用できます。現在、この機能は Windows AWS IoT Greengrass コアデバイスでサポートされていません。

コアデバイスのコンポーネントのプロセスを一時停止します。コンポーネントを再開するには、ResumeComponent オペレーションを使用します。

一時停止できるのはジェネリックコンポーネントのみです。他の種類のコンポーネントを一時停止しようとすると、オペレーションは InvalidRequestError をスローします。

注記

この操作は、Docker コンテナなどのコンテナ化されたプロセスは一時停止できません。Docker コンテナの一時停止および再開を行うには、docker pause および docker unpause コマンドを使用できます。

このオペレーションは、コンポーネントの依存関係や、一時停止するコンポーネントに依存するコンポーネントに対しては、一時停止を行いません。別のコンポーネントの依存関係であるコンポーネントを一時停止するときは、この動作を検討してください。依存するコンポーネントは、依存関係が一時停止されたときに問題が発生する可能性があるためです。

デプロイ経由などで一時停止したコンポーネントを再起動またはシャットダウンすると、Greengrass nucleus はコンポーネントを再開し、シャットダウンライフサイクルを実行します。コンポーネントの再起動についての詳細は、「RestartComponent」を参照してください。

重要

このオペレーションを使用するには、このオペレーションを使用する権限を付与する承認ポリシーを定義する必要があります。(詳細については、Authorization を参照してください)。

最小 SDK バージョン

次の表 AWS IoT Device SDK に、コンポーネントの一時停止と再開に使用する必要がある の最小バージョンを示します。

リクエスト

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

componentName (Python: component_name)

一時停止するコンポーネントの名前。ジェネリックコンポーネントである必要があります。(詳細については、コンポーネントタイプ を参照してください)。

応答

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

ResumeComponent

この機能は、Greengrass nucleus コンポーネントの v2.4.0 以降で使用できます。現在、この機能は Windows AWS IoT Greengrass コアデバイスでサポートされていません。

コアデバイスのコンポーネントのプロセスを再開します。コンポーネントを一時停止するには、PauseComponent オペレーションを使用します。

再開できるのは一時停止しているコンポーネントのみです。一時停止していないコンポーネントを再開しようとすると、このオペレーションは InvalidRequestError をスローします。

重要

このオペレーションを使用するには、そうするための権限を付与する承認ポリシーを定義する必要があります。(詳細については、Authorization を参照してください)。

最小 SDK バージョン

次の表 AWS IoT Device SDK に、コンポーネントの一時停止と再開に使用する必要がある の最小バージョンを示します。

リクエスト

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

componentName (Python: component_name)

再開するコンポーネントの名前。

応答

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