Payload GraphQL API怎麼用 內容查詢介面教程

Payload GraphQL API是Payload的內容查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做前後端分離應用。它會根據專案中的集合和全域性配置生成查詢能力，預設介面是 /api/graphql。下面從權限準備、編寫查詢到前端請求，帶你完成一次內容讀取。示例假設你已經啟動Payload專案，並建立了名為 posts 的內容集合。

第一步：獲取API金鑰

先確認專案裡有啟用認證的使用者集合，並在集合配置中開啟 auth.useAPIKey。API Key不是單獨的公共訪問令牌，而是代表某個使用者；請求會沿用該使用者的訪問控制權限。因此建議為程式整合建立專用使用者，只授予讀取文章所需的權限，不要直接使用管理員帳戶。

啟動專案後，登入管理面板，找到對應使用者記錄，按當前版本介面提供的操作生成API Key。生成後馬上覆制並妥善儲存，因為金鑰通常只在生成時完整顯示，之後只會顯示遮罩值。若金鑰洩露，及時撤銷或重新生成；修改 PAYLOAD_SECRET 後，已有金鑰也需要重新生成。

呼叫時把金鑰放在 Authorization 請求頭中，格式為“使用者集合slug API-Key 金鑰”。例如使用者集合slug為 users，格式就是 users API-Key 後接實際金鑰。注意大小寫和空格要準確。公開可讀的內容可能不需要認證，但是否允許讀取最終由集合的訪問控制決定，不能只憑介面能訪問就判斷內容已公開。

第二步：編寫GraphQL查詢

開啟開發環境的 GraphQL Playground，預設地址通常是專案域名加 /api/graphql-playground；生產環境一般預設關閉，可直接使用 /api/graphql 發請求。先在 Playground 的 Docs 或 Schema 面板檢視實際查詢名稱和欄位。名稱依據集合標籤生成，不一定與集合slug完全相同，欄位也必須符合專案配置。

例如文章集合標籤生成的查詢若為 Posts，可嘗試查詢文章標題和摘要：query { Posts(limit: 5) { docs { id title excerpt } } }。不同Payload版本或配置生成的欄位可能不同，請以Schema為準。查詢中只寫頁面需要的欄位，限制返回數量；若查詢報欄位不存在，先檢查集合標籤、欄位名和複數查詢名稱，再核對權限是否允許讀取。

使用變數和片段

篩選條件會變化時，使用變數，不要把使用者輸入直接拼進查詢字串。例如 query PostsByLimit($count: Int!) { Posts(limit: $count) { docs { id title } } }，請求體的 variables 可傳 { “count”: 5 }。變數型別要與Schema定義一致；必填型別帶感嘆號。這樣修改數量時只更新變數，查詢結構保持不變。

多個查詢需要重複同一組欄位時，可以定義片段複用：fragment PostFields on Post { id title excerpt }，然後在查詢中用 …PostFields 展開。片段的型別名稱須按專案Schema填寫。把大型查詢拆成清晰的小片段，能減少重複；同時控制關聯欄位和返回條數，避免一次取回過多資料，影響介面響應速度。

第三步：在前端呼叫API

瀏覽器端可用 fetch 向 https://你的域名/api/graphql 傳送 POST 請求，設定 Content-Type 為 application/json，body 放 query 和 variables。示例：fetch(‘/api/graphql’, { method: ‘POST’, headers: {‘Content-Type’:’application/json’}, body: JSON.stringify({query: ‘query { Posts(limit: 5) { docs { id title } } }’}) })。跨域場景需在服務端配置允許的來源。

如果需要認證，在 headers 中新增 Authorization，值按前述集合slug、API-Key和金鑰格式組合。更推薦由服務端代理請求：把金鑰放在伺服器環境變數中，再由服務端呼叫Payload，避免金鑰進入瀏覽器程式碼、頁面原始碼或網路響應。不要把金鑰提交到公開程式碼倉庫，也不要在前端硬編碼。

請求完成後先檢查HTTP狀態，再解析JSON；GraphQL錯誤通常會出現在 errors 欄位，即使HTTP請求本身成功也要檢查。開發時可以輸出錯誤訊息，生產環境則避免把金鑰或敏感內容寫入日誌。若返回空資料，依次檢查查詢欄位、過濾條件、釋出狀態和訪問控制；確認查詢有效後，再按需接入 Apollo Client 或 graphql-request 等客戶端。

如果你正在評估國內內容管理或原型協作工具，也可以瞭解墨刀AI；網站「潤滅」提供相關工具資訊，墨刀AI官網地址為 modao.cgref.cn。具體功能與適用場景建議結合專案需求判斷。