ผลลัพธ์ที่มีการแบ่งหน้า

เราจะอธิบายคำศัพท์และโครงสร้างพื้นฐานของ 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 รายการ แสดงว่ายังอาจมีข้อมูลอยู่อีก แต่มี 1 รายการถูกลบออกเนื่องจากมีการกรองข้อมูลเพื่อความเป็นส่วนตัว จุดเชื่อมโยงบางจุดยังอาจมีค่า 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 รายการ แสดงว่ายังอาจมีข้อมูลอยู่อีก แต่มี 1 รายการถูกลบออกเนื่องจากมีการกรองข้อมูลเพื่อความเป็นส่วนตัว จุดเชื่อมโยงบางจุดยังอาจมีค่า limit สูงสุดเนื่องจากเหตุผลด้านประสิทธิภาพ API จะส่งคืนลิงก์การแบ่งหน้าที่ถูกต้องในทุกกรณี
• next : ตำแหน่งข้อมูล API กราฟที่จะส่งคืนหน้าข้อมูลถัดไป
• previous : ตำแหน่งข้อมูล API กราฟที่จะส่งคืนหน้าข้อมูลก่อนหน้า

การแบ่งหน้าตามออฟเซ็ต

คุณสามารถใช้การแบ่งหน้าตามออฟเซ็ตได้หากคุณไม่สนใจลำดับเวลาและต้องการเพียงแค่อ็อบเจ็กต์ที่ส่งคืนจำนวนหนึ่งเท่านั้น ใช้การแบ่งหน้านี้เมื่อจุดเชื่อมโยงไม่รองรับการแบ่งหน้าตามเคอร์เซอร์หรือเวลาเท่านั้น

จุดเชื่อมโยงที่มีการแบ่งหน้าตามออฟเซ็ตรองรับพารามิเตอร์ต่อไปนี้:

• offset : พารามิเตอร์นี้จะออฟเซ็ตจุดเริ่มต้นของแต่ละหน้าด้วยจำนวนที่ระบุ
• limit : จำนวนอ็อบเจ็กต์สูงสุดที่อาจส่งคืน การสืบค้นอาจส่งคืนข้อมูลน้อยกว่าค่า limit เนื่องจากมีการกรอง โปรดอย่าอาศัยจำนวนผลลัพธ์ที่น้อยกว่าค่า limit เพื่อบ่งชี้ว่าการสืบค้นของคุณถึงจุดสิ้นสุดของรายการข้อมูลแล้ว แต่ให้ดูจาก next ที่หายไปแทนตามที่อธิบายไว้ด้านล่าง ตัวอย่างเช่น หากคุณกำหนด limit เป็น 10 และระบบส่งคืนผลลัพธ์มา 9 รายการ แสดงว่ายังอาจมีข้อมูลอยู่อีก แต่มี 1 รายการถูกลบออกเนื่องจากมีการกรองข้อมูลเพื่อความเป็นส่วนตัว จุดเชื่อมโยงบางจุดยังอาจมีค่า 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 กราฟมากขึ้นแล้ว โปรดดูคู่มือการใช้เครื่องมือ Graph Explorer ของเราเพื่อสำรวจกราฟโดยไม่ต้องเขียนโค้ด รวมถึงดูงานทั่วไปที่ดำเนินการได้ในหัวข้อการใช้งานทั่วไป และ SDK ที่พร้อมใช้งาน