frappe-core-files

Frappe ファイル管理

クイックリファレンス

操作	メソッド	備考
バイトデータからファイルを保存	save_file(fname, content, dt, dn)	File ドキュメントを返します
URL からファイルを保存	save_url(file_url, fname, dt, dn)	URL から File ドキュメントを作成します
ファイルの内容を読み取る	frappe.get_file(fname)	[filename, content] を返します
ファイルパスを取得	get_file_path(file_name)	絶対パスを解決します
HTTP 経由でアップロード	POST /api/method/upload_file	マルチパート形式のフォームアップロード
ファイルを削除	frappe.delete_doc("File", name)	ドキュメントとファイルシステム上のファイルを削除します
印刷データを添付	frappe.attach_print(dt, dn, print_format)	{"fname", "fcontent"} を返します
キャッシュ済みドキュメントを取得	frappe.get_cached_doc("File", name)	読み取り専用、キャッシュ済み

---

判断ツリー

What file operation do you need?
│
├─ Upload a file from user input?
│  ├─ Via web form → Attach field type (auto-handles upload)
│  └─ Via API → POST /api/method/upload_file
│
├─ Create a file programmatically?
│  ├─ From bytes/content → save_file(fname, content, dt, dn)
│  ├─ From external URL → save_url(file_url, fname, dt, dn)
│  └─ Full control → frappe.get_doc({"doctype": "File", ...}).insert()
│
├─ Read file content?
│  ├─ By filename → frappe.get_file(fname)
│  └─ By File doc → file_doc.get_content()
│
├─ Public or private?
│  ├─ Public (anyone with link) → is_private=0, URL: /files/fname
│  └─ Private (permission-based) → is_private=1, URL: /private/files/fname
│
└─ Generate PDF attachment?
   └─ frappe.attach_print(doctype, name, print_format)

---

File DocType：主要フィールド

フィールド	型	説明
file_name	Data	パスを含まないファイル名
file_url	Data	URL パス（例：/files/report.pdf）
file_type	Data	拡張子（PDF、PNG、DOCX など）
is_private	Check	0 = 公開、1 = 非公開
is_folder	Check	フォルダー項目の場合は True
folder	Link → File	親フォルダー
attached_to_doctype	Link → DocType	親ドキュメントの型
attached_to_name	Data	親ドキュメント名
attached_to_field	Data	親ドキュメントのフィールド名
content_hash	Data	重複排除用の SHA-256
file_size	Int	サイズ（バイト単位）

---

ファイル URL のパターン

種類	URL パターン	ファイルシステムパス
公開	/files/{filename}	{site}/public/files/{filename}
非公開	/private/files/{filename}	{site}/private/files/{filename}
リモート	https://...	ローカルには保存されません
API	/api/method/{path}	動的に生成されます

有効な URL プレフィックス：http://、https://、/api/method/、/files/、/private/files/。

機密文書には必ず /private/files/ を使用してください。公開ファイルは、認証されていないユーザーを含め、URL を知っている誰でもアクセスできます。

---

権限モデル

Frappe のファイルでは、次の 3 段階の権限モデルが使用されます。

1. Administrator — すべてのファイルに無制限でアクセスできます
2. 公開ファイル（is_private=0）— URL を知っている誰でも読み取り可能です（読み取りに認証は不要です）
3. 非公開ファイル（is_private=1）— アクセスには次のいずれかが必要です。
   • ユーザーがファイルの所有者である、または
   • ユーザーがファイルに対する明示的な共有権限を持っている、または
   • ユーザーが attached_to_doctype／attached_to_name ドキュメントの読み取り権限を持っている

機密データを公開ファイルとして保存しないでください。個人データ、財務記録、機密情報を含む文書には、必ず is_private=1 を設定してください。

---

プログラムによるファイル操作

コンテンツからファイルを保存

from frappe.utils.file_manager import save_file

# Save a generated CSV
csv_content = "Name,Amount\nACME,1000\nGlobex,2000"
file_doc = save_file(
    fname="report.csv",
    content=csv_content.encode("utf-8"),
    dt="Sales Invoice",           # attach to this DocType
    dn="SINV-00001",              # attach to this document
    folder="Home/Attachments",    # optional folder
    is_private=1,                 # private file
)
# file_doc.file_url → "/private/files/report.csv"

URL からファイルを保存

from frappe.utils.file_manager import save_url

file_doc = save_url(
    file_url="https://example.com/logo.png",
    filename="company-logo.png",
    dt="Company",
    dn="My Company",
    folder="Home",
    is_private=0,
)

ファイルの内容を読み取る

# By filename
filename, content = frappe.get_file("report.csv")

# By File document
file_doc = frappe.get_doc("File", {"file_name": "report.csv"})
content_bytes = file_doc.get_content()

File ドキュメントを直接作成

file_doc = frappe.get_doc({
    "doctype": "File",
    "file_name": "generated-report.pdf",
    "attached_to_doctype": "Sales Invoice",
    "attached_to_name": "SINV-00001",
    "is_private": 1,
    "content": pdf_bytes,  # raw bytes — written to disk on insert
}).insert(ignore_permissions=True)

PDF を生成して添付

# Create PDF attachment dict (for use with sendmail)
pdf_attachment = frappe.attach_print(
    "Sales Invoice",
    "SINV-00001",
    print_format="Standard",
)
# Returns: {"fname": "Sales Invoice - SINV-00001.pdf", "fcontent": <bytes>}

# Save PDF as file attachment
from frappe.utils.file_manager import save_file

pdf = frappe.get_print("Sales Invoice", "SINV-00001", print_format="Standard", as_pdf=True)
save_file("invoice.pdf", pdf, "Sales Invoice", "SINV-00001", is_private=1)

---

REST API 経由でのファイルアップロード

# Upload file attached to a document
curl -X POST https://site.example.com/api/method/upload_file \
  -H "Authorization: token api_key:api_secret" \
  -F "file=@/path/to/document.pdf" \
  -F "doctype=Sales Invoice" \
  -F "docname=SINV-00001" \
  -F "is_private=1"

レスポンス：

{
  "message": {
    "name": "FILE-00001",
    "file_name": "document.pdf",
    "file_url": "/private/files/document.pdf",
    "is_private": 1
  }
}

---

ファイルサイズと拡張子の制限

デフォルトの最大ファイルサイズ： 添付ファイル 1 件あたり 10 MB です。

site_config.json で上書きします。

{
  "max_file_size": 20971520
}

ドキュメントあたりの最大添付数： DocType の Customize Form → Max Attachments フィールドで設定します。

プログラムでファイルサイズを確認：

from frappe.utils.file_manager import check_max_file_size
check_max_file_size(content)  # raises MaxFileSizeReachedError if too large

---

添付フィールドの型

フィールド型	保存内容	UI
Attach	単一のファイル URL	ファイル選択画面 + アップロードボタン
Attach Image	単一の画像 URL	画像プレビュー + アップロード

どちらもフィールド値に file_url 文字列を保存します。File DocType レコードは別途作成され、attached_to_field が設定されます。

---

S3／クラウドストレージの統合

Frappe では、delete_file_data_content フックとカスタムアップロードハンドラーを使って、独自のファイルストレージに対応できます。

frappe-s3-attachment または類似アプリ経由の S3

# In hooks.py of custom app
delete_file_data_content = "my_app.storage.delete_from_s3"

カスタムストレージバックエンドを使用する場合は、ファイルの削除を必ずテストしてください。デフォルトの delete_file_from_filesystem が対応するのはローカルファイルのみです。

設定パターン

# site_config.json for S3-compatible storage
{
  "s3_bucket": "my-frappe-files",
  "s3_region": "eu-west-1",
  "s3_access_key": "AKIA...",
  "s3_secret_key": "...",
}

---

バージョンの違い

機能	v14	v15	v16
ファイルのDocType	利用可能	利用可能	利用可能
content_hashによる重複排除	利用可能	利用可能	利用可能
画像の最適化	手動	自動（1920x1080、85%）	自動
Zipのインポート／エクスポート	利用不可	利用可能	利用可能

---

関連項目

• references/examples.md — ファイル操作のコード例
• references/anti-patterns.md — ファイル処理でよくある間違い
• frappe-core-permissions — ファイルアクセスの権限モデル
• frappe-core-database — Fileクエリのデータベース操作