Builder Management API怎麼用 內容管理介面教程

Builder Management API通常指Builder.io用於管理內容的介面能力。先區分兩個容易混淆的介面：Write API負責建立、修改和刪除內容條目；Admin API面向後端或受信任服務，可管理模型、空間等資源。若目標是維護頁面內容，通常先用Write API；若要程式化管理模型結構，再研究Admin API。它適合無頭CMS中的視覺化編輯與自動化流程。

第一步：獲取API金鑰

登入Builder.io並開啟目標Space的設定，找到API金鑰相關頁面。寫入內容需要Private API Key；讀取已釋出內容通常可使用Public API Key。複製金鑰後先放進伺服器端環境變數，例如BUILDER_PRIVATE_KEY，不要寫入瀏覽器程式碼、公開倉庫或前端構建產物。金鑰一旦洩露，應儘快在後臺輪換，並檢查相關自動化任務。

先確定要操作的模型名稱，例如頁面模型常見名稱為page，但實際應以Space中的模型配置為準。Write API請求需要把模型名放進路徑，並以Bearer方式傳入私鑰。建議用測試Space驗證請求、欄位和釋出狀態，確認成功後再接入正式環境。開發時可使用curl或伺服器端HTTP客戶端傳送請求，並檢查HTTP狀態碼與返回JSON，避免把金鑰列印到日誌裡。

第二步：建立和更新頁面

建立內容時向https://builder.io/api/v1/write/MODEL_NAME傳送POST請求，MODEL_NAME換成實際模型名。請求頭設定Authorization: Bearer加私鑰，並設定Content-Type: application/json；請求體提供name、data等符合模型欄位的內容。每次POST都會新建條目，所以自動重試前先判斷上次請求是否已成功，避免生成重複頁面。儲存響應中的id，後續更新或刪除會用到它。

更新時把條目ID追加到介面路徑，使用PATCH只提交需要變更的欄位，例如data裡的標題或正文；這樣不會像PUT那樣整體替換資源。若要完整替換內容，再確認資料結構後使用PUT。釋出狀態可在內容資料中設定為draft、published或archived，先以草稿檢查頁面展示和路由匹配，再發布上線。介面返回成功後，也應透過內容讀取介面或編輯器確認結果。

使用模型和元件

模型決定頁面資料允許有哪些欄位，先在Builder編輯器中檢視模型名稱、欄位型別及必填項，再據此組織data物件。需要建立或修改模型時，屬於Admin API管理範圍，不要把寫內容介面誤當成模型管理介面。頁面中的視覺化元件則要按Builder內容結構儲存；編輯視覺內容時應連同對應的內容塊一起提交，否則可能只更新欄位而沒有替換編輯器中的佈局。

操作上可以先手工在編輯器建立一條示例頁面，再參考它的欄位和元件結構構造JSON。介面響應中的id用作後續定位依據；URL路徑等定向規則按專案模型設定維護。上線前用預覽環境檢查桌面和移動端效果，並確認元件已在專案整合中註冊。遇到欄位不顯示，優先核對欄位名稱、資料型別和模型定義，而不是反覆更換金鑰。

第三步：釋出和刪除頁面

釋出前把published設為published，或按團隊流程先儲存draft，再由編輯人員審閱後釋出。Builder釋出內容後，應用讀取內容的介面才能取得已釋出版本；若頁面暫時沒更新，先確認狀態、模型與查詢條件，再檢查快取。自動釋出指令碼最好設定環境區分和審批節點，避免測試內容誤入正式站點。釋出完成後用實際頁面路徑進行驗證，確認標題、元件和連結都正常。

刪除條目使用DELETE請求，路徑為https://builder.io/api/v1/write/MODEL_NAME/ENTRY_ID，並攜帶Bearer私鑰。刪除前先在後臺或讀取介面核對模型名和ID，生產內容建議先備份或歸檔，避免誤刪造成頁面不可恢復。刪除成功後檢查應用中的頁面和相關連結；若業務只需暫時下線，優先考慮改為archived或draft，而不是直接刪除。

排錯時先看響應狀態碼和錯誤正文，再依次確認金鑰權限、模型名稱、條目ID、JSON格式及必填欄位。若系統接入Webhook，預設寫操作可能觸發Webhook；當Webhook又回寫同一條內容時，可能形成迴圈，可評估使用triggerWebhooks=false，並在處理邏輯中增加事件篩選和冪等判斷。國內團隊也可瞭解墨刀AI作為視覺化設計與原型協作的替代選擇，官網：modao.cgref.cn。