合作夥伴 API 分頁：如何可靠地讀取全部紀錄

一頁資料不等於全數紀錄

合作夥伴的清單 API 即使回傳成功，也可能只交出其中一頁。GitHub REST API 以 Link 標頭的 next 關係指出下一頁；Microsoft Graph 則在回應內提供 @odata.nextLink。兩者只是不同供應商的例子，不能混用語法。中小企在承諾資料匯入完成前，應先記下該端點真正的續頁訊號和終止條件。HTTP 200、畫面上看似填滿的一頁或一個合理的筆數，都不足以證明已讀取全數紀錄。把端點規則寫進整合規格，並保留實際回應範例供覆核。

分頁的重點不只是寫一個取下一頁的迴圈，還包括收齊資料後准許哪些業務動作。庫存資料可能影響可售數量，客戶名單可能影響支援工作，預約匯出可能用於通知。若程序在中途悄悄停止，而儀表板仍顯示「成功」，員工便會根據殘缺資料行事。應定義完成紀錄，列明端點、篩選條件、擷取時段、跟隨頁數、接納的唯一紀錄及未解決錯誤。未完成的匯入必須明確標示，不能讓下游工作把它當作完整快照。空白頁也可能源自錯誤請求，而非真的沒有資料。

依供應商的續頁規則行事

應把供應商交來的下一頁網址或權杖視為不透明指示。Microsoft Graph 指示客戶端持續使用 @odata.nextLink 提供的網址，直至回應不再包含該欄位；GitHub 則以 Link 標頭的 next 網址表示可繼續讀取。不要假設頁碼必然連續、用算術自行組裝下一個權杖，或把 Graph 的規則套到 GitHub。API 可能限制每頁大小，也可能日後更改續頁格式。每次請求仍須遵守相同的授權及端點規則，避免把權杖送往無關主機。

匯入前，先與供應商確認甚麼欄位可作穩定紀錄身分。例如不變的產品 ID 可作本地更新鍵；顯示名稱會更改，也可能重複，不宜作唯一鍵。若 API 提供更新時間，應把它保存為來源資料，不能假設它代表全域一致的快照。分開保存來源 ID、擷取時間、來源更新時間（如有）及匯入批次 ID，團隊才可分辨跨頁重現的同一項目，與名稱相近的兩項不同資料。往後核對時，也能追溯每個值來自哪一批。

讓失敗批次可以安全續跑

網絡中斷後，不應讓操作員猜測哪些資料已經寫入資料庫。只有當整頁資料通過驗證並完成提交，才更新進度。檢查點須包括已完成的續頁位置、查詢及篩選條件，以及所屬匯入批次。若供應商提供下一頁網址，應把它當作可能含敏感權杖的操作狀態妥善保存。重啟時，應依該供應商的文件重試同一頁或從可靠檢查點續跑。切勿先推進檢查點、後提交資料；一旦中間失敗，就會留下普通重試補不回的缺口。

Microsoft Graph 的分頁文件特別提醒：對某些大型目錄結果，重試回應產生的權杖未必可供後續頁面使用；其建議是沿用上一次非重試成功回應的續頁資訊。這是 Graph 的特定條件，不是所有 API 的通則。對其他合作夥伴整合，應直接測試該供應商的重試語義，並保留足夠狀態來重複它預期的請求。只有在供應商規格及自己的測試均證實適用時，才把這類特殊處理寫進操作手冊。

處理讀取期間持續變動的資料

分頁清單不會自動成為供應商資料庫的凍結快照。當客戶端讀取第二頁時，來源可能新增、刪除或改動紀錄排序。以位移頁碼讀取時，同一筆資料可能重複出現，也可能被跳過；續頁權杖或可減少部分風險，但本身不保證快照隔離。應查閱端點有否聲明快照、變更資料流、穩定排序鍵或更新時間篩選。若沒有，就應把匯入描述為盡力遍歷，並安排再次核對。不可單憑「已讀完所有頁」就聲稱取得某一時點的精確副本。

例如供應商產品清單整天都在變。可以先按供應商產品 ID 把各頁資料放進暫存表，之後與上一個已接納批次的 ID 和更新標記比較；若項目突然大幅減少或出現不明缺口，先調查，再供員工查看可售資訊。若供應商提供增量端點，應依其文件使用游標或時間範圍，並明訂重疊時段及去重規則。重疊讀取只是可選的防漏措施，並非所有 API 的已量度標準。若來源既無筆數也無可靠更新標記，至少與供應商抽查已知紀錄，並保留不確定性。

用一宗匯入例子作決定

假設本地分銷商向香港商店提供產品更新 API。測試請求回傳一頁資料及下一頁網址，端點文件指示一直跟隨網址，直至網址消失。商店先記錄批次 ID 和原來的篩選條件，驗證每項產品 ID 及價格欄位，再把每頁資料與檢查點一併提交。模擬在第三頁後中斷時，程序按文件指定的位置續跑，並以產品 ID 更新現有紀錄。同一產品再次出現，只更新一筆本地資料，不會新增重複項。此處頁數純屬測試例子，並非任何真實供應商的頁數或效能數據。

商店之後要先查看批次摘要，才把新目錄交給員工使用。若下一頁網址消失是因為按文件已到最後一頁，批次才可視為完成。若請求失敗、回應無法解析，或重要紀錄未通過驗證，批次仍屬未完成。若供應商有正式提供總筆數，而結果不吻合，也要先查明原因。操作員可比較新舊批次的來源 ID，判斷大量刪除是否真實業務變化。關鍵決定是資料何時足夠可靠，可供下游工作使用，而非程式有沒有拋出例外。

驗收失敗情況並交接

驗收時，準備一組身分和預期結果已知的小型測試資料，涵蓋多於一頁、最後一頁、重複身分、已改動紀錄，以及取回頁面後但提交前發生故障。確認續跑後沒有漏項，也沒有多出本地紀錄。格式錯誤的續頁資訊及授權失敗應分開測試，兩者都不能當作清單結束。若供應商有測試環境，應在那裏驗證真正的標頭或回應格式。本地模擬可補足邊界情況，卻不能證明正式服務的排序、權杖期限及重試規則相同。

應指定有人維護供應商端點規格，並指定操作角色覆核未完成批次；小團隊可由同一人兼任不同職責。記下檢查點位置、安全重跑方法、已接納批次的比較方式，以及供應商更改 API 時的聯絡人。給業務同事看的摘要要如實寫明最後一次完整匯入時間、資料範圍及未解決例外。若來源無法支援完整匯入，就在內部清楚標示資料已過時，或暫停依賴該資料的決定。這樣分頁才是一項受控的資料流程，而不是出問題後才被發現的隱藏細節。

最後還須分清「這次沒有見到」與「來源已刪除」。若一次遍歷沒有某個產品 ID，除非供應商保證該批是完整而具權威性的快照，否則不要立即從商店刪掉該產品。先檢查端點是否排除了停用項目、查詢條件有否改動，以及供應商有否正式提供刪除標記。遇到可疑的大幅減少時，應保留上一個已接納狀態供員工調查。若清單本來就只涵蓋部分資料，只更新實際讀到的紀錄，並另訂移除流程。這可避免暫時的分頁缺口變成難以逆轉的業務動作，也讓營運人員能向供應商提出準確問題：端點內缺席是否代表產品真的不存在，還是只代表不在這次結果範圍內？