diff --git a/notebooks/tutorial/basic_apc_cli_tutorial.ipynb b/notebooks/tutorial/basic_apc_cli_tutorial.ipynb index 8bb16b6..3786fcd 100644 --- a/notebooks/tutorial/basic_apc_cli_tutorial.ipynb +++ b/notebooks/tutorial/basic_apc_cli_tutorial.ipynb @@ -6,83 +6,68 @@ "source": [ "# APC-CLI 基本チュートリアル 実行フロー\n", "\n", - "基本的に各ステップを上から順に実行することで、AutoPrivacy DCR上で関数を実行することができます。\n", + "各ステップを上から順に実行することで、AutoPrivacy DCR上で関数を実行することができます。\n", "AutoPrivacy DCRの操作をCLIから行うツールとして、APC-CLIというコマンドラインツールを用います。\n", "\n", - "**このJupyterNotebookは[こちら](https://github.com/acompany-develop/dcr-docs-examples/blob/main/notebooks/tutorial/basic_apc_cli_tutorial.ipynb)に上がっているため、ステップ2の環境変数さえ設定すれば、あとは説明に従って各セルを実行するだけで、AutoPrivacy DCR上で処理を実行できるようになっています。**\n", + "**このJupyterNotebookは[dcr-docs-examplesリポジトリ](https://github.com/acompany-develop/dcr-docs-examples)に含まれています。リポジトリをクローンし、ステップ3の環境変数を設定すれば、説明に従って各セルを実行するだけでAutoPrivacy DCR上で処理を実行できます。**\n", "\n", "## 概要\n", "\n", "このスクリプトは以下の主要なステップで構成されています：\n", - "1. 全体概要\n", - "2. 環境変数設定\n", - "3. APC-CLI のセットアップ\n", - "4. プロファイル設定\n", - "5. 入出力の設定ファイルの生成\n", - "6. 認証とヘルスチェック\n", - "7. プロジェクト設定\n", - "8. 関数の準備\n", - "9. 関数ストレージへのアップロード\n", - "10. Cleanroom デプロイ\n", - "11. データの Cleanroom へのコピー\n", - "12. Cleanroom の実行\n", - "13. 結果のダウンロード\n", - "14. クリーンアップ" + "1. チュートリアル全体概要\n", + "2. AutoPrivacy DCR 概要\n", + "3. 環境変数設定\n", + "4. APC-CLI のセットアップ\n", + "5. プロファイル設定\n", + "6. 入出力の設定ファイルの生成\n", + "7. 認証とヘルスチェック\n", + "8. プロジェクト設定\n", + "9. 関数の準備\n", + "10. 関数ストレージへのアップロード\n", + "11. Cleanroom デプロイ\n", + "12. データの Cleanroom へのコピー\n", + "13. Cleanroom の実行\n", + "14. 結果のダウンロード\n", + "15. クリーンアップ" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. 全体概要\n", - "Cleanroomを用いることで、二者間で安全にデータを共有し実行することが可能となります。APC-CLI実行時に基本的にprofile（user）を指定するのですが、profileが異なれば異なるユーザーから実行されることを想定しているため、異なるマシンから実行することが可能です（同一のマシンから実行することも可能）。\n", - "具体的なフロー図は以下のようになります。\n", + "## 1. チュートリアル全体概要\n", "\n", - "
フロー図\n", - "\n", - "
" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 2. 環境変数設定\n", - "ファイル・ディレクトリ構成としては、今回は以下のようなものを想定します。この詳細については[こちら](https://acompany-develop.github.io/autoprivacy-cloud/apc-dcr/user-guide/user-files/function-directory.html)から参照できます。" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "```\n", - "FUNCTION_SOURCE_PATH\n", - "├── function # 関数のパス\n", - "│ └── handler.py\n", - "│ └── packages # 依存パッケージのパス\n", - "├── inputs # 入力データのパス\n", - "│ ├── input_1\n", - "│ └── input_2\n", - "└── outputs # 出力データのパス\n", - " ├── output_1\n", - " └── output_2\n", - "```" + "このチュートリアルでは、AutoPrivacy DCRを使用してデータの安全な共有と処理を実現する方法を説明します。具体的には、二者間でデータを共有し、Cleanroom上でjoin関数を実行することで、プライバシーを保護しながらデータ処理を行います。join関数の全実装は[こちらのコード](https://github.com/acompany-develop/dcr-docs-examples/blob/main/functions/join/function/handler.py)のようになります。\n", + "\n", + "**前提条件：**\n", + "- 設定情報（CLIENT_ID、CLIENT_SECRET等）\n", + "- Python 3.10\n", + "- OS: macOS、Linux\n", + "- アーキテクチャ: x86_64、ARM64" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "このチュートリアルではjoin関数をCleanroom上で実行します。join関数の全実装は[こちら](https://github.com/acompany-develop/dcr-docs-examples/blob/main/functions/join/function/handler.py)のようになります。" + "## 2. AutoPrivacy DCR 概要\n", + "Cleanroomを用いることで、二者間で安全にデータを共有し実行することが可能となります。APC-CLI実行時にprofile（user）を指定することで、異なるユーザーとして実行することができます。profileによってユーザーが区別されるため、異なるマシンから実行することが可能です（同一のマシンから実行することも可能）。\n", + "具体的なフロー図は以下のようになります。\n", + "\n", + "
フロー図\n", + "\n", + "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "実行に必要な環境変数を.envファイルに書き込みます。`API_URL`, `ATTESTATION_URL`, `ATTESTATION_API_VERSION`, `MR_ENCLAVE`, `MR_SIGNER`, `CLIENT_ID1`, `CLIENT_SECRET1`, `CLIENT_ID2`, `CLIENT_SECRET2`, `PROJECT_ID`という環境変数の値はAutoPrivacy DCRサービス提供者から提供されたものを使用します。ただし、ダブルクオーテーションはつけずに値だけを環境変数に代入してください。\n", + "## 3. 環境変数設定\n", "\n", - "なお、データ共有を行う二者間では、`CLIENT_ID`と`CLIENT_SECRET`だけ異なり、それ以外環境変数の値（`API_URL`, `ATTESTATION_URL`, `ATTESTATION_API_VERSION`, `MR_ENCLAVE`, `MR_SIGNER`, `PROJECT_ID`）は同一になります。" + "実行に必要な環境変数を設定します。`API_URL`, `ATTESTATION_URL`, `ATTESTATION_API_VERSION`, `MR_ENCLAVE`, `MR_SIGNER`, `CLIENT_ID1`, `CLIENT_SECRET1`, `CLIENT_ID2`, `CLIENT_SECRET2`, `PROJECT_ID`という環境変数の値は、AutoPrivacy DCRサービス提供者から提供されるconfig.tomlファイルに記載されています。ただし、ダブルクオーテーションはつけずに値だけを環境変数に代入してください。\n", + "\n", + "なお、データ共有を行う二者間では、`CLIENT_ID`と`CLIENT_SECRET`だけ異なり、それ以外の環境変数の値（`API_URL`, `ATTESTATION_URL`, `ATTESTATION_API_VERSION`, `MR_ENCLAVE`, `MR_SIGNER`, `PROJECT_ID`）は同一になります。" ] }, { @@ -115,7 +100,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. APC-CLI のセットアップ\n", + "## 4. APC-CLI のセットアップ\n", "\n", "詳細なAPC-CLIのセットアップ方法については、[こちら](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/getting-started/installation.html)から参照できます。\n", "\n", @@ -139,7 +124,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "指定したバージョンでAPC-CLIをダウンロードします。" + "指定したバージョンでAPC-CLIをダウンロードします。\n", + "\n", + "**注意**: このステップではwgetを使用します。wgetがインストールされていない場合は、以下のコマンドでインストールしてください：\n", + "- **macOS**: `brew install wget`\n", + "- **Linux (Ubuntu/Debian)**: `sudo apt-get install wget`" ] }, { @@ -226,8 +215,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. プロファイル設定\n", - "各プロファイルに対して種設定情報を入力し、User IDを生成します。\n", + "## 5. プロファイル設定\n", + "各プロファイルに対して設定情報を入力し、User IDを生成します。\n", "今回のチュートリアルでは標準出力されるUserIDを環境変数に読み込むために以下のようにコマンドを実行します。\n", "コマンドの詳細は [configure コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/configure.html) から参照できます。\n", "\n", @@ -307,11 +296,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. 入出力の設定ファイルの生成\n", + "## 6. 入出力の設定ファイルの生成\n", "\n", - "入出力の設定ファイルを`$ENCRYPTED_FILES_PATH`に作成します。詳細は[こちら](https://acompany-develop.github.io/autoprivacy-cloud/apc-dcr/user-guide/user-files/definition-files.html)から参照できます。\n", + "入出力の設定ファイルを`$ENCRYPTED_FILES_PATH`に作成します。この設定ファイルでは、入力データと出力データにアクセス可能なUser IDを指定します。\n", + "詳細は[こちら](https://acompany-develop.github.io/autoprivacy-cloud/apc-dcr/user-guide/user-files/definition-files.html)から参照できます。\n", "\n", - "**ただし、実行前に**``**と**``**を5で出力された**`profile1`**と**`profile2`**のUser IDに置き換えてください。**" + "**注意: 以下のコマンド実行前に**``**と**``**を5で出力された**`profile1`**と**`profile2`**のUser IDに置き換えてください。**" ] }, { @@ -340,7 +330,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 6. 認証とヘルスチェック\n", + "## 7. 認証とヘルスチェック\n", "\n", "各プロファイルでログインします。コマンドの詳細は [auth-login コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/auth-login.html) から参照できます。" ] @@ -386,7 +376,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 7. プロジェクト設定\n", + "## 8. プロジェクト設定\n", "\n", "各プロファイルで同じプロジェクトを設定します。コマンドの詳細は [set-project コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/set-project.html) から参照できます。" ] @@ -410,9 +400,25 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 8. 関数の準備\n", - "Cleanroom上で実行する関数のパスを設定します。\n", - "今回のチュートリアルでは、リポジトリの中のjoin関数のパスを`FUNCTION_SOURCE_PATH`に指定します。\n", + "## 9. 関数の準備\n", + "\n", + "Cleanroom上で実行する関数のパスを設定します。今回のチュートリアルでは、リポジトリの中のjoin関数のパスを`FUNCTION_SOURCE_PATH`に指定します。\n", + "\n", + "ファイル・ディレクトリ構成としては、今回は以下のようなものを想定します。ディレクトリ構成の詳細については[ドキュメント](https://acompany-develop.github.io/autoprivacy-cloud/apc-dcr/user-guide/user-files/function-directory.html)から参照できます。\n", + "\n", + "```\n", + "FUNCTION_SOURCE_PATH\n", + "├── function # 関数のパス\n", + "│ └── handler.py\n", + "│ └── packages # 依存パッケージのパス\n", + "├── inputs # 入力データのパス\n", + "│ ├── input_1\n", + "│ └── input_2\n", + "└── outputs # 出力データのパス\n", + " ├── output_1\n", + " └── output_2\n", + "```\n", + "\n", "なお、[このディレクトリ](https://github.com/acompany-develop/dcr-docs-examples/tree/main/functions)の中の関数はCleanroom上で実行可能であり、これらの関数のパスを指定することも可能です。" ] }, @@ -468,7 +474,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 9. 関数ストレージへのアップロード\n", + "## 10. 関数ストレージへのアップロード\n", "\n", "関数ディレクトリのパスを指定した上で、実行する関数をCleanroom上にアップロードします。コマンドの詳細は [function-storage コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/function-storage.html#function-storage-upload) から参照できます。なお、出力された`FunctionStoragePath`は次のCleanroomデプロイのステップで使用します。" ] @@ -491,12 +497,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 10. Cleanroom デプロイ\n", + "## 11. Cleanroom デプロイ\n", "\n", "アップロードされた関数を使用してCleanroomアプリケーションをデプロイします。\n", "コマンドの詳細は [cleanroom deploy コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom.html#cleanroom-deploy) から参照できます。\n", "\n", - "**ただし、実行前に**`--source`**オプションの引数のを9で出力された**`FunctionStoragePath`**の値に置き換えてください。**" + "**注意: 以下のコマンド実行前に**`--source`**オプションの引数のを10で出力された**`FunctionStoragePath`**の値に置き換えてください。**" ] }, { @@ -524,7 +530,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 11. データの Cleanroom へのコピー\n", + "## 12. データの Cleanroom へのコピー\n", "\n", "各プロファイルから、ローカルの入力データをCleanroom上にコピーします。コマンドの詳細は [cleanroom copyコマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom-data.html) から参照できます。" ] @@ -548,7 +554,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 12. Cleanroom の実行\n", + "## 13. Cleanroom の実行\n", "\n", "デプロイされたCleanroom上のアプリケーションを実行します。コマンドの詳細は [cleanroom run コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom.html#cleanroom-run) から参照できます。" ] @@ -571,7 +577,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 13. 結果のダウンロード\n", + "## 14. 結果のダウンロード\n", "\n", "実行結果を各プロファイルにダウンロードします。コマンドの詳細は [cleanroom data コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom-data.html) から参照できます。" ] @@ -595,9 +601,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 14. クリーンアップ\n", + "## 15. クリーンアップ\n", "\n", - "使用したリソースに変更を加える必要があり、削除したい場合はリソースをクリーンアップすることができます。" + "DCR上にアップロードした関数ディレクトリやデプロイしたCleanroomアプリケーションを使用しない場合はクリーンアップすることをお勧めします。それぞれの手順は以下の通りです。" ] }, { @@ -627,7 +633,7 @@ "source": [ "Cleanroom上にアップロードされた関数を削除します。コマンドの詳細は [function-storage delete コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/function-storage.html#function-storage-delete) から参照できます。\n", "\n", - "**ただし、実行前にを9で出力された`FunctionStoragePath`の値に置き換えてください。**" + "**注意: 以下のコマンド実行前にを10で出力された`FunctionStoragePath`の値に置き換えてください。**" ] }, {