Webiny Admin API怎麼用 內容管理介面教程

Webiny Admin API是Webiny內容管理系統提供的內容管理介面，實際操作主要透過Headless CMS的GraphQL API完成。它可以建立、更新、釋出和刪除內容，適合自動化內容管理與批次匯入。開始前先確認已有內容模型，例如文章模型，並記下模型欄位；下面以圖形化管理後臺和GraphQL請求為主線，帶你完成基本流程。

第一步：獲取API令牌

先登入Webiny管理後臺，在左側選單開啟Security（安全）下的API Keys（API金鑰）。新建金鑰時填寫名稱和用途說明，再選擇需要訪問的語言、Headless CMS範圍及操作權限。若只需檢視內容，授予讀取權限即可；要建立、編輯或刪除內容，則需配置相應的管理權限，避免直接開放不必要的操作範圍。

儲存後複製生成的令牌，並把它放在伺服器端的環境變數中，例如WEBINY_API_TOKEN；不要寫進公開網頁程式碼或提交到程式碼倉庫。接著從API Playground（API操作檯）或專案部署資訊中找到對應環境、語言和API型別的GraphQL地址。每次請求都要在HTTP頭中加入Authorization: Bearer 令牌，Bearer與令牌之間要有空格。

在API Playground裡可以先確認請求是否可用：選擇Manage API和目標語言，執行一個簡單查詢；若返回內容而不是授權錯誤，說明地址與令牌基本配置正確。Manage API支援寫入和管理操作，Read API用於讀取已釋出內容，Preview API可檢視未釋出的最新版本。開發和生產環境的地址可能不同，複製時要核對當前環境，避免誤操作線上資料。

第二步：建立和更新內容

建立內容前，先在Content Models中確認模型已存在，並檢查必填欄位、欄位型別和校驗規則。回到API Playground，在Manage API下檢視該模型自動生成的GraphQL schema，找到建立內容所需的mutation及欄位名稱。Webiny會根據內容模型動態生成可用查詢和mutation，因此不要憑空猜欄位；先用Playground自動補全或文件面板確認準確名稱。

確定欄位後，在GraphQL請求中填寫標題、正文、slug等模型欄位，執行建立mutation。成功後檢查響應中的記錄標識和欄位值，再到後臺內容列表確認條目出現。若返回校驗錯誤，通常是必填欄位缺失、欄位型別不匹配或slug衝突；按錯誤提示修正後重試。首次執行建議先建立一條測試內容，確認欄位對映與預期一致，再接入正式資料來源。

更新時先按記錄標識查詢目標內容，再使用模型對應的更新mutation提交修改後的欄位。不要只看請求是否返回成功，還要檢查返回資料或重新查詢確認變更落庫。欄位名必須與模型定義一致；對富文字、引用或檔案欄位，按schema要求傳入結構化值。若更新流程涉及版本或狀態，按介面要求提供對應引數，避免覆蓋他人剛剛提交的修改。

使用批次操作

批次匯入時，先把CSV或其他來源的資料轉換成符合模型欄位結構的記錄，再按固定數量分批提交。GraphQL支援一次請求組合多個操作，但具體可用方式取決於schema和介面限制；也可由指令碼逐條呼叫mutation。建議先用少量資料試跑，記錄每條記錄的成功或失敗結果，並儲存返回的標識，方便後續更新、排錯或續跑。

為了避免重複匯入，可先為每條內容準備穩定的唯一標識，例如來源系統ID或規範化slug，並在匯入前查詢是否已有對應條目。指令碼遇到網路超時或伺服器錯誤時，不要盲目重複建立；先查詢確認是否已寫入，再決定重試。遇到欄位校驗錯誤時，將錯誤與原始記錄一起記錄，修正後單獨重跑失敗項，這樣比整批迴滾更容易控制。

第三步：刪除和釋出內容

刪除操作使用Manage API中該模型對應的刪除mutation。執行前先用記錄標識查詢內容，核對標題、語言和狀態，確認刪的是目標條目；批次清理時先匯出標識與標題作為核對清單，再分批執行。刪除權限應僅授予確實需要清理資料的令牌。若不確定刪除是否可恢復，先在測試環境演練，並確認團隊的資料備份與恢復流程。

建立或更新內容後，條目不一定會自動對外可見。需要釋出時，使用模型schema中對應的釋出mutation，並在返回成功後透過Read API重新查詢，確認釋出版本可讀；若要預覽草稿，則使用Preview API。需要撤回時，可查詢相應的取消釋出操作。實際mutation名稱隨模型與Webiny版本而異，應以API Playground顯示的schema為準。

日常使用中，把令牌權限、API地址、模型欄位和釋出狀態分開管理，並在開發環境驗證後再遷移到生產環境。批次任務最好加入日誌、失敗重試和重複檢查；呼叫出錯時先檢視GraphQL響應中的errors，再核對授權範圍、語言和欄位結構。國內團隊若希望用視覺化方式梳理頁面或原型流程，也可以瞭解墨刀AI，官網入口為modao.cgref.cn。潤滅可作為教程釋出站點名稱，實際介面配置仍以你的Webiny專案為準。