dfx canister
dfx canister コマンドとフラグおよびサブコマンドを使用して Canister の操作と {platform} またはローカルの Canister 実行環境との対話を管理します。
ほとんどの場合、プログラムをコンパイルした後に dfx canister サブコマンドを使用して Canister のライフサイクルを管理し、プログラムの関数を呼び出すなどの重要なタスクを実行します。
dfx canister コマンドを実行するための基本的な構文は以下の通りです：
dfx canister [subcommand] [flag]
指定する dfx canister サブコマンドによっては、追加の引数、オプション、およびフラグが適用され、または必要になる場合があります。
特定の dfx canister サブコマンドの使用情報を表示するにはそのサブコマンドと --help フラグを指定します。
例えば dfx canister call の利用情報を見るには以下のコマンドを実行します：
dfx canister call --help
dfx canister コマンドを使用する際の利用情報および例を参考にして、適切なコマンドを選択してください。
| コマンド | 説明 |
|---|---|
call | デプロイされた Canister で指定されたメソッドを呼び出します。 |
create | {platform} またはローカルの Canister 実行環境に Canister ID を登録することで、新しい「空」の Canister を作成します。 |
delete | 現在停止している Canister を削除します。 |
deposit-cycles | 指定された Canister に Cycle をデポジットします。 |
help | 指定されたサブコマンドの利用情報を表示します。 |
id | Canister ID を表示します。 |
info | Canister の WASM モジュールと現在のコントローラのハッシュを認証で取得する。 |
install | コンパイルされたコードを {platform} またはローカルの Canister 実行環境上に Canister としてインストールします。 |
request-status | Canister への呼び出しの状況をリクエストします。 |
send | 事前に署名された message.json を、指定された Canister ID に送信します。例えば、Neuron を管理するために Network Nervous System (NNS) のガバナンス Canister を呼び出すメッセージを送信したい場合、セキュリティ上の理由からメッセージの署名をメッセージから分離したいときに使用します。 |
sign | 指定された Canister の ID を呼び出す前に、署名付きの message.json ファイルを作成します。例えば、Neuron を管理するために Network Nervous System (NNS) のガバナンス Canister を呼び出すメッセージを送信する場合、セキュリティ上の理由からメッセージの署名をメッセージから分離したいときに使用します。 |
start | 停止している Canister をリスタートします。 |
status | Canister の動作状況をリクエストします。 |
stop | 現在動作中の Canister を停止します。 |
uninstall-code | Internet Computer ネットワーク上の Canister をアンインストールし、そのコードとステートを削除します。 |
update-settings | 1 つまたは複数の Canister の設定を更新します (コントローラ・計算量割り当て・メモリ割り当てなど。)。 |
デフォルトのデプロイ環境をオーバーライドする
デフォルトでは dfx canister コマンドは dfx.json ファイルで指定されたローカルの Canister 実行環境上で実行されます。
もし dfx.json 設定ファイルの設定を変更せずに dfx canister サブコマンドを {platform} やテストネットで実行したい場合、 --network オプションを用いて接続先 URL を明示的に指定することで可能になります。
例えば、ローカルの Canister 実行環境上でプロジェクトに一意の Canister ID を登録するには、以下のコマンドを実行します：
dfx canister create --all
同一プロジェクトに対して {platform} 上で一意の Canister ID を登録したい場合は、以下のコマンドを実行します：
dfx canister --network ic create --all
SDK には ic というエイリアスが付属しており、{platform} を指すように設定されます。また、ネットワークオプションとして URL を渡すこともできますし、dfx.json の networks 設定で、追加のエイリアスを設定することも可能です。
例として、以下のようなコマンドを使用して、テストネット上で動作している Canister と関数を呼び出すことができます。
dfx canister --network \http://192.168.3.1:5678 call counter get
Canister の操作（create または call）や、Canister 名（counter）や関数 （get）などの追加の引数の前に --network パラメータを指定しなければならないことに注意してください。
dfx canister call
デプロイされた Canister で指定されたメソッドを呼び出すには、 dfx canister call コマンドを使用します。
基本的な利用法
dfx canister call [option] canister_name _method_name_ [argument] [flag]
フラグ
dfx canister call コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
--async | ローカル Canister 実行環境、または {platform} をポーリングして、呼び出しの結果が返されるのを待たずに続行できるようにします。 |
-h, --help | 利用情報を表示します。 |
--query | デプロイされた Canister にクエリ・リクエストを送信できるようにします。 |
明示的にクエリ・メソッドを使用して効率よく情報を取得する場合に、このフラグを使用する必要があります。
クエリコールとアップデートコールの違いについては Canister はプログラムとステートを包含する を参照してください。|
|--update |デプロイされた Canister にアップデートリクエストを送信できるようにします。
デフォルトでは Canister の呼び出しは アップデートメソッドが使用されます。|
|-V, --version |バージョン情報を表示します。|
オプション
dfx canister call コマンドでは、以下のオプションを使用することができます。
| オプション | 説明 |
|---|---|
--output <output> | メソッドの戻り値を表示する際に使用する出力形式を指定します。有効な値は idl と raw です。 |
--type <type> | 引数を用いて呼び出しを行う場合の引数のデータ形式を指定します。有効な値は idl と raw です。 |
引数
dfx canister call コマンドでは、以下の引数を指定することができます。
| 引数 | 説明 |
|---|---|
canister_name | 呼び出す Canister の名前を指定します。Canister 名は必須の引数で dfx.json 設定ファイルの canisters セクションでプロジェクトに設定した名前と一致する必要があります。 |
method_name | Canister 内の呼び出すメソッド名を指定します。Canister メソッドは必須引数です。 |
argument | メソッドに渡す引数を指定します。プログラム・ロジックに応じて、引数は必須引数、またはオプション引数にすることができます。Canister に引数を渡す場合は --type オプションを使用してデータフォーマットのタイプを指定することができます。デフォルトでは、データ値に Candid (idl) 構文を使用して引数を指定します。Candid の使い方やサポートされている型についてはInteract with a service in a terminal とSupported types をご覧ください。Canister に生のバイトを渡したい場合は、引数の型として raw を使用することができます。 |
例
dfx canister call コマンドを使用すると dfx canister install コマンドを使用して Canister をデプロイした後に、引数付き、または引数なしで特定のメソッドを起動することができます。
例えば、canister_name が counter である Canister に対して get メソッドを呼び出すには、以下のコマンドを実行してください。
dfx canister call counter get --async
この例では、コマンドに --async オプションが含まれており、ローカルの Canister 実行環境や {platform} をポーリングして結果を待つのではなく、個別に request-status を呼び出したいことを表しています。
--async オプションはオペレーションを完了するまでに時間がかかる場合に便利です。
このオプションにより、他の操作を続けてながら別の dfx canister request-status コマンドを使用して結果を確認することができます。
返された結果は IDL のテキストフォーマットで表示されます。
IDL 構文を使用する
Text データ型に対して以下のようなコマンドを実行することで、IDL 構文で引数を渡すことを明示的に指定することができます：
dfx canister call hello greet --type idl '("Lisa")'
("Hello, Lisa!")
dfx canister call hello greet '("Lisa")' --type idl
("Hello, Lisa!")
また、以下のようなコマンドを実行することで IDL を暗黙的に利用することができます：
dfx canister call hello greet '("Lisa")'
("Hello, Lisa!")
IDL 構文で複数の引数を指定する場合は、引数の間にカンマ(,)を使用します。
例：
dfx canister call contacts insert '("Amy Lu","01 916-335-2042")'
dfx canister call hotel guestroom '("Deluxe Suite",42,true)'
以下のようなコマンドを実行することで、バイト単位の生データを渡すことができます：
dfx canister call hello greet --type raw '4449444c00017103e29883'
この例では、raw データ型を使って、hello Canister の greet 関数に 16 進数を渡しています。
dfx canister create
コンパイルされたコードなしにひとつ、または複数の Canister ID を登録するには、dfx canister create コマンドを使用します。
このコマンドを実行するには、ローカルの Canister 実行環境、または {platform} に接続されている必要があります。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
(Canister) ID を登録するため、初めて dfx canister create コマンドを実行すると、公開鍵と秘密鍵のペアの認証情報が default ユーザー（開発者） Identity に作成されます。
default ユーザー（開発者）の認証情報は $HOME/.dfinity/identity/creds.pem から $HOME/.config/dfx/identity/default/identity.pem へ移行されます。
基本的な利用法
dfx canister create [option] [flag] [--all | canister_name]
フラグ
dfx canister create コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
オプション
dfx canister create コマンドでは、以下のオプションを使用することができます。
| オプション | 説明 |
|---|---|
--with-cycles <number-of-cycles> | Canister を作成する際の初期 Cycle 数をウォレットで指定できるようになります。 |
引数
dfx canister create コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
--all | 複数の Canister を定義した dfx.json ファイルがプロジェクトにある場合、複数の Canister ID を一度に作成できるようにします。--all または、個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | (Canister) ID を登録する Canister の名前を指定します。--all オプションを使用しない場合、Canister 名は必須の引数であり、プロジェクトの dfx.json 設定ファイルの canisters セクションで設定した名前と少なくとも 1 つは一致しなければなりません。 |
例
dfx canister create コマンドを使用すると、最初にコードをコンパイルすることなく、Canister ID を登録することができます。
例えば、プログラムを書く前にプロジェクト my_counter の Canister ID を作成したい場合、以下のコマンドを実行します：
dfx canister create my_counter
dfx canister create コマンドに --with-cycles オプションを付けて使用すると、プロジェクト内の 1 つまたはすべての Canister の作成時に初期残高を指定することができます。例えば、すべての Canister の初期残高を 8000000000000 Cycle に指定するには、次のコマンドを実行します。
dfx canister create --with-cycles 8000000000000 --all
dfx canister delete
停止した Canister をローカルの Canister 実行環境または {platform} から削除するには、dfx canister delete コマンドを使用します。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
基本的な利用法
dfx canister delete [flag] [--all | canister_name]
フラグ
dfx canister delete コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister delete コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
--all | dfx.json ファイルに設定されているすべての Canister を削除します。--all または、個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | 削除する Canister の名前を指定します。Canister 名、または --all オプションのいずれかを指定する必要があることに注意してください。 |
例
dfx canister delete コマンドを使うと、特定の Canister またはすべての Canister を削除することができます。
hello_world の Canister を削除するには、以下のコマンドを実行します：
dfx canister delete hello_world
IC {platform} にデプロイしたすべての Canister を削除するには、次のコマンドを実行します：
dfx canister --network=ic delete --all
dfx canister deposit-cycles
Use the dfx canister deposit-cycles command to deposit cycles from your configured wallet into a canister.
Note that you must have your cycles wallet configured for this to work.
Basic usage
dfx canister deposit-cycles [amount of cycles] [--all | canister_name]
Flags
You can use the following optional flags with the dfx canister deposit-cycles command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Arguments
You can use the following arguments with the dfx canister deposit-cycles command.
| Argument | Description |
|---|---|
--all | Deposits the specified amount of cycles into all canisters configured in dfx.json. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to deposit cycles into. Note that you must specify either a canister name or the --all option. |
Examples
You can use the dfx canister deposit-cycles command to add cycles to a specific canister or all canisters.
To add 1T cycles to the canister called hello, you can run the following command:
dfx canister deposit-cycles 1000000000000 hello
To add 2T cycles to each individual canister specified in dfx.json, you can run the following command:
dfx canister deposit-cycles 2000000000000 --all
dfx canister id
特定の Canister 名の Canister ID を出力するには、dfx canister id コマンドを使用します。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
基本的な利用法
dfx canister id [flag] canister_name
フラグ
dfx canister id コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister id コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
canister_name | (Canister) ID を表示する Canister の名前を指定します。 |
例
特定の Canister 名の Canister ID を表示するには、dfx canister id コマンドを使用することができます。
hello_world Canister の Canister ID を表示するには、次のコマンドを実行します。
dfx canister id hello_world
このコマンドは次のような出力を表示します：
75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
dfx canister install
コンパイルされたコードを {platform} またはローカルの Canister 実行環境にインストールするには dfx canister install コマンドを使用します。
基本的な利用法
dfx canister install [flag] [option] [--all | canister_name]
フラグ
dfx canister install コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
--async | {platform} またはローカルの Canister 実行環境をポーリングして、インストールの結果が返されるのを待たずに続行できるようにします。 |
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
オプション
dfx canister install コマンドでは、以下のオプションを使用することができます。
| オプション | 説明 |
|---|---|
--argument <argument> | インストール時に Canister に渡す引数を指定します。 |
--argument-type <argument-type> | --argument オプションを使用してインストールする際に、引数のデータフォーマットを指定します。有効な値は idl と raw です。デフォルトでは、データ値に Candid (idl) 構文を使用して引数を指定します。Candid の使い方やサポートされている型については、Interact with a service in a terminal とSupported types を見てみてください。Canister に生バイナリデータを渡したい場合は、引数の型として raw を使用することができます。 |
-c, --compute-allocation <compute-allocation> | Canister 実行のための計算割り当て（実質的に CPU 割り当ての設定に相当）を定義します。この値は 0 ～ 100 の範囲でパーセンテージとして設定できます。 |
--memory-allocation <memory-allocation> | Canister で使用できる総メモリ数を指定します。この値は 0 ～ 8 MB の範囲で設定できます。 |
-m, --mode <mode> | Canister を install, reinstall, または upgrade のいずれでインストールするかを指定します。インストールモードと Canister 管理の詳細については、Canister を管理する を参照してください。 |
引数
dfx canister install コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
--all | プロジェクトの dfx.json ファイルに複数の Canister が含まれている場合、複数の Canister を一度にインストールできるようにします。--all または個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | デプロイする Canister の名前を指定します。 |
dfx.json 設定ファイルの canisters セクションでプロジェクトに設定した名前と一致する必要があります。 |
例
dfx canister install コマンドを使用すると、dfx build コマンドでコンパイルした WebAssembly を {platform} またはローカルの Canister 実行環境上にデプロイすることができます。
最も一般的な使用方法は、以下のコマンドを実行してすべての Canister をインストールすることです：
dfx canister install --all
特定の Canister をインストールする
また、dfx canister install コマンドを使用すると、プロジェクト内のすべての Canister ではなく、特定の Canister をデプロイすることができます。
例えば、hello_world Canister と hello_world_assets Canister を持つプロジェクトで、 hello_world Canister だけをデプロイしたい場合、以下のコマンドを実行してその Canister だけをデプロイすることが可能です：
dfx canister install hello_world
非同期リクエストを送信する
Canister のインストールのリクエストを行い、そのリクエストの識別子を返すことで、コマンドの完了を待つのではなく後でリクエストの状況を確認したい場合には、次のようなコマンドを実行します：
dfx canister install hello_world --async
このコマンドは Canister をインストールするリクエストを送信し、次のようなリクエスト識別子を返します：
0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608
リクエスト識別子を使用して、後でリクエストのステータスを確認することができます。これは荷物を発送するときの追跡番号のようなものです。
デフォルトのデプロイオプションを上書きする
もし、dfx.json 設定ファイルの設定を変更せずに、テストネット上に Canister をデプロイしたい場合は、--network オプションを使って接続するテストネットを明示的に指定することができます。
例えば、以下のようなコマンドを実行することで、テストネットの URL を指定することができます：
dfx canister --network \http://192.168.3.1:5678 install --all
ネットワークのパラメータは Canister オペレーション (install) の前に、かつ Canister 名または --all フラグの前に指定する必要があることに注意してください。
メッセージ処理のアロケーション
compute-allocation オプションでは、0 から 100 の範囲で計算資源をパーセンテージで割り当て、Canister の実行をどの程度の頻度でスケジュールするかを指定できます。
例えば、以下のようなコマンドを実行したとします：
dfx canister install --all --compute-allocation 50
この設定では、現在のプロジェクト内のすべての Canister に 50% の割り当てが行われます。プロジェクト内の Canister が処理する入力メッセージを受信すると、そのメッセージは実行のためにスケジュールされます。 100 回の実行サイクルの間に、各 Canister のメッセージは少なくとも 50 回処理されるようスケジュールされます。
このオプションの既定値は 0 で、特定の割り当てやスケジューリングが有効でないことを示します。 すべての Canister が既定の設定を使用する場合、処理はラウンドロビン方式で行われます。
dfx canister request-status
dfx canister request-status コマンドでは、Canister への指定された呼び出しのステータスをリクエストすることができます。
このコマンドでは Canister のメソッドを呼び出した後に受け取ったリクエストの識別子を指定する必要があります。
リクエストの識別子は 0x で始まる 16 進数の文字列です。
基本的な利用法
dfx canister request-status request_id
フラグ
dfx canister request-status コマンドでは、以下のオプションフラグを 使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister request-status コマンドには、以下の引数を指定できます。
| 引数 | 説明 |
|---|---|
request_id | dfx canister call または dfx canister install コマンドのレスポンスとして返される 16 進数の文字列を指定します。この識別子は 0x で始まる 16 進数の文字列です。 |
例
dfx canister request-status コマンドを使用して、Canister のステータス変更の状況を確認したり、次のようなコマンドを実行して、呼び出しが拒否されなかったことを確認することができます：
dfx canister request-status 0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608
このコマンドはリクエスト識別子が無効であるか、Canister によって拒否された場合、エラーメッセージを表示します。
dfx canister set-controller
dfx canister set-controller コマンドでは、{platform} 上の指定された Canister の新しい コントローラー として Identity 名 または Principal を指定することができます。
コントローラーは制御対象の Canister を管理する特別な権限を持ちます。
例えば、コントローラー（の Identity ）だけがその制御下にある Canister のインストール、アップグレード、または削除をすることができます。
コントローラーとして、ユーザー（開発者）Identity または Canister のいずれかを指定できることに注意してください。 また、コントローラーは（ Identity の）名前、または Principal を使用して指定することもできます。
基本的な利用法
dfx canister set-controller [flag] canister new-controller
フラグ
dfx canister set-controller コマンドでは、以下のオプションフラグを 使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister set-controller コマンドでは、以下の引数を使用する必要があります。
| 引数 | 説明 |
|---|---|
<canister> | new_controller 引数で指定したコントローラー（の ID ）が制御する対象である Canister 名、または Canister ID を指定します。 |
<new_controller> | （新規）コントローラーの Identity 名または Principal を指定します。 |
例
dfx canister set-controller コマンドを使用すると、特定の Canister を制御する コントローラーとして、（ユーザー）identity、または Canister を指定することができます。
例えば、dfx canister set-controller を実行して新しい Identity pubsadmin を作成し hello_world Canister のコントローラーとして指定するには、以下のコマンドを実行するとよいでしょう。
dfx identity new pubsadmin
dfx canister set-controller hello_world pubsadmin
Principal ID のテキスト表現を使用してコントローラーを設定するには、次のようなコマンドを実行します。
dfx canister set-controller hello_world wcp5u-pietp-k5jz4-sdaaz-g3x4l-zjzxa-lxnly-fp2mk-j3j77-25qat-pqe
Identity 名や Principal を指定するのも 1 つの使用例ですが、より一般的なシナリオは Cycle を送信するために使用するウォレット Canister を指定することです。
次の手順はローカル開発をしている場合のこのシナリオを説明するものです。この例では、 open_sf というプロジェクトを作成し、2 つの Canister をローカルの Canister 実行環境上にデプロイしたと仮定します。
コントローラーとして動作するように
sf-controllerという名前の Identity を作成します。dfx identity new sf-controller
Creating identity: "sf-controller".
Created identity: "sf-controller".新しい Identity をアクティブ Identity にします。
dfx identity use sf-controller
Using identity: "sf-controller".新しい Identity のウォレット Canister ID を生成します。
dfx identity get-wallet
Creating a wallet canister on the local canister execution environment.
r7inp-6aaaa-aaaaa-aaabq-cai
The wallet canister on the the local canister execution environment for user "sf-controller" is "r7inp-6aaaa-aaaaa-aaabq-cai"アクティブ Identity を Canister の現在のコントローラーに切り替えます。例えば、Canister の作成に default の Identity が使用された場合、以下のコマンドを実行します。
dfx identity use default
Using identity: "default".指定された Canister のコントローラーにウォレットを使用するようにした sf-controller Identity に設定します。
dfx canister set-controller open_sf_assets r7inp-6aaaa-aaaaa-aaabq-cai
Set "r7inp-6aaaa-aaaaa-aaabq-cai" as controller of "open_sf_assets".これで、ウォレット Canister
r7inp-6aaaa-aaabq-caiを使って Cycle を送ったり、open_sf_assetsCanister にカストディアンを追加することができるようになります。
dfx canister send
dfx canister call コマンドを使うのではなく、 dfx canister sign コマンドでメッセージに署名をした後に dfx canister send コマンドを使うことで、これらのステップを分離させることができます。別々の呼び出しを使うことで、トランザクションにセキュリティを加えることが可能です。
例えば、Neuron のステーキングを作成するときに dfx canister sign コマンドを使用して、エアギャップされたコンピュータを使用して署名済みの message.json ファイルを作成し、次に dfx canister send コマンドを使用して署名済みのメッセージを配信することができます。
基本的な利用法
dfx canister send file_name
フラグ
dfx canister request-status コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister send コマンドには、以下の引数を指定することができます。
| 引数 | 説明 | |
|---|---|---|
file_name | メッセージのファイル名を指定します。 |
例
dfx canister send コマンドを使用して作成した署名付きメッセージを genesis token canister (GTC) に送信し、以下のコマンドを実行することであなたに代わって Neuron を作成します：
dfx canister send message.json
dfx canister sign
dfx canister call コマンドを一度に使うのではなく、 dfx canister send コマンドでメッセージを送信する前に dfx canister sign コマンドを使うことで、これらのステップを分離することができます。別々の呼び出しを使うことで、トランザクションにセキュリティを加えることが可能です。
例えば、Neuron ステーキングを作成する際に dfx canister sign コマンドを使用して、エアギャップされたコンピュータを使用して署名された message.json ファイルを作成し、dfx canister send コマンドを使用して {platform} に接続されているコンピュータから署名されたメッセージを配信することが考えられます。
基本的な利用法
dfx canister sign [flag] [option] _canister-name_ _method-name_ [argument]
フラグ
dfx canister sign コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
--query | Canister にクエリ・リクエストを送信します。 |
--update | Canister にアップデート・リクエストを送信します。これは --query メソッドが使用されない場合のデフォルト・メソッドです。 |
-V, --version | バージョン情報を表示します。 |
オプション
dfx canister sign コマンドには、以下のオプションを指定することができます。
| Option | Description |
|---|---|
--expire-after <seconds> | 有効期限が切れて送信できなくなるまでの時間を指定します。秒単位で指定します。未定義の場合、デフォルトは 300 秒（5 分）です。 |
--file <output> | 出力ファイル名を指定します。デフォルトは message.json です。 |
--random <random> | ランダムな引数を生成するための設定を指定します。 |
--type <type> | S 引数を用いた呼び出しを行う際に、引数のデータ型を指定します。 idl と raw を指定可能です。 |
引数
dfx canister sign コマンドには、以下の引数を指定することができます。
| 引数 | 説明 |
|---|---|
canister_name | 呼び出す Canister の名前を指定します。Canister 名は必須の引数で dfx.json 設定ファイルの canisters セクションでプロジェクトに対して設定した名前と一致する必要があります。 |
method_name | Canister で呼び出すメソッド名を指定します。Canister のメソッドは必須引数です。 |
argument | メソッドに渡す引数を指定します。プログラム・ロジックに応じて、引数は必須引数またはオプション引数にすることができます。Canister に引数を渡す場合は --type オプションを使用してデータフォーマットのタイプを指定することができます。デフォルトでは、データ値に Candid (idl) 構文を使って引数を指定することができます。Candid の使い方やサポートされている型については Interact with a service in a terminal とSupported types を見てみてください。生バイナリ（データ）を渡したい場合は、引数の型として raw を指定することができます。 |
例
dfx canister sign コマンドを使用して、以下のようなコマンドを Privacy Enhanced Mail (PEM) ファイルを使用して作成した Identity に関連付けられた Principal を使用して実行し、署名付き message.json ファイルを作成します：
dfx canister --network=ic sign --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’
このコマンドでは、署名された message.json ファイルを作成する方法を説明します。
このコマンドは message.json ファイルを作成して、ic エイリアスで指定した {platform} 上に Neuron を作成する方法を示しています。このファイルはメッセージの送信者としてあなたの Principal ID を使い、1 時間で終了する有効期限を設定して署名されています。
署名されたメッセージの送信に割り当てられる時間は 5 分という固定されたウィンドウであることに注意してください。expire-after オプションは署名されたメッセージを送るための 5 分のウィンドウを終了させる時点を指定することができます。例えば、--expire-after オプションを 1 時間（1h）に設定すると、生成されたメ ッセージを送る前に少なくとも 55 分待たなければならず、メッセージの署名は 60 分で終わる 5 分間のウィンドウの間だけ有効になります。
したがって、この例では、55 分後にメッセージを送信し、60 分前にメッセージを送信しないと、メッセージが有効であると認識されません。
もし、--expire-after オプションを指定しなければ、デフォルトの有効期限は 5 分です。
以下のコマンドを実行して、署名されたメッセージを genesis token canister (GTC) に送信し、あなたの代わりに Neuron を作成します：
dfx canister send message.json
dfx canister start
dfx canister start コマンドを使用すると、{platform} または、ローカルの Canister 実行環境上で停止している Canister を再起動できます。
ほとんどの場合、Canister のアップグレードの前提条件に保留中のリクエストを適切に中断するために Canister を停止した後、このコマンドを実行します。
このコマンドは、プロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world トップレベルのプロジェクトディレクトリか、そのサブディレクトリのいずれかである必要があります。
基本的な利用法
dfx canister start [flag] [--all | canister_name]
フラグ
dfx canister start コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister start コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
--all | dfx.json ファイルで設定されているすべての Canister を起動します。--all または、個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | 起動する canister の名前を指定します。Canister 名、または --all オプションのいずれかを指定する必要があることに注意してください。 |
例
dfx canister start コマンドを使用すると、特定の Canister またはすべての Canister を起動することができます。
hello_world Canister を起動するためには、以下のコマンドを実行します。
dfx canister start hello_world
{platform} 上にデプロイした全ての Canister を起動するには、以下のコマンドを実行します。
dfx canister --network=ic start --all
dfx canister status
dfx canister status コマンドでは、{platform} またはローカルの Canister 実行環境において Canister が現在実行中か、停止中か、または現在停止しているかを確認できます。
このコマンドは、プロジェクト・ディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
基本的な利用法
dfx canister status [flag] [--all | canister_name]
フラグ
dfx canister status コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister status コマンドでは、以下の引数を使用できます。
| 引数 | 説明 |
|---|---|
--all | dfx.json ファイルに設定されているすべての Canister のステータス情報を返します。--all または個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | データを返したい Canister の名前を指定します。Canister 名、または --all オプションのいずれかを指定する必要があることに注意してください。 |
例
dfx canister status コマンドを使用することで、特定の Canister または全ての Canister のステータスを確認することができます。
hello_world Canister のステータスを確認するには、以下のコマンドを実行します。
dfx canister status hello_world
{platform} にデプロイしたすべての Canister のステータスを確認するには、次のコマンドを実行します。
dfx canister --network=ic status --all
dfx canister stop
dfx canister stop コマンドでは、{platform} またはローカルの Canister 実行環境上で現在実行中の Canister を停止できます。
ほとんどの場合、Canister をアップグレードする前提条件に、保留中のリクエストを適切に中断させるためにこのコマンドを実行します。
このコマンドは、プロジェクト・ディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world の場合、現在の作業ディレクトリは hello_world トップレベルのプロジェクトディレクトリか、そのサブディレクトリのいずれかである必要があります。
基本的な利用法
dfx canister stop [flag] [--all | canister_name]
フラグ
dfx canister stop コマンドでは、以下のオプションフラグを使用することができます。
| フラグ | 説明 |
|---|---|
-h, --help | 利用情報を表示します。 |
-V, --version | バージョン情報を表示します。 |
引数
dfx canister stop コマンドでは、以下の引数を使用することができます。
| 引数 | 説明 |
|---|---|
--all | dfx.json ファイルで設定されているすべての Canister を停止します。--all または、個々の Canister 名を指定する必要があることに注意してください。 |
canister_name | 停止したい Canister の名前を指定します。Canister 名または --all オプションのいずれかを指定する必要があることに注意してください。 |
例
dfx canister stop コマンドを使用することで、特定の Canister またはすべての Canister を停止することができます。
hello_world Canister を停止させるには、以下のコマンドを実行します：
dfx canister stop hello_world
{platform} にデプロイしたすべての Canister を停止するには、次のコマンドを実行します：
dfx canister --network=ic stop --all