附件型別：attachment

用途

attachment 適合發票、合約、商品照片與檢驗報告等檔案欄位。例如採購單可把 PDF 發票與簽收照片放在「發票附件」cell；檔案本身先上傳成 blob，紀錄只保存該 blob 的 ID。

建立 schema

columns.create 可直接接受附件限制；建立整張表時，schema_definition.columns 也使用相同欄位：


{
  "name": "發票附件",
  "type": "attachment",
  "required": false,
  "max_count": 3,
  "max_file_bytes": 10485760,
  "allowed_mime_types": ["application/pdf", "image/png"],
  "description": "發票 PDF 或簽收照片"
}

max_count 為 1–100；max_file_bytes 必須大於零且最多 5 GiB；allowed_mime_types: null 與空清單都代表不限制。

這三項限制是建立時設定。PATCH columns/{column_id} 使用的 ColumnUpdate 沒有附件限制欄位，因此建立後不能新增、修改或移除限制。若一定要更改，必須先評估刪欄會移除已儲存的 blob-ID cell，再刪除並重建欄位。

合法與不合法的值

先從 attachments.multipartInit 開始分段上傳並呼叫 attachments.multipartComplete，再把完成回應的 blob.id 陣列寫入 cell：


{
  "data": {
    "發票附件": [
      "44444444-4444-4444-8444-444444444444",
      "55555555-5555-4555-8555-555555555555"
    ]
  }
}

選填附件欄可用 null 或 [] 表示沒有檔案。

非字串 ID、其他公司擁有的 blob，或超過已宣告 max_count 的陣列都會被拒：


{
  "data": {
    "發票附件": [44444444]
  }
}

建立紀錄時也不能使用差量物件；包含 add 與 remove 的物件只適用於更新，而且 max_count: 1 的單檔欄只允許整組取代。

顯示與回傳

blob ID 實際存在 record.data；一般紀錄回應會把它們展開成 URL 已遮蔽的附件 metadata 陣列：


{
  "data": {
    "發票附件": [
      {
        "id": "44444444-4444-4444-8444-444444444444",
        "created_at": "2026-07-19 02:35:00",
        "url": null,
        "content_type": "application/pdf",
        "filename": "invoice.pdf",
        "size_bytes": 245760
      }
    ]
  }
}

要取得真正的檔案內容，先呼叫權限控管的 attachments.download，再使用它回傳的 signed_url；一般紀錄中的 url: null 不可使用。signed_url 是儲存 blob URL 的舊欄位名稱；這條 route 不會做密碼學簽章或加上時效限制，且回傳 expiration_seconds: 0。

注意事項

max_count 的 schema 範圍是 1–100；max_file_bytes 必須大於 0 且不超過 5 GiB；allowed_mime_types 為 MIME allow-list，null 或空陣列代表不限。
columns.create 可提供附件限制，但建立後不能用 PATCH 修改。
multipart init 不指定最終欄位。只有每個 attachment 欄都宣告大小上限時，早期 size check 才取最大的 max_file_bytes；只有每個 attachment 欄都宣告非空 MIME 清單時，早期 MIME check 才取 allowed_mime_types 聯集。實際寫入哪個 cell 是後續紀錄請求決定的。
兩道 init guard 彼此獨立。某欄不限制大小時，只停用早期 size guard；某欄不限制 MIME 時，只停用早期 MIME guard，因為某一欄會拒絕的檔案對另一欄可能合法。不要把「上傳成功」當成「目標欄驗證通過」。
真正的強制執行發生在後面兩個點。multipart complete 會重新量測組裝後的物件，並再次比對整張表最大的上限：違規時物件會被刪除、session 鍵會被清掉，blob 根本不會建立。接著資料列寫入會套用目標欄位自己的 MIME 與大小限制，且所有寫入路徑都適用；被拒絕時訊息會指出欄位（請求有帶顯示名稱時用顯示名稱，否則用內部 col_<hex> 鍵）。
量測到的大小會保存下來，並出現在每個附件項目的 size_bytes。null 代表這是從未量測過的舊 blob，下一次資料列寫入會補量並回填。如果物件完全讀不到，該次寫入會放行，而不是擋下來。
attachment 不可有 default_value、max_length 或 options。blob 必須先上傳，且必須屬於該表解析出的公司租戶。
更新多檔 cell 可用 add / remove 差量；新增與移除清單不可重疊。建立紀錄時請一律送完整陣列。
附件欄只支援是否有值的篩選：stored_filters 可用 is_empty 與 is_not_empty。不能依 blob ID、檔名、MIME 型別或大小篩選，也永遠不能排序。

試試看

先從 attachments.multipartInit 開始完整上傳流程，再到 API Playground 將回傳的 blob ID 寫進紀錄。