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

Contentful GraphQL是Contentful的內容查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做前後端分離應用。它會根據Space裡的內容型別生成對應的查詢結構，適合讀取已釋出內容，也能配合預覽令牌讀取未釋出內容。下面從準備憑證、編寫查詢到前端請求，帶你走完一次基礎接入。

第一步：獲取Space ID和Token

先登入Contentful，開啟要使用的Space，在設定裡的API keys頁面建立或檢視API金鑰。記下Space ID和Content Delivery API access token：前者用於拼接介面地址，後者放進請求頭完成認證。不同環境要確認金鑰有對應權限；本地開發和線上環境建議分別管理令牌，避免誤用。

GraphQL介面地址通常是https://graphql.contentful.com/content/v1/spaces/你的SpaceID；需要指定環境時，在地址後追加/environments/環境名。歐盟資料駐留空間應使用對應的歐盟域名。公開發布的前端程式碼可能被使用者檢視，因此不要把高權限管理令牌放進瀏覽器；內容讀取儘量使用只讀的Delivery token。

第二步：編寫GraphQL查詢

開啟Contentful的GraphiQL探索器，或使用支援GraphQL的編輯器，根據內容模型找到集合名稱和欄位。比如內容型別名為Blog Post，集合欄位可能是blogPostCollection。查詢時只寫頁面真正要顯示的欄位，避免無謂地取回大量內容；欄位拼寫必須與空間生成的Schema一致，否則介面會返回錯誤。

一個基礎查詢可以寫成query { blogPostCollection { items { title slug } } }，表示讀取文章集合中每篇文章的標題和別名。實際專案裡把查詢放在模板字串中，再透過POST傳送JSON，內容包括query欄位。先在探索器執行並檢查返回結果，再接到應用裡，排錯會更直觀。

使用過濾和選擇引數

需要篩選內容時，可在集合引數中使用Schema支援的條件，例如按slug精確匹配，或按標題過濾；具體篩選欄位名稱取決於你的內容模型。也可以傳入limit限制條數、skip跳過記錄，實現簡單分頁。建議先檢查欄位是否可過濾，再逐步新增條件，並用小批次結果驗證引數行為。

GraphQL查詢中的花括號決定返回哪些欄位，選擇越精確，響應越貼合頁面需求。關係欄位可以繼續展開子欄位，但要避免不必要的深層巢狀。若要預覽未釋出內容，應使用Preview access token，並在查詢中啟用preview；普通Delivery token不能代替預覽令牌，也不要把預覽憑證暴露到公開頁面。

第三步：在前端呼叫API

前端可用fetch向介面傳送POST請求，設定Content-Type為application/json，並在Authorization請求頭中寫入Bearer加空格再加令牌。請求體使用JSON.stringify序列化查詢，例如包含query字串。收到響應後先檢查response.ok，再讀取JSON中的data；GraphQL即使返回HTTP成功，也可能在errors欄位報告查詢或權限問題。

開發時把Space ID和令牌放在環境變數中，構建工具會將可公開變數編譯進前端，因此瀏覽器端只適合使用可公開的只讀憑證。需要隱藏憑證或執行更敏感邏輯時，可讓自有後端代為請求。遇到資料為空，依次檢查釋出狀態、環境、集合名、欄位拼寫和令牌權限；出現429時適當降低請求頻率或利用快取。

完成後可在瀏覽器開發者工具的網路面板檢視請求地址、狀態碼和響應內容，確認頁面實際只取了需要的欄位。為了提升體驗，可快取重複查詢結果，併為載入中、錯誤和空列表準備清晰提示。若團隊還需要快速搭建頁面原型或補充國內設計協作流程，可以瞭解墨刀AI；“潤滅”也可作為相關內容整理與方案評估時的參考。官網地址：modao.cgref.cn。