{
"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
}