分頁的結果

圖形 API 總覽已大致介紹圖形 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：將傳回下一頁資料的圖形 API 端點。如果未包含此參數，代表傳回資料為最後一頁。由於分頁作業配合能見度和隱私設定的方式，有可能某頁為空白，但卻包含 next 的分頁連結。當 next 連結不再出現時，請停止分頁。
• previous：將傳回上一頁資料的圖形 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：將傳回下一頁資料的圖形 API 端點。
• previous：將傳回上一頁資料的圖形 API 端點。

位移型分頁

當您不在乎時間順序，而只想要傳回特定數目的物件時，可使用位移分頁。只有當關係連線不支援游標型或時間型分頁時，才使用位移型分頁。

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

• offset：依指定數目，將每一頁開頭位移。
• limit：這是可能傳回的物件數量上限。由於過濾的緣故，查詢時傳回的物件數量可能低於 limit 的值。請不要根據結果數量少於 limit 值的情形，而標示查詢已達到資料清單的結尾處，請改為使用未包含 next 的方式，如下所述。例如，如果您將 limit 設為 10，而系統傳回 9 筆結果，可能仍有更多資料可使用，但因為隱私過濾功能，而有一個項目遭移除。基於效能因素，某些關係連線的 limit 值同樣具有上限。無論什麼情況，API 都會傳回正確的分頁連結。
• next：將傳回下一頁資料的圖形 API 端點。如果未包含此參數，代表傳回資料為最後一頁。由於分頁作業配合能見度和隱私設定的方式，有可能某頁為空白，但卻包含 next 的分頁連結。當 next 連結不再出現時，請停止分頁。
• previous：將傳回上一頁資料的圖形 API 端點。如果未包含此參數，代表傳回資料為第一頁。

請注意，如果將新的物件加入分頁中的項目清單，每個位移型頁面的內容都會變更。

如果物件傳回許多項目，例如數萬則留言，則可能會在分頁時受到限制。當應用程式已達到游標限制時，API 會傳回錯誤：

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

後續步驟

現在，您對於圖形 API 已經更加熟悉，請前往我們的圖形測試工具指南，探索不需撰寫程式碼的圖形、用於查看最常執行工作的常見用途，以及可用的 SDK。