dfx canister
dfx canister
コマンドとフラグおよびサブコマンドを使用して Canister の操作と Internet Computer プラットフォーム またはローカルの Canister 実行環境との対話を管理します。
ほとんどの場合、プログラムをコンパイルした後に dfx canister
サブコマンドを使用して Canister のライフサイクルを管理し、プログラムの関数を呼び出すなどの重要なタスクを実行します。
dfx canister
コマンドを実行するための基本的な構文は以下の通りです:
dfx canister [subcommand] [flag]
指定する dfx canister
サブコマンドによっては、追加の引数、オプション、およびフラグが適用され、または必要になる場合があります。
特定の dfx canister
サブコマンドの使用情報を表示するにはそのサブコマンドと --help
フラグを指定します。
例えば dfx canister call
の利用情報を見るには以下のコマンドを実行します:
dfx canister call --help
dfx canister
コマンドを使用する際の利用情報および例を参考にして、適切なコマンドを選択してください。
コマンド | 説明 |
---|---|
デプロイされた Canister で指定されたメソッドを呼び出します。 |
|
Internet Computer プラットフォーム またはローカルの Canister 実行環境に Canister ID を登録することで、新しい「空」の Canister を作成します。 |
|
現在停止している Canister を削除します。 |
|
|
指定されたサブコマンドの利用情報を表示します。 |
Canister ID を表示します。 |
|
コンパイルされたコードを Internet Computer プラットフォーム またはローカルの Canister 実行環境上に Canister としてインストールします。 |
|
Canister への呼び出しの状況をリクエストします。 |
|
Internet Computer プラットフォーム 上の指定された Canister の新しいコントローラーとして使用する ユーザー(開発者)Identity 名または Principal を指定します。 |
|
事前に署名された |
|
指定された Canister の ID を呼び出す前に、署名付きの |
|
停止している Canister をリスタートします。 |
|
Canister の動作状況をリクエストします。 |
|
現在動作中の Canister を停止します。 |
デフォルトのデプロイ環境をオーバーライドする
デフォルトでは dfx canister
コマンドは dfx.json
ファイルで指定されたローカルの Canister 実行環境上で実行されます。
もし dfx.json
設定ファイルの設定を変更せずに dfx canister
サブコマンドを Internet Computer プラットフォーム やテストネットで実行したい場合、 --network
オプションを用いて接続先 URL を明示的に指定することで可能になります。
例えば、ローカルの Canister 実行環境上でプロジェクトに一意の Canister ID を登録するには、以下のコマンドを実行します:
dfx canister create --all
同一プロジェクトに対して Internet Computer プラットフォーム 上で一意の Canister ID を登録したい場合は、以下のコマンドを実行します:
dfx canister --network ic create --all
DFINITY Canister SDK には ic
というエイリアスが付属しており、Internet Computer プラットフォーム を指すように設定されます。また、ネットワークオプションとして 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
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
ローカル Canister 実行環境、または Internet Computer プラットフォーム をポーリングして、呼び出しの結果が返されるのを待たずに続行できるようにします。 |
|
利用情報を表示します。 |
|
デプロイされた Canister にクエリ・リクエストを送信できるようにします。 明示的にクエリ・メソッドを使用して効率よく情報を取得する場合に、このフラグを使用する必要があります。 クエリコールとアップデートコールの違いについては Canister はプログラムとステートを包含するを参照してください。 |
|
デプロイされた Canister にアップデートリクエストを送信できるようにします。 デフォルトでは Canister の呼び出しは アップデートメソッドが使用されます。 |
|
バージョン情報を表示します。 |
オプション
dfx canister call
コマンドでは、以下のオプションを使用することができます。
オプション | 説明 |
---|---|
|
メソッドの戻り値を表示する際に使用する出力形式を指定します。 有効な値は |
|
引数を用いて呼び出しを行う場合の引数のデータ形式を指定します。 有効な値は |
|
レスポンスの形式を記述した candid (.did) ファイルへのパスを指定します。 これはプロジェクトの一部でない Canister を呼び出すときに便利です。 |
引数
dfx canister call
コマンドでは、以下の引数を指定することができます。
引数 | 説明 |
---|---|
|
呼び出す Canister の名前を指定します。Canister 名は必須の引数で |
|
Canister 内の呼び出すメソッド名を指定します。 Canister メソッドは必須引数です。 |
|
メソッドに渡す引数を指定します。
プログラム・ロジックに応じて、引数は必須引数、またはオプション引数にすることができます。
Canister に引数を渡す場合は |
例
dfx canister call
コマンドを使用すると dfx canister install
コマンドを使用して Canister をデプロイした後に、引数付き、または引数なしで特定のメソッドを起動することができます。
例えば、canister_name
が counter
である Canister に対して get
メソッドを呼び出すには、以下のコマンドを実行してください。
dfx canister call counter get --async
この例では、コマンドに --async
オプションが含まれており、ローカルの Canister 実行環境や Internet Computer プラットフォーム をポーリングして結果を待つのではなく、個別に 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 実行環境、または Internet Computer プラットフォーム に接続されている必要があります。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が 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
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
オプション
dfx canister create
コマンドでは、以下のオプションを使用することができます。
オプション | 説明 |
---|---|
|
Canister を作成する際の初期 Cycle 数をウォレットで指定できるようになります。 |
引数
dfx canister create
コマンドでは、以下の引数を使用することができます。
引数 | 説明 |
---|---|
|
複数の Canister を定義した |
|
(Canister) ID を登録する Canister の名前を指定します。
|
例
dfx canister create
コマンドを使用すると、最初にコードをコンパイルすることなく、Canister ID を登録することができます。
例えば、プログラムを書く前にプロジェクト my_counter
の Canister ID を作成したい場合、以下のコマンドを実行します:
dfx canister create my_counter
dfx canister create
コマンドに --with-cycles
オプションを付けて使用すると、プロジェクト内の 1 つまたはすべての Canister の作成時に初期残高を指定することができます。例えば、すべての Canister の初期残高を 8,000,000,000,000 Cycle に指定するには、次のコマンドを実行します。
dfx canister create --with-cycles 8000000000000 --all
dfx canister delete
停止した Canister をローカルの Canister 実行環境または Internet Computer プラットフォーム から削除するには、dfx canister delete
コマンドを使用します。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world
の場合、現在の作業ディレクトリは hello_world
のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
フラグ
dfx canister delete
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
dfx canister id
特定の Canister 名の Canister ID を出力するには、dfx canister id
コマンドを使用します。
このコマンドはプロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world
の場合、現在の作業ディレクトリは hello_world
のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
フラグ
dfx canister id
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
dfx canister install
コンパイルされたコードを Internet Computer プラットフォーム またはローカルの Canister 実行環境にインストールするには dfx canister install
コマンドを使用します。
フラグ
dfx canister install
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
Internet Computer プラットフォーム またはローカルの Canister 実行環境をポーリングして、インストールの結果が返されるのを待たずに続行できるようにします。 |
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
オプション
dfx canister install
コマンドでは、以下のオプションを使用することができます。
オプション | 説明 |
---|---|
|
インストール時に Canister に渡す引数を指定します。 |
|
|
|
Canister 実行のための計算割り当て(実質的に CPU 割り当ての設定に相当)を定義します。 この値は 0 ~ 100 の範囲でパーセンテージとして設定できます。 |
|
Canister で使用できる総メモリ数を指定します。 この値は 0 ~ 8 MB の範囲で設定できます。 |
|
Canister を |
引数
dfx canister install
コマンドでは、以下の引数を使用することができます。
引数 | 説明 |
---|---|
|
プロジェクトの |
|
デプロイする Canister の名前を指定します。
|
例
dfx canister install
コマンドを使用すると、dfx build
コマンドでコンパイルした WebAssembly を Internet Computer プラットフォーム またはローカルの 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
コマンドでは、以下のオプションフラグを 使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
dfx canister set-controller
dfx canister set-controller
コマンドでは、Internet Computer プラットフォーム 上の指定された Canister の新しい コントローラー として Identity 名([訳者追加]参考: dfx-identity )または Principal を指定することができます。
コントローラーは制御対象の Canister を管理する特別な権限を持ちます。
例えば、コントローラー(の Identity )だけがその制御下にある Canister のインストール、アップグレード、または削除をすることができます。
コントローラーとして、ユーザー(開発者)Identity または Canister のいずれかを指定できることに注意してください。 また、コントローラーは( Identity の)名前、または Principal を使用して指定することもできます。
フラグ
dfx canister set-controller
コマンドでは、以下のオプションフラグを 使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
引数
dfx canister set-controller
コマンドでは、以下の引数を使用する必要があります。
引数 | 説明 |
---|---|
|
new_controller 引数で指定したコントローラー(の ID )が制御する対象である Canister 名、または Canister ID を指定します。 |
|
(新規)コントローラーの 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_assets
Canister にカストディアンを追加することができるようになります。
dfx canister send
dfx canister call
コマンドを使うのではなく、 dfx canister sign
コマンドでメッセージに署名をした後に dfx canister send
コマンドを使うことで、これらのステップを分離させることができます。別々の呼び出しを使うことで、トランザクションにセキュリティを加えることが可能です。
例えば、Neuron のステーキングを作成するときに dfx canister sign
コマンドを使用して、エアギャップされたコンピュータを使用して署名済みの message.json
ファイルを作成し、次に dfx canister send
コマンドを使用して署名済みのメッセージを配信することができます。
dfx canister sign
dfx canister call
コマンドを一度に使うのではなく、 dfx canister send
コマンドでメッセージを送信する前に dfx canister sign
コマンドを使うことで、これらのステップを分離することができます。別々の呼び出しを使うことで、トランザクションにセキュリティを加えることが可能です。
例えば、Neuron ステーキングを作成する際に dfx canister sign
コマンドを使用して、エアギャップされたコンピュータを使用して署名された message.json
ファイルを作成し、dfx canister send
コマンドを使用して Internet Computer プラットフォーム に接続されているコンピュータから署名されたメッセージを配信することが考えられます。
フラグ
dfx canister sign
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
Canister にクエリ・リクエストを送信します。 |
|
Canister にアップデート・リクエストを送信します。これは |
|
バージョン情報を表示します。 |
オプション
dfx canister sign
コマンドには、以下のオプションを指定することができます。
オプション | 説明 |
---|---|
|
有効期限が切れて送信できなくなるまでの時間を指定します。秒単位で指定します。未定義の場合、デフォルトは300秒(5分)です。 |
|
出力ファイル名を指定します。デフォルトは |
|
ランダムな引数を生成するための設定を指定します。 |
|
引数を用いた呼び出しを行う際に、引数のデータ型を指定します。 デフォルトでは、データ値に対して Candid ( |
引数
dfx canister sign
コマンドには、以下の引数を指定することができます。
引数 | 説明 |
---|---|
|
呼び出す Canister の名前を指定します。Canister 名は必須の引数で |
|
Canister で呼び出すメソッド名を指定します。 Canister のメソッドは必須引数です。 |
|
メソッドに渡す引数を指定します。
プログラム・ロジックに応じて、引数は必須引数またはオプション引数にすることができます。
Canister に引数を渡す場合は |
例
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
エイリアスで指定した Internet Computer プラットフォーム 上に 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
コマンドを使用すると、Internet Computer プラットフォーム または、ローカルの Canister 実行環境上で停止している Canister を再起動できます。
ほとんどの場合、Canister のアップグレードの前提条件に保留中のリクエストを適切に中断するために Canister を停止した後、このコマンドを実行します。
このコマンドは、プロジェクトのディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world
の場合、現在の作業ディレクトリは hello_world
トップレベルのプロジェクトディレクトリか、そのサブディレクトリのいずれかである必要があります。
フラグ
dfx canister start
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
dfx canister status
dfx canister status
コマンドでは、Internet Computer プラットフォーム またはローカルの Canister 実行環境において Canister が現在実行中か、停止中か、または現在停止しているかを確認できます。
このコマンドは、プロジェクト・ディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world
の場合、現在の作業ディレクトリは hello_world
のトップレベルのプロジェクトディレクトリかそのサブディレクトリのいずれかである必要があります。
フラグ
dfx canister status
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |
dfx canister stop
dfx canister stop
コマンドでは、Internet Computer プラットフォーム またはローカルの Canister 実行環境上で現在実行中の Canister を停止できます。
ほとんどの場合、Canister をアップグレードする前提条件に、保留中のリクエストを適切に中断させるためにこのコマンドを実行します。
このコマンドは、プロジェクト・ディレクトリ構造内からのみ実行できることに注意してください。
例えば、プロジェクト名が hello_world
の場合、現在の作業ディレクトリは hello_world
トップレベルのプロジェクトディレクトリか、そのサブディレクトリのいずれかである必要があります。
フラグ
dfx canister stop
コマンドでは、以下のオプションフラグを使用することができます。
フラグ | 説明 |
---|---|
|
利用情報を表示します。 |
|
バージョン情報を表示します。 |