{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# APC-CLI 基本チュートリアル 実行フロー\n", "\n", "各ステップを上から順に実行することで、AutoPrivacy DCR上で関数を実行することができます。\n", "AutoPrivacy DCRの操作をCLIから行うツールとして、APC-CLIというコマンドラインツールを用います。\n", "\n", "**このJupyterNotebookは [dcr-docs-examplesリポジトリ](https://github.com/acompany-develop/dcr-docs-examples) に含まれています。リポジトリをクローンし、ステップ3の環境変数を設定すれば、説明に従って各セルを実行するだけでAutoPrivacy DCR上で処理を実行できます。**\n", "\n", "## 概要\n", "\n", "このスクリプトは以下の主要なステップで構成されています:\n", "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", "\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": [ "## 2. AutoPrivacy DCR 概要\n", "Cleanroomを用いることで、二者間で安全にデータを共有し実行することが可能となります。APC-CLI実行時にprofile(user)を指定することで、異なるユーザーとして実行することができます。profileによってユーザーが区別されるため、異なるマシンから実行することが可能です(同一のマシンから実行することも可能)。\n", "具体的なフロー図は以下のようになります。\n", "\n", "
フロー図\n", "\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 3. 環境変数設定\n", "\n", "実行に必要な環境変数を設定します。`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`)は同一になります。" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# マシンに保存される設定に紐づく識別子。ユーザーが自由に設定することが出来る。\n", "%env profile1=user1\n", "# マシンに保存される設定に紐づく識別子。ユーザーが自由に設定することが出来る。\n", "%env profile2=user2\n", "\n", "%env API_URL=\n", "%env ATTESTATION_URL=\n", "%env ATTESTATION_API_VERSION=\n", "%env MR_ENCLAVE=\n", "%env MR_SIGNER=\n", "%env CLIENT_ID1=\n", "%env CLIENT_SECRET1=\n", "%env CLIENT_ID2=\n", "%env CLIENT_SECRET2=\n", "%env PROJECT_ID=\n", "\n", "# 入出力設定ファイルのパス\n", "%env ENCRYPTED_FILES_PATH=encrypted-files.yaml" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 4. APC-CLI のセットアップ\n", "\n", "詳細なAPC-CLIのセットアップ方法については、[こちら](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/getting-started/installation.html)から参照できます。\n", "\n", "まず、`apc_cli_version`は[こちら](https://github.com/acompany-develop/apc-cli/releases)を参照し、APC-CLIのバージョンを指定してください。以下は例として、`3.0.1`を指定しています。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%env APC_CLI_VERSION=3.0.1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "指定したバージョンでAPC-CLIをダウンロードします。\n", "\n", "**注意**: このステップではwgetを使用します。wgetがインストールされていない場合は、以下のコマンドでインストールしてください:\n", "- **macOS**: `brew install wget`\n", "- **Linux (Ubuntu/Debian)**: `sudo apt-get install wget`" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "\n", "# OSを判定\n", "OS=$(uname -s)\n", "\n", "case $OS in\n", " \"Darwin\")\n", " # macOS\n", " echo \"macOS detected\"\n", " wget https://github.com/acompany-develop/apc-cli/releases/download/$APC_CLI_VERSION/apc-darwin-arm64.zip\n", " unzip apc-darwin-arm64.zip\n", " mv apc-darwin-arm64 apc\n", " chmod +x apc\n", " rm apc-darwin-arm64.zip\n", " ;;\n", " \"Linux\")\n", " # Linux\n", " echo \"Linux detected\"\n", " wget https://github.com/acompany-develop/apc-cli/releases/download/$APC_CLI_VERSION/apc-linux-x64.zip\n", " unzip apc-linux-x64.zip\n", " mv apc-linux-x64 apc\n", " chmod +x apc\n", " rm apc-linux-x64.zip\n", " ;;\n", " *)\n", " echo \"Unknown OS: $OS\"\n", " exit 1\n", " ;;\n", "esac" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "ダウンロードしたAPC-CLIのパスを通します。" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", "\n", "os.environ[\"PATH\"] = os.path.dirname(os.path.abspath(\"apc\")) + \":\" + os.environ[\"PATH\"]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "APC-CLIが正しくインストールされているか確認します。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc --version" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 5. プロファイル設定\n", "各プロファイルに対して設定情報を入力し、User IDを生成します。\n", "今回のチュートリアルでは標準出力されるUserIDを環境変数に読み込むために以下のようにコマンドを実行します。\n", "コマンドの詳細は [configure コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/configure.html) から参照できます。\n", "\n", "まずは、`profile1`について設定します。出力された`USER_ID`は次の入出力設定のステップで使用します。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "expect <`**と**``**を5で出力された**`profile1`**と**`profile2`**のUser IDに置き換えてください。**" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "cat > $ENCRYPTED_FILES_PATH << EOF\n", "inputs:\n", " input_1: &user_1_id \n", " input_2: &user_2_id \n", "outputs:\n", " output_1: *user_1_id\n", " output_2: *user_2_id\n", "EOF\n", "cat $ENCRYPTED_FILES_PATH" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 7. 認証とヘルスチェック\n", "\n", "各プロファイルでログインします。コマンドの詳細は [auth-login コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/auth-login.html) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc auth-login --profile $profile1\n", "apc auth-login --profile $profile2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "各プロファイルで、サーバーに対してヘルスチェックを行い、正常にサーバーと通信ができているかを確認します。コマンドの詳細は [healthcheck コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/healthcheck.html) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc healthcheck --profile $profile1\n", "apc healthcheck --profile $profile2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 8. プロジェクト設定\n", "\n", "各プロファイルで同じプロジェクトを設定します。コマンドの詳細は [set-project コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/set-project.html) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc set-project $PROJECT_ID --profile $profile1\n", "apc set-project $PROJECT_ID --profile $profile2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 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上で実行可能であり、これらの関数のパスを指定することも可能です。" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", "\n", "%env FUNCTION_SOURCE_PATH=../../functions/join\n", "\n", "FUNCTION_SOURCE_PATH = os.environ.get(\"FUNCTION_SOURCE_PATH\")\n", "\n", "%env FUNCTION_SOURCE_PATH={FUNCTION_SOURCE_PATH}\n", "# 関数のパス\n", "%env FUNCTION_DIRECTORY_PATH={FUNCTION_SOURCE_PATH}/function\n", "# 入力データのパス\n", "%env INPUT_1_PATH={FUNCTION_SOURCE_PATH}/inputs/input_1\n", "%env INPUT_2_PATH={FUNCTION_SOURCE_PATH}/inputs/input_2\n", "# 出力データのパス\n", "%env OUTPUT_1_PATH={FUNCTION_SOURCE_PATH}/outputs/output_1\n", "%env OUTPUT_2_PATH={FUNCTION_SOURCE_PATH}/outputs/output_2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Cleanroom上での関数実行で使用するライブラリを`packages`ディレクトリにインストールします。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "pip install --platform manylinux2014_x86_64 \\\n", " --only-binary=:all: \\\n", " --python-version 3.10 \\\n", " --target=$FUNCTION_DIRECTORY_PATH/packages \\\n", " -r $FUNCTION_SOURCE_PATH/requirements.txt" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 10. 関数ストレージへのアップロード\n", "\n", "関数ディレクトリのパスを指定した上で、実行する関数をCleanroom上にアップロードします。コマンドの詳細は [function-storage コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/function-storage.html#function-storage-upload) から参照できます。なお、出力された`FunctionStoragePath`は次のCleanroomデプロイのステップで使用します。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc function-storage upload --source $FUNCTION_DIRECTORY_PATH --profile $profile1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 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`**オプションの引数のを10で出力された**`FunctionStoragePath`**の値に置き換えてください。**" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc cleanroom deploy \\\n", " --source \\\n", " --name join_app \\\n", " --runtime python3.10 \\\n", " --handler handler.run \\\n", " --encrypted-files $ENCRYPTED_FILES_PATH \\\n", " --memory 2 \\\n", " --profile $profile1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 12. データの Cleanroom へのコピー\n", "\n", "各プロファイルから、ローカルの入力データをCleanroom上にコピーします。コマンドの詳細は [cleanroom copyコマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom-data.html) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc cleanroom data cp $INPUT_1_PATH join_app:input_1 --profile $profile1\n", "apc cleanroom data cp $INPUT_2_PATH join_app:input_2 --profile $profile2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 13. Cleanroom の実行\n", "\n", "デプロイされたCleanroom上のアプリケーションを実行します。コマンドの詳細は [cleanroom run コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom.html#cleanroom-run) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc cleanroom run join_app --profile $profile1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 14. 結果のダウンロード\n", "\n", "実行結果を各プロファイルにダウンロードします。コマンドの詳細は [cleanroom data コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom-data.html) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc cleanroom data cp join_app:output_1 $OUTPUT_1_PATH --profile $profile1\n", "apc cleanroom data cp join_app:output_2 $OUTPUT_2_PATH --profile $profile2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## 15. クリーンアップ\n", "\n", "DCR上にアップロードした関数ディレクトリやデプロイしたCleanroomアプリケーションを使用しない場合はクリーンアップすることをお勧めします。それぞれの手順は以下の通りです。" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Cleanroom上のアプリケーションを削除します。コマンドの詳細は [cleanroom delete コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/cleanroom.html#cleanroom-delete) から参照できます。" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc cleanroom delete join_app --profile $profile1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Cleanroom上にアップロードされた関数を削除します。コマンドの詳細は [function-storage delete コマンド リファレンス](https://acompany-develop.github.io/autoprivacy-cloud/apc-cli/commands/function-storage.html#function-storage-delete) から参照できます。\n", "\n", "**注意: 以下のコマンド実行前にを10で出力された`FunctionStoragePath`の値に置き換えてください。**" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "vscode": { "languageId": "shellscript" } }, "outputs": [], "source": [ "%%bash\n", "apc function-storage delete --profile $profile1" ] } ], "metadata": { "kernelspec": { "display_name": "venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.17" } }, "nbformat": 4, "nbformat_minor": 4 }