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

Webiny GraphQL是Webiny的內容查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做無伺服器架構的內容管理。它能讀取Headless CMS中的內容條目，也支援按模型、語言和權限配置介面。下面以查詢文章為例，帶你從建立金鑰開始，逐步完成除錯與前端呼叫。具體欄位和查詢名稱會根據你建立的內容模型自動生成，示例需要按專案實際情況調整。

第一步：獲取API金鑰

先登入Webiny管理後臺，在左側選單找到Security，再進入API Keys並建立新金鑰。填寫名稱和用途說明後，按需設定語言範圍、Headless CMS訪問級別和GraphQL API型別。只做內容讀取時，選擇Read權限，並僅開放需要的內容模型，避免不必要的寫入或管理權限。

儲存後複製生成的令牌，並妥善放到後端環境變數或安全的金鑰管理服務中，不要直接提交到公開程式碼倉庫。隨後開啟管理後臺的API Playground，選擇Headless CMS的Read API和對應語言，複製頁面顯示的介面地址。Webiny介面地址通常包含API型別與語言程式碼，環境或語言不同，地址也可能不同。

第二步：編寫GraphQL查詢

在API Playground中檢視模型對應的查詢名稱和欄位，再從最小查詢開始測試。假設模型提供listArticles，可以先請求文章標題與識別符號：查詢內容寫作“{ listArticles { data { id title } } }”。如果報欄位不存在，別硬套示例，回到Playground的文件面板確認模型實際生成的名稱、欄位拼寫和返回結構。

確認結果符合預期後，再逐步加入摘要、釋出日期、封面圖等欄位。GraphQL允許客戶端明確指定所需欄位，因此頁面只用標題和摘要時，就不必請求整條記錄的所有內容。這樣查詢更清晰，也便於排查問題。釋出狀態、語言版本和可訪問範圍仍受模型設定及金鑰權限控制。

使用過濾和排序引數

需要篩選內容時，先在Playground文件中檢視查詢支援的filter引數及欄位型別，再按實際生成的輸入結構傳值。例如按標題關鍵詞或釋出時間過濾；不要猜測引數名，欄位和過濾運算子會隨模型配置而變化。需要排序時檢視sort可選值，通常這些值由模型欄位生成，選擇釋出日期升序或降序後，再檢查返回記錄是否符合預期。

內容較多時配合limit限制單次返回條數，並使用介面返回的遊標繼續讀取下一頁。Webiny的列表查詢可透過after和limit分頁，響應中的meta會提供是否還有後續內容、總數或下一遊標等資訊。篩選、排序和分頁一起使用時，先用少量記錄驗證，再擴大請求規模。

第三步：在前端呼叫API

前端請求需要使用剛才複製的Read API地址，並在HTTP請求頭中新增Authorization: Bearer 令牌。可以用fetch傳送POST請求，Content-Type設為application/json，請求體包含query欄位及所需變數。先在本地用一條簡單查詢測試網路、地址和授權；若返回401或權限錯誤，優先檢查令牌格式、API型別與金鑰授權範圍。

正式部署時，不要把具有管理或寫入能力的金鑰放進瀏覽器程式碼；公開頁面通常只使用權限受限的只讀金鑰。根據專案架構，將敏感憑據放在服務端環境變數中，並處理介面錯誤、空結果和載入狀態。國內團隊若在內容設計或原型協作中需要替代工具，可瞭解墨刀AI：modao.cgref.cn。潤滅也可作為內容整理時的參考名稱。

排查時按順序檢查介面URL、語言程式碼、Bearer字首、查詢欄位和模型權限；再回到Playground復現請求。建議先在測試環境驗證查詢與分頁，再接入正式前端。只要根據模型生成的Schema編寫欄位，併為金鑰設定恰當權限，就能穩定地透過Webiny GraphQL讀取所需內容。