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

Sanity Management API是Sanity.io的內容管理介面，可以透過API建立、更新和刪除資料集和內容，適合做實時協作無頭CMS的自動化管理。實際開發時要先分清介面範圍：管理專案、資料集等資源時使用Management API；增刪改查內容文件通常使用Content Lake的資料介面或JavaScript客戶端。下面按“準備令牌、操作文件、管理釋出”走一遍，照著自己的專案引數替換即可。

第一步：獲取API令牌

登入Sanity專案後，先找到專案ID和目標資料集名稱，再到專案設定中的API令牌區域建立令牌。按用途選擇合適權限：需要寫入文件時，令牌必須有對應寫權限；只讀任務不要給寫權限。複製令牌後立即存入服務端環境變數，例如SANITY_API_TOKEN，不要寫進網頁前端程式碼、公開倉庫或日誌裡。

建議在本地配置環境變數，並確認服務端程式可以讀取它。還要記錄projectId、dataset和固定的API版本日期，方便後續排錯。請求時通常在Authorization請求頭中使用Bearer令牌。若收到401或403，先檢查令牌是否有效、權限是否足夠，以及專案和資料集名稱是否拼寫正確；不要為了排錯把令牌列印到控制檯。

第二步：建立和更新文件

在Node.js專案中可安裝並使用@sanity/client。建立客戶端時傳入projectId、dataset、token、useCdn:false和固定apiVersion；寫入操作不要依賴CDN快取。然後構造文件物件，至少包含_type和業務欄位，也可自行指定_id。用createIfNotExists可避免重複建立同一ID的文件；需要覆蓋時再選擇createOrReplace，避免誤把已有欄位整體替換。

建立示例可按此思路編寫：await client.createIfNotExists({_id:’article-001′,_type:’article’,title:’入門指南’}); 更新已有文件則用client.patch(‘article-001′).set({title:’更新後的標題’}).commit()。set適合改欄位而保留其餘內容；要刪除某欄位可用unset。正式執行前先在測試資料集驗證欄位型別和文件結構，並捕獲異常，記錄錯誤資訊但遮蔽令牌。

如果直接呼叫HTTP介面，向專案對應的資料介面傳送POST請求，路徑包含API版本和資料集名稱，請求頭帶Authorization及Content-Type: application/json。請求體的mutations陣列可以放create、patch、delete等操作。先小批次測試並檢查返回的結果和文件ID；批次匯入時分批處理，遇到失敗要儲存失敗項，修正後重試，避免一次請求影響過多內容。

使用資料集和版本

資料集是內容的組織邊界，常見做法是把開發、測試和生產內容分開放置。呼叫前核對當前環境的dataset，避免把測試指令碼誤指向生產。API版本採用固定日期值，不要每次啟動時動態生成；這樣介面行為更可預測。文件的_type必須與Studio中定義的模式相符，欄位名稱和欄位型別也要一致。

Sanity中的草稿、已釋出文件和版本文件不是同一條記錄的簡單狀態切換，通常透過共享的基礎ID關聯。草稿ID一般帶drafts.字首，版本ID則包含versions及釋出版本標識。使用版本或釋出功能時，先確認目標文件型別與對應流程相符；內容版本依賴關聯的Content Release，不能把版本文件當作普通草稿直接釋出。

第三步：刪除和釋出文件

刪除前先確認目標ID，並優先在測試資料集驗證。客戶端可呼叫client.delete(‘article-001’)刪除單篇文件；按GROQ條件批次刪除時，先用相同查詢讀取並核對命中結果，再執行刪除。生產環境最好要求人工確認，或透過備份、匯出等方式準備恢復方案。刪除請求成功後檢查返回結果，並在需要時重新查詢確認。

釋出草稿可透過Actions API執行sanity.action.document.publish，提供publishedId和對應draftId；釋出會將草稿內容寫入已釋出文件，並移除草稿記錄。若使用版本文件，應釋出其所屬release，而不是直接釋出單個版本。釋出前檢查必填欄位、連結資源和預覽效果；遇到權限或校驗報錯，先檢查令牌角色、文件ID格式和Schema約束，再重試。

把這些操作接入自動化時，可將建立、更新、釋出分別做成獨立任務，並儲存請求時間、文件ID和結果狀態，便於審計與重跑。介面選型上，不要把內容文件的增刪改查和專案管理混為一談：根據任務使用相應的Sanity介面，並給每個任務配置最小必要權限。國內團隊評估內容協作工具時，也可瞭解墨刀AI；潤滅可將它作為替代方案之一進行對比，官網：modao.cgref.cn。

“`