最小 SDK バージョン認証 CreateLocalDeployment ListLocalDeployments GetLocalDeploymentStatus ListComponents GetComponentDetails RestartComponent StopComponent CreateDebugPassword

ローカルデプロイおよびコンポーネントの管理

注記

この機能は、Greengrass nucleus コンポーネントの v2.6.0 以降で利用できます。

Greengrass CLI IPC サービスを使用して、コアデバイスのローカルデプロイおよび Greengrass コンポーネントを管理します。

これらの IPC オペレーションを使用するには、カスタムコンポーネントの依存関係として、バージョン 2.6.0 以降の Greengrass CLI コンポーネントを含めます。その後、カスタムコンポーネントの IPC オペレーションを使用して、次の操作を行うことができます。

ローカルデプロイを作成し、コアデバイスの Greengrass コンポーネントを変更および設定します。
コアデバイスの Greengrass コンポーネントを再起動して停止します。
ローカルデバッグコンソールへのサインインに使用できるパスワードを生成します。

最小 SDK バージョン

次の表に、AWS IoT Device SDK の最小バージョンを示します。Greengrass CLI IPC サービスとやり取りする際は、これを使用する必要があります。

SDK	最小バージョン
AWS IoT Device SDK for Java v2	v1.2.10
AWS IoT Device SDK for Python v2	v1.5.3
AWS IoT Device SDK for C++ v2	v1.17.0
AWS IoT Device SDK JavaScript v2 用	v1.12.0

認証

Greengrass CLI IPC サービスをカスタムコンポーネントで使用するには、コンポーネントがローカルデプロイとコンポーネントを管理できるように承認ポリシーを定義する必要があります。承認ポリシーの定義については、「コンポーネントにIPCオペレーションの実行を許可する」を参照してください。

Greengrass CLI の承認ポリシーには、次のプロパティがあります。

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

操作	説明	リソース
`aws.greengrass#CreateLocalDeployment`	コンポーネントがコアデバイスにローカルデプロイを作成できるようにします。	`*`
`aws.greengrass#ListLocalDeployments`	コンポーネントがコアデバイスのローカルデプロイを一覧表示できるようにします。	`*`
`aws.greengrass#GetLocalDeploymentStatus`	コンポーネントがコアデバイスのローカルデプロイのステータスを取得できるようにします。	すべてのローカルデプロイへのアクセスを許可するローカルデプロイ ID または `*`。
`aws.greengrass#ListComponents`	コンポーネントがコアデバイスのコンポーネントを一覧表示できるようにします。	`*`
`aws.greengrass#GetComponentDetails`	コンポーネントがコアデバイスのコンポーネントの詳細を取得できるようにします。	すべてのコンポーネントへのアクセスを許可するコンポーネント名 (`com.example.HelloWorld` など) または `*`。
`aws.greengrass#RestartComponent`	コンポーネントがコアデバイスのコンポーネントを再起動できるようにします。	すべてのコンポーネントへのアクセスを許可するコンポーネント名 (`com.example.HelloWorld` など) または `*`。
`aws.greengrass#StopComponent`	コンポーネントがコアデバイスのコンポーネントを停止できるようにします。	すべてのコンポーネントへのアクセスを許可するコンポーネント名 (`com.example.HelloWorld` など) または `*`。
`aws.greengrass#CreateDebugPassword`	コンポーネントがローカルデバッグコンソールコンポーネントへのサインインに使用するパスワードを生成できるようにします。	`*`

例承認ポリシーの例

次の認証ポリシーの例では、コンポーネントがローカルデプロイを作成し、すべてのローカルデプロイとコンポーネントを表示し、com.example.HelloWorld という名前のコンポーネントを再起動および停止できるようにします。


{
  "accessControl": {
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:1": {
        "policyDescription": "Allows access to create local deployments and view deployments and components.",
        "operations": [
          "aws.greengrass#CreateLocalDeployment",
          "aws.greengrass#ListLocalDeployments",
          "aws.greengrass#GetLocalDeploymentStatus",
          "aws.greengrass#ListComponents",
          "aws.greengrass#GetComponentDetails"
        ],
        "resources": [
          "*"
        ]
      }
    },
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:2": {
        "policyDescription": "Allows access to restart and stop the Hello World component.",
        "operations": [
          "aws.greengrass#RestartComponent",
          "aws.greengrass#StopComponent"
        ],
        "resources": [
          "com.example.HelloWorld"
        ]
      }
    }
  }
}

CreateLocalDeployment

指定されたコンポーネントレシピ、アーティファクト、ランタイム引数を使用して、ローカルデプロイを作成または更新します。

このオペレーションは、Greengrass CLI のデプロイの create コマンドと同じ機能を提供します。

リクエスト

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

recipeDirectoryPath (Python: recipe_directory_path)

(オプション) コンポーネントレシピファイルを含むフォルダへの絶対パス。

artifactDirectoryPath (Python: artifact_directory_path)

(オプション) デプロイに含めるアーティファクトファイルを含むフォルダへの絶対パス。アーティファクトフォルダには、次のフォルダ構造が含まれている必要があります。


/path/to/artifact/folder/component-name/component-version/artifacts

rootComponentVersionsToAdd (Python: root_component_versions_to_add)

(オプション) コアデバイスにインストールするコンポーネントのバージョン。このオブジェクト ComponentToVersionMap は、次のキーと値のペアを含むマップです。

key: コンポーネントの名前。
value: コンポーネントのバージョン。

rootComponentsToRemove (Python: root_components_to_remove)

(オプション) コアデバイスからアンインストールするコンポーネント。各エントリがコンポーネントの名前となるリストを指定します。

componentToConfiguration (Python: component_to_configuration)

(オプション) デプロイ内の各コンポーネントの設定更新。このオブジェクト ComponentToConfiguration は、次のキーと値のペアを含むマップです。

key

コンポーネントの名前。

value

コンポーネントの設定更新の JSON オブジェクト。JSON オブジェクトは次の形式である必要があります。


{ 
  "MERGE": {
    "config-key": "config-value"
  },
  "RESET": [
    "path/to/reset/"
  ]
}

設定の更新の詳細については、「コンポーネント設定の更新」を参照してください。

componentToRunWithInfo (Python: component_to_run_with_info)

(オプション) デプロイ内の各コンポーネントのランタイム設定。この設定には、各コンポーネントのプロセスを所有するシステムユーザーと、各コンポーネントに適用するシステム制限が含まれます。このオブジェクト ComponentToRunWithInfo は、次のキーと値のペアを含むマップです。

key

コンポーネントの名前。

value

コンポーネントのランタイム設定。ランタイム設定のパラメータを省略した場合、AWS IoT Greengrass Core ソフトウェアは Greengrass nucleus で設定したデフォルト値を使用します。このオブジェクト (RunWithInfo) には、次の情報が含まれます。

posixUser (Python: posix_user)

(オプション) Linux コアデバイスでこのコンポーネントを実行する際に使用する POSIX システムユーザーおよびオプションのグループ。ユーザーまたはグループを指定する場合は、各 Linux コアデバイス上に存在している必要があります。ユーザーとグループを user:group の形式に従ってコロン (:) で区切って指定します。グループはオプションです。グループを指定しなかった場合、AWS IoT Greengrass Core ソフトウェアは、ユーザーのプライマリグループを使用します。詳細については、コンポーネントを実行するユーザーを設定するを参照してください。

windowsUser (Python: windows_user)

(オプション) Windows コアデバイスでこのコンポーネントを実行する際に使用する Windows ユーザー。ユーザーは各 Windows コアデバイスに存在し、その名前とパスワードは LocalSystem アカウントの認証情報マネージャーインスタンスに保存されている必要があります。詳細については、コンポーネントを実行するユーザーを設定するを参照してください。

systemResourceLimits (Python: system_resource_limits)

(オプション) このコンポーネントのプロセスに適用されるシステムリソースの制限。システムリソースの制限を、ジェネリックおよびコンテナ化されていない Lambda コンポーネントプロセスに適用することができます。詳細については、コンポーネントのシステムリソース制限を設定するを参照してください。

AWS IoT Greengrass は、現在 Windows コアデバイスにこの機能をサポートしていません。

このオブジェクト (SystemResourceLimits) には、次の情報が含まれます。

cpus: (オプション) このコンポーネントのプロセスがコアデバイスで使用できる CPU 時間の最大量。コアデバイスの合計 CPU 時間は、デバイスの CPU コア数と同じです。例えば、4 つの CPU コアを持つコアデバイスの場合は、この値を 2 に設定することで、このコンポーネントのプロセスを各 CPU コアの 50% の使用率に制限することができます。CPU コアが 1 つのデバイスの場合は、この値を 0.25 に設定することで、このコンポーネントのプロセスを CPU の 25% の使用率に制限することができます。この値を CPU コア数よりも大きい値に設定すると、AWS IoT Greengrass Core ソフトウェアは、コンポーネントの CPU 使用率に制限をかけません。
memory: (オプション) このコンポーネントのプロセスがコアデバイスで使用できる RAM の最大量 (キロバイト単位)。

groupName (Python: group_name)

(オプション) このデプロイでターゲットにするモノのグループの名前。

レスポンス

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

deploymentId (Python: deployment_id): リクエストによって作成されたローカルデプロイの ID。

ListLocalDeployments

過去 10 回分のローカルデプロイのステータスを取得します。

このオペレーションは、Greengrass CLI のデプロイの list コマンドと同じ機能を提供します。

リクエスト

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

レスポンス

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

localDeployments (Python: local_deployments)

ローカルデプロイのリスト。このリストの各オブジェクトは、次の情報が含まれる LocalDeployment オブジェクトです。

deploymentId (Python: deployment_id)

ローカルデプロイの ID。

status

ローカルデプロイのステータス。この列挙型 (DeploymentStatus) には以下の値があります。

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

GetLocalDeploymentStatus

ローカルデプロイのステータスを取得します。

このオペレーションは、Greengrass CLI のデプロイの status コマンドと同じ機能を提供します。

リクエスト

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

deploymentId (Python: deployment_id): 取得するローカルデプロイの ID。

レスポンス

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

deployment

ローカルデプロイ。このオブジェクト (LocalDeployment) には、次の情報が含まれます。

deploymentId (Python: deployment_id)

ローカルデプロイの ID。

status

ローカルデプロイのステータス。この列挙型 (DeploymentStatus) には以下の値があります。

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED

ListComponents

コアデバイスの各ルートコンポーネントの名前、バージョン、ステータス、および設定を取得します。ルートコンポーネントは、デプロイ時に指定するコンポーネントです。このレスポンスには、他のコンポーネントとの依存関係の中でインストールされるコンポーネントは含まれません。

このオペレーションは、Greengrass CLI のコンポーネントの list コマンドと同じ機能を提供します。

リクエスト

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

レスポンス

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

components

コアデバイスのルートコンポーネントのリスト。このリストの各オブジェクトは、次の情報が含まれる ComponentDetails オブジェクトです。

componentName (Python: component_name)

コンポーネントの名前。

version

コンポーネントのバージョン。

state

コンポーネントの状態。これは、次のいずれかの状態になります。

BROKEN
ERRORED
FINISHED
INSTALLED
NEW
RUNNING
STARTING
STOPPING

configuration

JSON オブジェクトとしてのコンポーネントの設定。

GetComponentDetails

コアデバイスのコンポーネントのバージョン、ステータス、および設定を取得します。

このオペレーションは、Greengrass CLI のコンポーネントの details コマンドと同じ機能を提供します。

リクエスト

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

componentName (Python: component_name): 取得するコンポーネントの名前。

レスポンス

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

componentDetails (Python: component_details)

コンポーネントの詳細。このオブジェクト (ComponentDetails) には、次の情報が含まれます。

componentName (Python: component_name)

コンポーネントの名前。

version

コンポーネントのバージョン。

state

コンポーネントの状態。これは、次のいずれかの状態になります。

BROKEN
ERRORED
FINISHED
INSTALLED
NEW
RUNNING
STARTING
STOPPING

configuration

JSON オブジェクトとしてのコンポーネントの設定。

RestartComponent

コアデバイスのコンポーネントを再起動します。

注記

どのコンポーネントでも再起動できますが、ジェネリックコンポーネントのみを再起動することをお勧めします。

このオペレーションは、Greengrass CLI のコンポーネントの restart コマンドと同じ機能を提供します。

リクエスト

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

componentName (Python: component_name): コンポーネントの名前。

レスポンス

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

restartStatus (Python: restart_status)

再起動リクエストのステータス。リクエストのステータスは次のいずれかになります。

SUCCEEDED
FAILED

message

リクエストが失敗した際の、コンポーネントが再起動に失敗した理由に関するメッセージ。

StopComponent

コアデバイスのコンポーネントのプロセスを停止します。

注記

どのコンポーネントも停止できますが、ジェネリックコンポーネントのみを停止することをお勧めします。

このオペレーションは、Greengrass CLI のコンポーネントの stop コマンドと同じ機能を提供します。

リクエスト

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

componentName (Python: component_name): コンポーネントの名前。

レスポンス

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

stopStatus (Python: stop_status)

停止リクエストのステータス。リクエストのステータスは次のいずれかになります。

SUCCEEDED
FAILED

message

リクエストが失敗した際の、コンポーネントが停止に失敗した理由に関するメッセージ。

CreateDebugPassword

ローカルデバッグコンソールコンポーネントへのサインインに使用できる、ランダムなパスワードを生成します。パスワードは、生成されてから 8 時間後に期限切れになります。

このオペレーションは、Greengrass CLI の get-debug-password コマンドと同じ機能を提供します。

リクエスト

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

レスポンス

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

username: サインインに使用するユーザー名。
password: サインインに使用するパスワード。
passwordExpiration (Python: password_expiration): パスワードの有効期限が切れる時刻。
certificateSHA256Hash (Python: certificate_sha256_hash): HTTPS が有効な場合にローカルデバッグコンソールが使用する自己署名証明書の SHA-256 フィンガープリント。ローカルデバッグコンソールを開く際に、このフィンガープリントを使用して、証明書が正当であり接続が安全であることを確認します。
certificateSHA1Hash (Python: certificate_sha1_hash): HTTPS が有効な場合にローカルデバッグコンソールが使用する自己署名証明書の SHA-1 フィンガープリント。ローカルデバッグコンソールを開く際に、このフィンガープリントを使用して、証明書が正当であり接続が安全であることを確認します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ローカルシャドウとやり取り

クライアントデバイスを認証して承認する

ローカルデプロイおよびコンポーネントの管理

注記

トピック

最小 SDK バージョン

認証

例 承認ポリシーの例

CreateLocalDeployment

リクエスト

レスポンス

ListLocalDeployments

リクエスト

レスポンス

GetLocalDeploymentStatus

リクエスト

レスポンス

ListComponents

リクエスト

レスポンス

GetComponentDetails

リクエスト

レスポンス

RestartComponent

注記

リクエスト

レスポンス

StopComponent

注記

リクエスト

レスポンス

CreateDebugPassword

リクエスト

レスポンス

例承認ポリシーの例