Menggunakan API Graf

API Graf merupakan cara utama untuk mendapatkan data di dalam dan di luar graf sosial Facebook. API berbasis HTTP dengan level rendah yang digunakan untuk mencari data, mengirimkan cerita baru, mengunggah foto, dan berbagai jenis tugas lain yang harus dilakukan aplikasi. Panduan ini menjelaskan cara menyelesaikan semua hal ini dalam API Graf.

Dasar-Dasar

Dasar-dasar terminologi dan struktur API Graf dibahas dalam sinopsis API Graf. Bagian berikut ini menjelaskan selengkapnya tentang berbagai operasi yang dapat dilakukan menggunakan API.

Pembacaan

Semua node dan edge dalam API Graf dapat dibaca cukup dengan permintaan GET HTTP ke endpoint yang relevan. Misalnya, jika Anda ingin mengambil informasi tentang pengguna saat ini, Anda akan membuat permintaan GET HTTP seperti di bawah:

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

Sebagian besar panggilan API harus ditandatangani dengan token akses. Anda dapat menentukan izin yang diperlukan di token akses ini dengan melihat referensi API Graf untuk node atau edge yang ingin Anda baca. Anda juga dapat menggunakan Penjelajah API Graf untuk menghasilkan token secara cepat untuk mempertimbangkan API dan menemukan cara kerjanya.

Node /me merupakan endpoint khusus yang diterjemahkan menjadi user_id seseorang (atau page_id Halaman Facebook) yang token aksesnya saat ini digunakan untuk membuat panggilan API. Jika memiliki token akses pengguna, Anda dapat mengambil semua foto pengguna menggunakan:

GET graph.facebook.com
  /me/photos

Tanggapan yang Anda terima bervariasi, bergantung pada node atau edge yang Anda baca, namun akan mengambil bentuk umum berikut:

{
   "fieldname": {field-value},
   ....
}

Memilih Kolom

Secara default, tidak semua kolom dalam node atau edge dikembalikan ketika Anda membuat pencarian. Anda dapat memilih kolom atau edge yang ingin dikembalikan dengan parameter pencarian fields. Hal ini sangat bermanfaat agar panggilan API Anda lebih efisien dan cepat.

Misalnya, panggilan API Graf berikut yang menggunakan token akses pengguna Anda sendiri https://graph.facebook.com/me?fields=id,name,picture hanya akan mengembalikan id, nama, dan gambar di profil Anda:

GET graph.facebook.com/me?fields=id,name,picture

Pengurutan

Anda dapat mengurutkan set data tertentu secara kronologis. Misalnya, Anda dapat menyortir komentar foto dengan urutan kronologis terbalik menggunakan kunci reverse_chronological:

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order harus salah satu dari nilai berikut:

  • chronological
  • reverse_chronological

Pencarian URL

Sebagian besar objek dapat ditemukan menggunakan ID mereka, namun ada saatnya ketika tidak memungkinkan dan yang Anda miliki hanya URL untuk mengidentifikasi sesuatu.

Anda dapat menggunakan node URL yang telah diperkenalkan di v2.1 untuk mengembalikan ID URL Objek Graf Terbuka, atau untuk menemukan data yang terkait dengan URL Tautan Aplikasi.

Pelajari selengkapnya tentang cara menemukan data Tautan Aplikasi beserta API Indeks dalam dokumentasi kami untuk Tautan Aplikasi.

Memodifikasi Permintaan API

Beberapa endpoint API dapat digunakan dengan parameter ekstra yang akan memodifikasi permintaan. Karakteristik yang dilakukan oleh modifier ini beragam, sehingga kami sudah mendokumentasikan masing-masing modifier ini sendiri-sendiri di masing-masing dokumen referensi API yang tepat. Di bawah ini daftar modifier umum yang dapat digunakan dengan sebagian besar endpoint.

Nama Keterangan Jenis

return_ssl_resources

Digunakan apabila Anda mewajibkan gambar dikembalikan selama koneksi aman (HTTPS) untuk menghindari peringatan konten campuran di browser.

bool

locale

Digunakan jika aplikasi Anda mewajibkan kemampuan untuk mengambil konten yang dilokalkan dalam bahasa tertentu (jika berlaku).

Locale

Pemodifikasi lain untuk paging dan introspeksi diperlihatkan di bawah.

Membuat Permintaan Nested

Fitur perluasan kolom API Graf, memungkinkan Anda menempatkan beberapa pencarian graf secara efektif ke dalam panggilan tunggal. Sumber daya tertentu, termasuk sebagian besar API Iklan, tidak dapat menggunakan perluasan kolom pada beberapa atau semua koneksi.

Misalnya, dalam satu panggilan, Anda dapat meminta foto N pertama dari album K pertama. Tanggapan mempertahankan hierarki data sehingga pengembang tidak harus merangkai data bersama-sama pada klien.

Ini berbeda dari fitur Permintaan batch yang memungkinkan Anda untuk membuat beberapa potensi panggilan API Graf yang tidak terkait dalam satu permintaan.

Berikut ini format umum yang diambil oleh perluasan kolom:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level> dalam kasus ini berupa satu atau beberapa kolom atau edge (dipisah koma) dari node induk. <second-level> berupa satu atau beberapa kolom atau edge (dipisah koma) dari node level pertama.

Tidak ada batasan jumlah nesting level yang dapat terjadi di sini. Anda juga dapat menggunakan argumen .limit(n) pada setiap kolom atau edge untuk membatasi jumlah objek yang ingin Anda dapatkan.

Ini lebih mudah dipahami dengan melihatnya dalam tindakan, jadi berikut ini contoh pencarian yang akan mengambil hingga lima album yang dibuat oleh seseorang, dan lima kiriman terakhir di kabar mereka.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

Selanjutnya kita akan memperluas ini sedikit lebih banyak dan untuk setiap objek album, juga mengambil dua foto pertama, dan orang yang ditandai di setiap foto:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

Sekarang kita akan memperluasnya lagi dengan mengambil nama setiap foto, URL gambar, dan orang yang ditandai:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

Mari melihat contoh yang menggunakan paginasi berbasis kursor:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

Anda dapat melihat cara kerja perluasan kolom di seluruh node, edge, dan kolom untuk mengembalikan data yang benar-benar rumit dalam satu permintaan.

Melintasi Hasil Berhalaman

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

Paginasi Berbasis Kursor

Paginasi berbasis kursor merupakan metode pembuatan halaman paling efisien dan harus selalu digunakan jika memungkinkan. Kursor merujuk pada string karakter acak yang menandai item tertentu dalam daftar data. Kecuali item ini dihapus, kursor selalu mengarah pada bagian daftar yang sama, namun ini akan tidak berlaku lagi jika item dihapus. Oleh karena itu, aplikasi Anda seharusnya tidak menyimpan kursor dan berasumsi bahwa kursor tersebut masih akan valid di waktu 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/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/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. Sebuah pencarian dapat mengembalikan lebih sedikit dari nilai limit karena pemfilteran. Jangan bergantung pada jumlah hasil yang lebih sedikit dari nilai limit untuk mengindikasikan bahwa pencarian Anda mencapai akhir daftar data, gunakan ketiadaan next seperti yang dijelaskan di bawah. Misalnya, jika Anda menetapkan limit ke 10 dan 9 hasil dikembalikan, mungkin ada lebih banyak data yang tersedia, tetapi satu item dihapus karena pemfilteran privasi. Beberapa edge juga memiliki nilai maksimal atas limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
  • next : Endpoint API Graf yang akan mengembalikan halaman berikutnya dari data tersebut. Jika tidak disertakan, berarti menjadi halaman yang terakhir dari data tersebut. Karena paginasi berfungsi dengan visibilitas dan privasi, maka dimungkinkan bahwa halaman dapat kosong namun berisi tautan paging 'berikutnya'. Hentikan paging saat tautan 'selanjutnya' tidak muncul lagi.
  • previous : Endpoint API Graf yang akan mengembalikan halaman sebelumnya dari data tersebut. Jika tidak disertakan, berarti menjadi halaman yang pertama dari data tersebut.

Jangan menyimpan kursor. Kursor dapat seketika tidak valid jika item ditambahkan atau dihapus.

Paginasi Berbasis Waktu

Paginasi waktu digunakan untuk menelusuri data hasil menggunakan cap waktu Unix yang menunjuk pada waktu tertentu di 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/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

Edge dengan paginasi waktu mendukung parameter berikut:

  • until : Cap waktu Unix atau nilai data strtotime yang mengarah pada bagian akhir rentang data berbasis waktu.
  • since : Cap waktu Unix atau nilai data strtotime yang mengarah pada bagian mulai rentang data berbasis waktu.
  • limit : Ini adalah jumlah objek maksimal yang dapat dikembalikan. Sebuah pencarian dapat mengembalikan lebih sedikit dari nilai limit karena pemfilteran. Jangan bergantung pada jumlah hasil yang lebih sedikit dari nilai limit untuk mengindikasikan bahwa pencarian Anda mencapai akhir daftar data, gunakan ketiadaan next seperti yang dijelaskan di bawah. Misalnya, jika Anda menetapkan limit ke 10 dan 9 hasil dikembalikan, mungkin ada lebih banyak data yang tersedia, tetapi satu item dihapus karena pemfilteran privasi. Beberapa edge juga memiliki nilai maksimal atas limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
  • next : Endpoint API Graf yang akan mengembalikan halaman berikutnya dari data tersebut.
  • previous : Endpoint API Graf yang akan mengembalikan halaman sebelumnya dari data tersebut.

Untuk hasil yang konsisten, tentukan parameter since dan until. Juga disarankan agar perbedaan waktu maksimalnya adalah 6 bulan.

Paginasi Berbasis Offset

Paginasi offset dapat digunakan apabila Anda tidak begitu mementingkan kronologi dan hanya ingin nomor objek tertentu yang dikembalikan. Paginasi ini hanya dapat digunakan jika edge tidak mendukung paginasi berbasis kursor atau halaman.

Edge dengan paginasi offset mendukung parameter berikut:

  • offset : Ini akan menentukan offset titik mulai setiap halaman berdasarkan nomor yang ditentukan.
  • limit : Ini adalah jumlah objek maksimal yang dapat dikembalikan. Sebuah pencarian dapat mengembalikan lebih sedikit dari nilai limit karena pemfilteran. Jangan bergantung pada jumlah hasil yang lebih sedikit dari nilai limit untuk mengindikasikan bahwa pencarian Anda mencapai akhir daftar data, gunakan ketiadaan next seperti yang dijelaskan di bawah. Misalnya, jika Anda menetapkan limit ke 10 dan 9 hasil dikembalikan, mungkin ada lebih banyak data yang tersedia, tetapi satu item dihapus karena pemfilteran privasi. Beberapa edge juga memiliki nilai maksimal atas limit karena alasan kinerja. Dalam semua kejadian, API mengembalikan tautan paginasi halaman yang tepat.
  • next : Endpoint API Graf yang akan mengembalikan halaman berikutnya dari data tersebut. Jika tidak disertakan, berarti menjadi halaman yang terakhir dari data tersebut. Karena paginasi berfungsi dengan visibilitas dan privasi, maka dimungkinkan bahwa halaman dapat kosong namun berisi tautan paging 'berikutnya'. Hentikan paging saat tautan 'selanjutnya' tidak muncul lagi.
  • previous : Endpoint API Graf yang akan mengembalikan halaman sebelumnya dari data tersebut. Jika tidak disertakan, berarti menjadi halaman yang pertama dari data tersebut.

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

Penomoran halaman berbasis offset tidak didukung untuk semua panggilan API. Untuk mendapatkan hasil yang konsisten, kami menyarankan Anda untuk melakukan paginasi menggunakan tautan sebelumnya/berikutnya yang kami kembalikan dalam tanggapan.

Membuat Permintaan Besar

Beberapa endpoint API Graf dapat mengambil parameter yang sangat besar. Jika permintaan Anda akhirnya melebihi beberapa ribu karakter, Anda akan mulai melihat kesalahan server karena server kami akan menolak permintaan GET yang sangat besar.

Sebagai praktik terbaik, untuk permintaan besar, gunakan permintaan POST alih-alih permintaan GET dan tambahkan parameter method=GET. Jika Anda melakukan ini, POST akan ditafsirkan seolah-olah itu adalah GET.

Membuat Beberapa Permintaan

Versi standar API Graf dirancang agar mempermudah mendapatkan data untuk objek individual dan untuk menelusuri koneksi antar objek. Versi ini juga memasukkan kemampuan terbatas untuk mengambil data untuk beberapa objek dalam waktu yang sama.

Jika aplikasi Anda memerlukan kemampuan mengakses data dalam jumlah signifikan sekaligus, atau Anda harus membuat perubahan pada beberapa objek sekaligus, biasanya lebih efisien untuk mengelompokkan pencarian Anda daripada membuat beberapa permintaan HTTP individu.

Untuk mengaktifkannya, API Graf mendukung sejumlah fungsi, termasuk pencarian beberapa ID, dan pembuatan batch. Permintaan batch dijelaskan dalam panduan terpisah namun Anda dapat membaca selengkapnya tentang pencarian beberapa ID di bawah.

Permintaan Pembacaan Beberapa ID

Anda dapat membuat satu permintaan GET yang mengambil beberapa node menggunakan endpoint ?ids beserta ID objek dari node tersebut. Misalnya, untuk mencari halaman Pengembang Facebook dan pengguna sesi saat ini dalam satu permintaan, Anda dapat menggunakan panggilan API Graf berikut:

GET graph.facebook.com
  /?ids=platform,me

Yaitu sama dengan permintaan API individual berikut:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

Data yang dikembalikan akan terlihat seperti ini:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

Permintaan ini juga berfungsi dengan edge, selama semua ID yang diminta memiliki edge yang diminta. Misalnya:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

Sama dengan permintaan API individual berikut:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

Data yang dikembalikan akan terlihat seperti ini:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

Perhatikan bahwa meskipun pemfilteran kolom, perluasan kolom, dan pembatasan akan bekerja dengan pencarian beberapa ID, Anda akan mendapat pesan kesalahan jika salah satu objek tidak memiliki kolom yang diminta. Misalnya, jika Anda mencari Halaman dan Pengguna menggunakan metode ini, lalu filter pada fields=id,picture,gender permintaan tersebut akan gagal karena Halaman tidak memiliki kolom gender.

Introspeksi

API Graf mendukung introspeksi node. Dengan API Graf, Anda dapat melihat semua edge yang dimiliki oleh sebuah node tanpa mengetahui jenis sebelumnya. Untuk mendapatkan informasi ini, tambahkan metadata=1 ke permintaan API Graf:

GET graph.facebook.com
  /{node-id}?
    metadata=1

JSON yang dihasilkan akan menyertakan properti metadata yang mencantumkan semua edge yang didukung untuk node tertentu:

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

Penerbitan

Sebagian besar node di API Graf memiliki edge yang dapat menjadi target penerbit, seperti /{user-id}/feed atau /{album-id}/photos. Semua penerbitan API Graf dilakukan dengan permintaan HTTP POST untuk edge yang relevan dengan menyertakan setiap parameter yang diperlukan. Misalnya, untuk menerbitkan kiriman atas nama seseorang, Anda harus membuat permintaan HTTP POST seperti di bawah:

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

Semua penerbitan harus ditandatangani dengan token akses. Anda dapat menentukan izin yang diperlukan di token akses ini dengan melihat referensi API Graf untuk node yang ingin Anda terbitkan.

Ada sejumlah besar edge yang dapat menjadi target penerbitan. Penjelasan lebih lengkap dapat dilihat di dokumen referensi untuk setiap node.

Panduan Skenario Umum untuk API Graf berisi informasi tambahan untuk beberapa skenario penerbitan umum.

Membuat Beberapa Permintaan

Anda dapat menghubungkan panggilan menerbitkan dengan panggilan membaca secara bersamaan dengan menggunakan Permintaan Batch. Untuk informasi tambahan, lihat Melakukan Beberapa Permintaan API.

Read-After-Write

Banyak edge mendukung read-after-write. Lihat setiap dokumentasi referensi endpoint untuk melihat apakah ini mendukung read-after-write dan kolom apa yang tersedia.

Memperbarui

Semua pembaruan API Graf dilakukan dengan permintaan HTTP POST untuk node yang relevan dengan menyertakan setiap parameter diperbarui:

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

Semua panggilan memperbarui harus ditandatangani dengan token akses dengan izin sama yang diperlukan guna menerbitkan ke endpoint tersebut, sesuai referensi API Graf untuk node yang ingin Anda perbarui.

Read-After-Write

Banyak edge mendukung read-after-write. Lihat setiap dokumentasi referensi endpoint untuk melihat apakah ini mendukung read-after-write dan kolom apa yang tersedia.

Menghapus

Hapus node dari graf tersebut dengan mengirimkan permintaan DELETE HTTP ke node:

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

Secara umum, aplikasi hanya dapat menghapus konten yang telah dibuatnya. Baca panduan referensi untuk node atau edge untuk informasi selengkapnya.

Guna mendukung klien yang tidak mendukung semua metode HTTP, alternatifnya Anda dapat mengeluarkan permintaan POST ke endpoint dengan argumen tambahan method=delete untuk menimpa metode HTTP. Misalnya, Anda dapat menghapus komentar dengan mengeluarkan permintaan berikut:

POST graph.facebook.com
  /{comment-id}?
    method=delete

Read-After-Write

Untuk membuat dan memperbarui endpoint, API Graf dapat langsung membaca objek yang telah berhasil diterbitkan atau diperbarui dan mengembalikan kolom apa pun yang didukung oleh endpoint baca yang sesuai.

Untuk menggunakan fitur ini, sertakan fields parameter dalam permintaan Anda dan buat daftar kolom yang ingin Anda kembalikan. Sebagai contohnya, untuk menerbitkan pesan “Halo” ke kabar berita pengguna, Anda dapat membuat permintaan berikut:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

Ini akan mengembalikan kolom tertentu sebagai tanggapan yang diformat JSON, seperti ini:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

Lihat setiap dokumentasi referensi endpoint untuk melihat apakah ini mendukung read-after-write dan kolom apa yang tersedia.

Kesalahan

Jika pembacaan gagal karena alasan apa pun (misalnya, meminta kolom yang tidak ada), API Graf akan menanggapi dengan tanggapan kesalahan standar. Sebagai tambahannya, tanggapan tersebut akan menyertakan original_response properti yang bernilai berupa apa yang biasanya dikembalikan oleh endpoint saat berhasil.

Seperti misalnya, permintaan ini memiliki kolom yang tidak valid:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

Berikut merupakan tanggapannya:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

Anda dapat mencari lebih banyak objek publik dalam graf sosial dengan endpoint /search. Sintaks untuk pencarian adalah:

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

Semua kueri pencarian API Graf mewajibkan token akses yang disertakan dalam permintaan. Anda memerlukan token akses pengguna untuk mengeksekusi pencarian.

Jenis Pencarian yang Tersedia

Kami mendukung pencarian untuk jenis berikut:

Jenis Keterangan Nilai `q`

user

Cari orang (jika mereka mengizinkan nama mereka untuk dicari).

Nama

page

Cari Halaman.

Nama

event

Cari peristiwa.

Nama

group

Cari Grup.

Nama

place

Cari tempat. Anda dapat mempersempit pencarian ke lokasi dan jarak tertentu dengan menambahkan parameter center (beserta garis lintang dan bujur) serta parameter opsional distance (dalam meter):

Nama

placetopic

Mengembalikan daftar kemungkinan topik Halaman tempat dan ID mereka. Gunakan dengan parameter topic_filter=all untuk mendapatkan daftar lengkapnya.

Tidak Ada

ad_*

Kumpulan opsi berbagai pencarian yang dapat digunakan untuk menemukan opsi penargetan.

Lihat Opsi Penargetan

Contoh:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

Penanganan Kesalahan

Permintaan yang dilakukan ke API kami dapat menghasilkan sejumlah tanggapan kesalahan berbeda. Topik berikut menjelaskan taktik pemulihan, dan menyediakan daftar nilai kesalahan beserta peta untuk penggunaan taktik pemulihan yang paling umum.

Menerima Kode Kesalahan

Berikut ditampilkan tanggapan kesalahan umum yang dihasilkan dari permintaan API yang gagal:

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: Keterangan kesalahan yang dapat dibaca manusia.
  • code: Kode kesalahan. Nilai umum tercantum di bawah ini, bersama dengan taktik pemulihan umum.
  • error_subcode: Informasi tambahan tentang kesalahan. Nilai umum dicantumkan di bawah ini.
  • error_user_msg: Pesan yang akan ditampilkan kepada pengguna. Bahasa pesan didasarkan pada lokale permintaan API.
  • error_user_title: Judul dialog, jika diperlihatkan. Bahasa pesan didasarkan pada lokale permintaan API.
  • fbtrace_id: Pengidentifikasi dukungan internal. Ketika melaporkan bug yang terkait dengan panggilan API Graf, sertakan fbtrace_id untuk membantu kami menemukan data catatan debugging.

Kode Kesalahan

Kode atau Jenis Nama Yang Harus Dilakukan

OAuthException

Jika tidak ada subkode, berarti status masuk atau token aksesnya sudah kedaluwarsa, sudah dihapus, atau tidak valid. Dapatkan token akses baru.

Jika terdapat subkode, lihat subkodenya.

102

Sesi API

Jika tidak ada subkode, berarti status masuk atau token aksesnya sudah kedaluwarsa, sudah dihapus, atau tidak valid. Dapatkan token akses baru.

Jika terdapat subkode, lihat subkodenya.

1

API Tidak Diketahui

Kemungkinan masalah sementara karena downtime. Tunggu dan coba lagi operasi tersebut. Jika terjadi lagi, periksa apakah Anda meminta API yang ada.

2

Layanan API

Masalah sementara karena downtime. Tunggu dan coba lagi operasi tersebut.

4

Terlalu Banyak Panggilan API

Masalah sementara karena macet. Tunggu dan coba lagi operasi tersebut, atau periksa volume permintaan API Anda.

17

Terlalu Banyak Panggilan Pengguna API

Masalah sementara karena macet. Tunggu dan coba lagi operasi tersebut, atau periksa volume permintaan API Anda.

10

Izin API Ditolak

Izin tidak diberikan atau sudah dihapus. Tangani izin yang tidak ada.

190

Token akses sudah kedaluwarsa

Dapatkan token akses baru.

200-299

Izin API (Beberapa nilai bergantung pada izin)

Izin tidak diberikan atau sudah dihapus. Tangani izin yang tidak ada.

341

Batas Aplikasi Tercapai

Masalah sementara karena downtime atau macet. Tunggu dan coba lagi operasi tersebut, atau periksa volume permintaan API Anda.

368

Sementara diblokir karena melanggar kebijakan

Tunggu dan coba lagi operasi tersebut.

506

Kiriman Duplikat

Kiriman duplikat tidak dapat diterbitkan berturutan. Ubah konten kiriman dan coba lagi.

1609005

Kesalahan Mengirim Tautan

Ada masalah saat melakukan scraping data dari tautan yang disediakan. Periksa URL dan coba lagi.

Subkode Kesalahan Autentikasi

Kode Nama Yang Harus Dilakukan

458

Aplikasi Tidak Terpasang

Pengguna belum masuk ke aplikasi Anda. Lakukan autentikasi ulang pada pengguna.

459

Pengguna yang Sudah Melewati Titik Pemeriksaan

Pengguna harus masuk di https://www.facebook.com atau https://m.facebook.com untuk memperbaiki masalah.

460

Kata Sandi Diubah

Pada iOS 6 ke atas, jika seseorang masuk menggunakan aliran OS terintegrasi, mereka harus diarahkan ke pengaturan OS Facebook pada perangkat untuk memperbarui kata sandinya. Jika tidak, dia harus masuk ke aplikasi lagi.

463

Kedaluwarsa

Status masuk atau token akses telah kedaluwarsa, telah dicabut, atau tidak valid. Tangani token akses kedaluwarsa.

464

Pengguna Belum Dikonfirmasi

Pengguna harus masuk di https://www.facebook.com atau https://m.facebook.com untuk memperbaiki masalah.

467

Token akses tidak valid

Token akses telah kedaluwarsa, telah dicabut, atau tidak valid. Tangani token akses kedaluwarsa.

Parameter Kompleks

Sebagian besar jenis parameter merupakan primitif yang lurus seperti string dan int, namun terdapat juga jenis list dan object yang dapat ditentukan di permintaan.

Jenis list ditentukan di syntax JSON, sebagai contohnya: ["firstitem", "seconditem", "thirditem"]

Jenis object juga ditentukan di syntax JSON, sebagai contohnya: {"firstkey": "firstvalue", "secondKey": 123}

Melakukan Debug Permintaan API

Mode Debug API Graf

Apabila Mode Debug diaktifkan, tanggapan API Graf dapat berisi kolom tambahan, yang menjelaskan kemungkinan masalah dengan permintaan.

Untuk mengaktifkan mode debugging, gunakan parameter string pencarian debug. Misalnya:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

Jika izin user_friends tidak diberikan, hal ini akan menghasilkan tanggapan berikut:

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

Nilai parameter debug dapat ditetapkan ke "semua" atau ke level keparahan minimal yang diminta, yang terkait dengan type pesan:

Nilai Parameter Debug Yang Akan Dikembalikan

semua

Semua pesan debug yang tersedia.

info

Pesan debug dengan tipe info dan warning.

peringatan

Hanya pesan debug dengan jenis peringatan.

Informasi debug, jika tersedia, dikembalikan sebagai objek JSON dalam kunci __debug__ di dalam array messages. Setiap elemen array ini adalah objek JSON, yang berisi kolom berikut:

Kolom Jenis data Keterangan

pesan

String

Pesan.

jenis

String

Keparahan pesan.

tautan

String

[Opsional] URL yang mengarah ke informasi terkait.

Anda juga dapat menggunakan Mode Debug dengan Penjelajah API Graf.

Menentukan Versi yang digunakan oleh Permintaan API

Ketika Anda membuat aplikasi, dan membuat permintaan API Graf, mungkin bermanfaat bagi Anda untuk dapat menentukan versi API yang ingin didapatkan tanggapannya. Misalnya, jika Anda melakukan panggilan tanpa menentukan versi, maka versi API yang menanggapi mungkin tidak Anda ketahui.

API Graf memberikan header permintaan dengan tanggapan facebook-api-version yang menunjukkan versi tepat dari API yang menghasilkan tanggapan. Misalnya, panggilan API Graf yang menghasilkan permintaan dengan v2.0 akan memiliki header HTTP berikut:

facebook-api-version:v2.0

Dengan header facebook-api-version ini, Anda dapat menentukan apakah panggilan API dikembalikan dari versi yang Anda harapkan.

Info Debug untuk Melaporkan Bug

Jika Anda perlu melaporkan bug di API Graf, kami menyertakan beberapa header permintaan tambahan yang harus Anda kirim beserta laporan bug untuk membantu kami menunjukkan dan menyebarkan masalah Anda. Header permintaan ini adalah X-FB-Debug, x-fb-rev, dan X-FB-Trace-ID.