Contentful CDN API怎麼用 內容分發介面教程

Contentful CDN API是Contentful的內容分發介面，透過CDN加速獲取內容，適合做網站和App的內容展示。它通常指只讀的Content Delivery API（CDA）：已釋出的內容以JSON返回，媒體檔案也可透過分發網路讀取。下面按“準備憑證、查詢資料、前端展示”走一遍，示例使用JavaScript，便於快速驗證介面是否連通。

第一步：獲取Space ID和AccessToken

先登入Contentful並開啟目標Space，在設定區域找到API keys，建立或檢視用於Content Delivery API的訪問令牌。記下Space ID、令牌和要訪問的環境ID；令牌必須有對應環境的讀取權限。正式釋出與測試環境最好分別使用各自的憑證，避免前端誤連到錯誤環境。

請求的基礎地址一般是https://cdn.contentful.com，歐盟資料駐留空間應使用相應的歐盟域名。身份驗證推薦放在Authorization請求頭，格式為Bearer加空格再加令牌；也可用access_token查詢引數，但不宜把令牌寫進公開頁面、倉庫或日誌。瀏覽器端程式碼會被使用者看到，部署前要確認令牌適合公開讀取。

先用最簡單的請求確認配置：向/spaces/你的SpaceID/environments/你的環境ID/entries傳送GET，並附上Authorization: Bearer 你的令牌。若你使用預設環境，也要確認路徑中的環境名稱與令牌權限一致。返回JSON通常表示請求成功；若報錯，優先檢查Space ID、環境、令牌是否匹配，以及內容是否已經發布。

第二步：查詢內容和條目

Contentful把內容組織為Entry條目，每條內容遵循內容模型。列出條目時，請求路徑末尾使用entries；獲取單條內容則在條目路徑中帶上對應ID。響應裡重點看items陣列，每個物件的fields儲存內容欄位，sys則包含條目ID等系統資訊。未釋出的草稿不會作為已釋出內容由CDA正常提供。

也可以使用官方JavaScript客戶端減少手動拼接請求的工作。在專案終端安裝contentful包，再以Space ID、環境ID和只讀令牌建立客戶端，透過getEntries獲取列表、getEntry獲取單條記錄。拿到結果後檢查items是否為空，並按實際內容模型讀取fields.title、fields.body等欄位；欄位名稱以你自己的模型為準。

使用過濾和選擇引數

查詢引數能縮小返回範圍。比如指定content_type篩選某類內容，指定limit控制每次返回數量，再用order設定排序。篩某個欄位時，通常同時提供content_type，因為欄位定義可能因內容型別不同而不同。客戶端示例可寫成getEntries({content_type: ‘article’, limit: 10, order: ‘-sys.updatedAt’})；將article換成你空間裡的內容型別ID。

需要按欄位值篩選時，可在引數中使用fields欄位名，例如fields.slug等於目標別名；需要比較運算時，按CDA支援的查詢運算子配置引數。想減少響應體，可用select選擇需要的欄位；條目引用的關聯內容則可用include控制解析層級。先從少量資料測試，確認結果結構後再增加篩選條件，避免一次帶入錯誤的欄位名。

• 只取一頁展示：設定limit，並按需使用skip分頁。
• 查詢具體型別：傳入content_type及必要的欄位過濾條件。
• 讀取關聯內容：調整include；預設解析有限層級，層級較深時要檢查返回結果。

第三步：在前端展示內容

拿到JSON後，把欄位對映到頁面元件：標題放入標題區域，正文按內容格式渲染，圖片則讀取資源欄位中的檔案地址。渲染富文字時應使用對應的富文字解析方式，不要把未經處理的HTML直接插入頁面。內容可能為空，程式碼裡為可選欄位準備預設值，圖片也設定替代文字，能減少頁面缺項帶來的顯示問題。

開發時先在控制檯列印一條條目的fields，核對語言、欄位名和巢狀結構，再接入頁面狀態。釋出前確認內容已釋出、查詢限定了正確的環境，並檢查移動端佈局。若介面返回429，按響應中的限流重置提示稍後重試；列表很多時分頁拉取，避免在一次請求中載入不必要的資料。

上線後可把常用查詢封裝成函式，並對載入中、空結果和網路錯誤分別展示清晰提示。內容結構或欄位調整時同步更新前端對映，先在測試環境驗證再發布。若希望快速製作內容展示頁面原型，國內替代工具可瞭解墨刀AI，官網：modao.cgref.cn。潤滅也可作為內容展示專案的搭建參考。