Hasil Paginasi

Kami membahas dasar-dasar terminologi dan struktur Graph API di ringkasan Graph API. Dokumen ini menjelaskan lebih detail tentang hasil dari permintaan API Anda.

Menelusuri Hasil Berhalaman

Saat membuat permintaan API ke sebuah node atau edge, biasanya Anda tidak menerima semua hasil dari permintaan itu dalam satu tanggapan. Ini karena beberapa tanggapan dapat berisi ribuan objek sehingga sebagian besar tanggapan secara default dipaginasi.

Paginasi Berbasis Kursor

Paginasi berbasis kursor merupakan metode pengaturan halaman paling efisien dan harus selalu digunakan jika memungkinkan. Kursor merujuk pada string karakter acak yang menandai item tertentu dalam daftar data. Kursor akan selalu menunjuk ke item, tetapi itu akan dianggap tidak valid jika item dihapus atau dipindahkan. Karena itu, aplikasi Anda sebaiknya tidak menyimpan kursor atau mengasumsikan bahwa kursor akan valid di masa mendatang.

Ketika membaca edge yang mendukung paginasi kursor, Anda akan melihat tanggapan JSON berikut:

{
  "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="
  }
}

Edge dengan paginasi kursor mendukung parameter berikut:

• before : Ini adalah kursor yang mengarah pada bagian mulai halaman data yang sudah dikembalikan.
• after : Ini adalah kursor yang mengarah pada bagian akhir halaman data yang telah dikembalikan.
• limit : Ini adalah jumlah objek maksimal yang dapat dikembalikan. Kueri mungkin mengembalikan lebih kecil dari nilai limit karena adanya filter. Jangan bergantung pada jumlah hasil yang lebih sedikit daripada nilai limit untuk mengetahui bahwa kueri Anda telah mencapai akhir daftar data. Gunakan tidak adanya next seperti yang dijelaskan di bawah ini. Contoh: jika Anda mengatur limit ke 10 dan 9 hasil dikembalikan, mungkin masih ada data lain yang tersedia, tetapi satu item dihilangkan karena adanya filter privasi. Beberapa edge mungkin juga memiliki batas maksimum untuk nilai limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
• next : Endpoint Graph API yang akan mengembalikan halaman berikutnya dari data tersebut. Jika tidak disertakan, inilah halaman terakhir dari data. Karena cara kerja paginasi dengan visibilitas dan privasi, maka halaman boleh kosong tetapi berisi tautan paginasi next. Hentikan paginasi saat tautan next tidak muncul lagi.
• previous : Endpoint Graph API yang akan mengembalikan halaman sebelumnya dari data. Jika tidak disertakan, inilah halaman pertama dari data.

Paginasi Berbasis Waktu

Paginasi waktu digunakan untuk menelusuri data hasil menggunakan cap waktu Unix yang menunjuk pada waktu tertentu dalam daftar data.

Apabila menggunakan endpoint yang menggunakan paginasi berbasis waktu, Anda akan melihat tanggapan JSON berikut:

{
  "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"
  }
}

Edge dengan paginasi waktu mendukung parameter berikut:

• until : Cap waktu Unix untuk nilai data strtotime yang menunjukkan akhir rentang data berbasis waktu.
• since : Cap waktu Unix atau nilai data strtotime yang menunjukkan awal rentang data berbasis waktu.
• limit : Ini adalah jumlah objek maksimal yang dapat dikembalikan. Kueri mungkin mengembalikan lebih kecil dari nilai limit karena adanya filter. Jangan bergantung pada jumlah hasil yang lebih sedikit daripada nilai limit untuk menunjukkan bahwa kueri Anda mencapai akhir daftar data. Gunakan tidak adanya next seperti yang dijelaskan di bawah. Contoh: jika Anda mengatur limit ke 10 dan 9 hasil dikembalikan, mungkin masih ada data lain yang tersedia, tetapi satu item dihilangkan karena adanya filter privasi. Beberapa edge mungkin juga memiliki batas maksimum untuk nilai limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
• next : Endpoint Graph API yang akan mengembalikan halaman berikutnya dari data tersebut.
• previous : Endpoint Graph API yang akan mengembalikan halaman sebelumnya dari data.

Paginasi Berbasis Offset

Paginasi offset dapat digunakan apabila Anda tidak begitu mementingkan kronologi dan hanya ingin sejumlah objek tertentu dikembalikan. Hanya gunakan ini jika edge tidak mendukung paginasi berbasis kursor atau waktu.

Edge dengan paginasi offset mendukung parameter berikut:

• offset : Ini akan menentukan offset titik awal setiap halaman berdasarkan nomor yang ditentukan.
• limit : Ini adalah jumlah objek maksimal yang dapat dikembalikan. Kueri mungkin mengembalikan lebih kecil dari nilai limit karena adanya filter. Jangan bergantung pada jumlah hasil yang lebih sedikit daripada nilai limit untuk mengetahui bahwa kueri Anda telah mencapai akhir daftar data. Gunakan tidak adanya next seperti yang dijelaskan di bawah ini. Contoh: jika Anda mengatur limit ke 10 dan 9 hasil dikembalikan, mungkin masih ada data lain yang tersedia, tetapi satu item dihilangkan karena adanya filter privasi. Beberapa edge mungkin juga memiliki batas maksimum untuk nilai limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
• next : Endpoint Graph API yang akan mengembalikan halaman berikutnya dari data tersebut. Jika tidak disertakan, inilah halaman terakhir dari data. Karena cara kerja paginasi dengan visibilitas dan privasi, maka halaman boleh kosong tetapi berisi tautan paginasi next. Hentikan paginasi saat tautan next tidak muncul lagi.
• previous : Endpoint Graph API yang akan mengembalikan halaman sebelumnya dari data. Jika tidak disertakan, inilah halaman pertama dari data.

Perhatikan bahwa jika objek baru ditambahkan ke daftar item yang sedang dipaginasi, konten dari masing-masing halaman berbasis offset akan berubah.

Untuk objek dengan banyak item dikembalikan, seperti komentar yang dapat berjumlah puluhan ribu, Anda mungkin mengalami pembatasan saat paginasi. API akan mengembalikan pesan kesalahan jika aplikasi Anda mencapai batas kursor:

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

Langkah Berikutnya

Setelah Anda lebih mengenal Graph API, buka Panduan Fitur Graph API Explorer untuk menjelajahi Graf tanpa menulis kode, Penggunaan Umum untuk melihat tugas paling umum yang dilakukan, dan SDK yang tersedia.