ライブラリモジュールのインポート

このチュートリアルでは、電話番号の保存と検索を可能にする簡単な Dapp を作成します。このチュートリアルでは、いくつかの基本的な Motoko ライブラリ関数をインポートして使用する方法を説明します。

このチュートリアルでは、Motoko の基本ライブラリ関数は List と AssocList モジュールで定義されており、リンクされたキーとバリューのペアでリストを操作できるようにします。この例では、key は name で、value はその名前に関連付けられた phone というテキスト文字列です。

この Dapp は以下の関数コールをサポートしています：

• insert 関数は、変数 book に格納された name と phone のキーとバリューのペアを入力として受け取ります。

• lookup 関数は、指定された name キーを入力として、関連する電話番号を検索するクエリです。

始める前に

チュートリアルを始める前に、以下を確認してください：

• ダウンロードとインストールで説明されているように、SDK パッケージをダウンロードしインストールする。

• dfxが提供するローカル Canister の実行環境を停止する。

このチュートリアルの所要時間は約 10分です。

新しいプロジェクトを作成する

このチュートリアルのための新しいプロジェクトを作成するには：

1. ローカルコンピューターでターミナルシェルを開いてください（まだ開いていない場合）。

2. Internet Computer のプロジェクトに使用しているフォルダがあれば、そこに移動します。

3. 以下のコマンドを実行して、新しいプロジェクトを作成します：

   dfx new phonebook

4. 以下のコマンドを実行して、プロジェクトディレクトリに移動してください：

   cd phonebook

デフォルトの Dapp を修正する

このチュートリアルでは、シンプルな電話番号検索 Dapp 用に新しい main.mo ファイルを作成しましょう。

デフォルトのテンプレートを変更するには：

1. テキストエディタで src/phonebook/main.mo ファイルを開き、既存の内容を削除してください。

2. このコード をコピーして main.mo ファイルに貼り付けてください。

   このサンプルアプリを見ると、次のような重要な要素に気づくかもしれません：

   • このコードでは、Name と Phone をカスタムの Text タイプとして定義しています。ユーザー定義の型を作成することで、コードの可読性を向上させることができます。

   • insert 関数はアップデートコールで、lookup 関数はクエリコールです。

   • Phone 型は、?Phone 構文を使ってオプションの値として識別されます。

ローカル Canister の実行環境を起動する

開発用に dfx はローカル Canister の実行環境を提供します。これには dfx.json ファイルが必要ですので、プロジェクトのルートディレクトリにいることを確認する必要があります。このチュートリアルでは、ターミナルシェルをふたつ用意して、ひとつのターミナルでローカル Canister 実行環境を起動して出力を確認し、もうひとつのターミナルでプロジェクトを管理するようにしてください。

ローカル Canister 実行環境を開始するには、以下の手順に従います：

1. ローカルコンピューターで新しいターミナルウィンドウまたはタブを開きます。

2. 必要であれば、プロジェクトのルートディレクトリに移動します。

   • これで、ふたつのターミナルが開いた状態になっているはずです。

   • プロジェクトディレクトリを、現在の作業ディレクトリとする必要があります。

3. ローカルコンピューターで以下のコマンドを実行して、ローカル Canister の実行環境を起動します：

   dfx start --clean

   このチュートリアルでは、--clean オプションを使用して、ローカル Canister 実行環境をクリーンな状態で起動します。

   このオプションは、通常の操作を中断させる可能性のある、孤立したバックグラウンドプロセスや Canister 識別子を削除します。例えば、プロジェクト間を移動する際に dfx stop を発行するのを忘れた場合、バックグラウンドや他のターミナルでプロセスが動作している可能性があります。--clean オプションを使用すると、実行中のプロセスを手動で見つけて終了させることなく、ローカル canister 実行環境を起動して次のステップに進むことができるようになります。

4. ローカル Canister の実行環境の出力を表示しているターミナルを開いたまま、新しいプロジェクトを作成した元のターミナルにフォーカスを切り替えます。

Dapp の登録、ビルド、デプロイ

開発環境において、ローカル Canister 実行環境が整えば、その上に Dapp を登録、ビルド、デプロイすることができます。

ローカルに Dapp をデプロイするには：

1. 必要に応じて、まだプロジェクトのルートディレクトリにいることを確認します。

2. 以下のコマンドを実行して、ローカルに Dapp を登録し、ビルド、デプロイします：

   dfx deploy phonebook

   dfx.json ファイルは、Dapp のフロントエンドエントリーポイントと assets Canister を作成するためのデフォルト設定を提供します。

   以前のチュートリアルでは、サンプルアプリのフロントエンドを追加しないため、アセット Canister のエントリーを削除しました。この変更により、プロジェクトのワークスペースが整理され、使われなくなるファイルがなくなりました。しかし、これを行う必要はなく、dfx.json ファイルにアセット Canister の記述を残しておいても問題はありません。例えば、後でフロントエンドアセットを追加するつもりなら、プレースホルダーとして使用することができます。

   このチュートリアルでは、dfx deploy phonebook コマンドを使用して電話帳のバックエンド Canister だけをデプロイすることができます。

   このチュートリアルでは、フロントエンド Canister のコンパイルを省略する方法を説明しますが、後で examples リポジトリの phone-book プロジェクトを調べれば、この Dapp に簡単なユーザーインターフェイスを追加することが可能です。

insert 関数で名前や数字を追加する

これで、ローカル Canister 実行環境に Canister として Dapp がデプロイされ、dfx canister call コマンドを使用して Dapp をテストできるようになりました。

デプロイした Dapp をテストするには、以下のようにします：

1. dfx canister call コマンドを使用して、insert 関数で Canister phonebook を呼び出し、以下のコマンドを実行して、名前と電話番号を渡します：

   dfx canister call phonebook insert '("Chris Lynn", "01 415 792 1333")'

2. 次のコマンドを実行して、2つ目の名前と番号のペアを追加します：

   dfx canister call phonebook insert '("Maya Garcia", "01 408 395 7276")'

3. 次のコマンドを実行して、lookup 関数を使って "Chris Lynn “ に関連する番号が返されることを確認します：

   dfx canister call phonebook lookup '("Chris Lynn")'

   このコマンドは、次のような出力を返します：

   (opt "01 415 792 1333")

4. 以下のコマンドを実行して、"Maya Garcia “ に関連付けられた番号で lookup 関数を呼び出してみてください：

   dfx canister call phonebook lookup '("01 408 395 7276")'

   この場合、電話番号は "Maya Garcia" という名前のエントリに関連付けられたキーではないので、コマンドは (null) を返すことに注意してください。

5. もう一度 lookup 関数を呼び出して、"Maya Garcia" と "Chris Lynn" の両方の電話番号を返すように、次のコマンドを実行してみてください：

   dfx canister call phonebook lookup '("Maya Garcia","Chris Lynn")'

   ひとつのキーに対してひとつの値を返すように書かれているので、コマンドは最初のキーに関連する情報、この例では Maya Garcia の電話番号のみを返します。

6. Candid UI を使用してコードをテストしてください。

   コードをテストするには、ここの指示に従います。

Dapp のソースコードを修正する

このチュートリアルで学んだことを発展させるために、ソースコードを修正して別の結果を返すようにしてみてはいかがでしょうか。

例えば、現在の Key-Value（名前-電話番号）のペアを挿入して検索するアプリの代わりに、データベースの「レコード」のように、主キーが複数のフィールドに関連付けられた連絡先情報を保存するアプリにするためにソースコードを変更したいと思うかもしれません。この例では、ユーザーや別のアプリが、自宅の電話番号、携帯電話番号、メールアドレス、住所などの情報を追加し、すべてのフィールドまたは特定のフィールドの値を選択的に返すことができるようにすることができます。

ローカル Canister の実行環境を停止する

Dapp の実験が終わったら、ローカル Canister 実行環境を停止して、バックグラウンドで実行し続けないようにすることができます。

ローカル Canister 実行環境を停止するには、以下の手順に従います：

1. ネットワーク操作が表示されているターミナルで、Control-C キーを押して、ローカルネットワークの処理を中断します。

2. 以下のコマンドを実行して、ローカル Canister 実行環境を停止します。

   dfx stop