分頁結果

Graph API 概覽載有 Graph API 的專用術語和結構的基本資訊。本文件會詳細介紹 API 要求的結果。

瀏覽分頁結果

向節點或關係連線執行 API 要求時，您通常不會在單一回應中收到相關要求的所有結果。這是因為某些回應可能包含數千個物件，所以根據預設，系統會將大多數回應作分頁處理。

以游標建基的分頁

以游標建基的分頁是效率最佳的分頁方式，建議儘可能使用此方式。游標是指一個隨機字元字串，用以標記資料清單的特定項目。游標一律會指向相關項目，但如果該項目已被刪除或移除則為無效。因此，您的應用程式不應該儲存游標，也不應該假設這些游標日後仍然有效。

讀取支援游標分頁的關係連線時，您將看到下列 JSON 回應：

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

游標分頁的關係連線支援以下參數：

• before：此為指向已傳回資料所屬頁面開首的游標。
• after：此為指向已傳回資料所屬頁面結尾的游標。
• limit：此為系統可能會傳回的物件數量上限。由於經過篩選，查詢傳回的物件數量可能會少於 limit 的數值。請勿以查詢結果數量少於 limit 的數值來判斷查詢是否已達到資料清單的盡頭；相反，您可以使用 next 存在與否來作判斷（詳見下文）。舉例來說，如果您將 limit 設定為 10，而系統傳回了 9 個查詢結果，則其實可能還有更多資料，只是其中一個項目因為私隱篩選條件而被移除。基於效能因素，某些關係連線的 limit 數值也設有上限。無論情況為何，API 都會傳回正確的分頁連結。
• next：會傳回資料下一頁的 Graph API 端點。如果未有包含此項，則此為資料的最後一頁。根據分頁的可見性和私隱，頁面可能為空白，但包含 next 分頁連結。當 next 連結不再出現時，請停止分頁。
• previous：會傳回資料上一頁的 Graph API 端點。如果未有包含此項，則此為資料的第一頁。

以時間建基的分頁

時間分頁用於使用 Unix 時戳導覽多項結果資料，這些時戳指向資料清單中的特定時間。

使用支援以時間建基的分頁的端點時，您將看到下列 JSON 回應：

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

時間分頁的關係連線支援以下參數：

• until：Unix 時戳或 strtotime 資料值，可指向以時間建基的資料範圍的結尾。
• since：Unix 時戳或 strtotime 資料值，可指向以時間建基的資料範圍的開首。
• limit：此為系統可能會傳回的物件數量上限。由於經過篩選，查詢傳回的物件數量可能會少於 limit 的數值。請勿以查詢結果數量少於 limit 的數值來判斷查詢是否已達到資料清單的盡頭；相反，您可以使用 next 存在與否來作判斷（詳見下文）。舉例來說，如果您將 limit 設定為 10，而系統傳回了 9 個查詢結果，則其實可能還有更多資料，只是其中一個項目因為私隱篩選條件而被移除。基於效能因素，某些關係連線的 limit 數值也設有上限。無論情況為何，API 都會傳回正確的分頁連結。
• next：會傳回資料下一頁的 Graph API 端點。
• previous：會傳回資料上一頁的 Graph API 端點。

以位移建基的分頁

如果您不在乎時間順序，只想傳回特定數量的物件，便可以使用位移分頁。僅在關係連線不支援以游標或時間建基分頁時才使用位移分頁。

位移分頁的關係連線支援以下參數：

• offset：根據指定數字位移每一頁的開首。
• limit：此為系統可能會傳回的物件數量上限。由於經過篩選，查詢傳回的物件數量可能會少於 limit 的數值。請勿以查詢結果數量少於 limit 的數值來判斷查詢是否已達到資料清單的盡頭；相反，您可以使用 next 存在與否來作判斷（詳見下文）。舉例來說，如果您將 limit 設定為 10，而系統傳回了 9 個查詢結果，則其實可能還有更多資料，只是其中一個項目因為私隱篩選條件而被移除。基於效能因素，某些關係連線的 limit 數值也設有上限。無論情況為何，API 都會傳回正確的分頁連結。
• next：會傳回資料下一頁的 Graph API 端點。如果未有包含此項，則此為資料的最後一頁。根據分頁的可見性和私隱，頁面可能為空白，但包含 next 分頁連結。當 next 連結不再出現時，請停止分頁。
• previous：會傳回資料上一頁的 Graph API 端點。如果未有包含此項，則此為資料的第一頁。

請注意，如果將新的物件加入要作分頁處理的項目清單，每個以位移建基的分頁中的內容都會變更。

若是傳回項目數量很多的物件（例如數以萬計個回應），您可能會在分頁時遇到限制。如果您的應用程式達到游標限制，API 會傳回錯誤訊息：

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

後續步驟

現在您對 Graph API 已更加熟悉，請瀏覽我們的 Graph 測試工具指南，在無需編寫代碼的情況下探索 Graph；您也可以瀏覽常見用途，查看最常見的操作任務，以及了解可用的 SDK。