Graph API

Ringkasan

Graph API merupakan cara utama untuk memperoleh data di dalam dan di luar platform Facebook. Graph API adalah API berbasis HTTP yang dapat digunakan oleh aplikasi untuk melakukan kueri data secara terprogram, memposting cerita baru, mengelola iklan, mengunggah foto, dan melakukan berbagai tugas lainnya.

Nama Graph API berakar dari gagasan mengenai "graf sosial", yaitu sebuah representasi informasi di Facebook. Graph API terdiri dari node, edge, dan kolom. Biasanya Anda menggunakan node untuk memperoleh data mengenai sebuah objek tertentu, menggunakan edge untuk mendapatkan kumpulan objek di suatu objek tunggal, dan menggunakan kolom untuk memperoleh data mengenai suatu objek tunggal atau masing-masing objek yang terdapat di dalam sebuah koleksi. Sepanjang dokumentasi kami, kami dapat merujuk ke node dan edge sebagai "endpoint". Contoh: "Kirim permintaan GET ke endpoint Pengguna".

HTTP

Semua transfer data sesuai dengan HTTP/1.1, dan semua endpoint memerlukan HTTPS. Graph API berbasis HTTP, sehingga Graph API dapat digunakan dengan berbagai bahasa yang mempunyai pustaka HTTP, seperti cURL dan urllib. Ini berarti Anda dapat menggunakan Graph API secara langsung di dalam browser Anda. Misalnya, dengan meminta URL ini di dalam browser Anda...

https://graph.facebook.com/facebook/picture?redirect=false

... kurang lebih sama dengan melakukan permintaan cURL ini:

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

Kami juga telah mengaktifkan direktif HSTS includeSubdomains di facebook.com, tetapi ini tidak akan berdampak buruk pada panggilan Graph API Anda.

URL Host

Hampir semua permintaan diteruskan ke URL host graph.facebook.com. Satu-satunya pengecualian adalah unggahan video, yang menggunakan graph-video.facebook.com.

Token Akses

Dengan token akses, aplikasi Anda dapat mengakses Graph API. Hampir semua endpoint Graph API memerlukan token akses, maka setiap kali Anda mengakses endpoint, permintaan Anda mungkin memerlukannya. Pada umumnya token akses memiliki dua fungsi:

  • Membuat aplikasi Anda dapat mengakses informasi Pengguna tanpa memerlukan kata sandi Pengguna. Contoh: aplikasi Anda memerlukan email Pengguna untuk menjalankan suatu fungsi. Jika Pengguna setuju untuk mengizinkan aplikasi Anda mengambil alamat email mereka dari Facebook, Pengguna tidak perlu memasukkan kata sandi Facebook mereka agar aplikasi Anda mendapatkan alamat email mereka.
  • Membuat kami dapat mengenali aplikasi Anda, Pengguna yang menggunakan aplikasi Anda, dan jenis data yang aksesnya untuk aplikasi Anda telah diizinkan oleh Pengguna.

Kunjungi dokumentasi token akses kami untuk mempelajari selengkapnya.

Node

Node adalah suatu objek yang memiliki ID unik. Sebagai contoh, ada banyak objek node Pengguna, masing-masing memiliki ID unik yang mewakili seseorang di Facebook. Halaman, Grup, Postingan, Foto, dan Komentar hanyalah beberapa node dari Grafik Sosial Facebook.

Contoh cURL berikut mewakili panggilan ke node Pengguna.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Permintaan ini akan mengembalikan data berikut secara default, diformat menggunakan JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Metadata Node

Anda bisa mendapatkan daftar semua kolom, termasuk nama kolom, deskripsi, dan jenis data, dari objek node, seperti Pengguna, Halaman, atau Foto. Kirim permintaan GET ke ID objek dan sertakan parameter metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

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

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Node /me adalah endpoint khusus yang diterjemahkan ke ID objek orang atau Halaman yang token aksesnya saat ini digunakan untuk membuat panggilan API. Jika Anda memiliki token akses Pengguna, Anda dapat mengambil nama dan ID Pengguna dengan menggunakan:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Edge

Edge adalah koneksi antara dua node. Contoh: node Pengguna dapat memiliki foto yang terhubung dengannya, dan node Foto dapat memiliki komentar yang terhubung dengannya. Contoh cURL berikut akan mengembalikan daftar foto yang telah diterbitkan seseorang ke Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Setiap ID yang dikembalikan mewakili node Foto dan saat diunggah ke Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Kolom

Kolom adalah properti node. Saat Anda meng-kueri sebuah node atau edge, kueri tersebut menghasilkan sebuah set kolom secara default, sebagaimana contoh di atas. Akan tetapi, Anda dapat menentukan kolom mana yang ingin ditampilkan menggunakan parameter fields dan mendaftar setiap kolom. Ini menimpa pengaturan default dan hanya mengembalikan kolom yang Anda tentukan beserta ID objek, yang selalu dikembalikan.

Permintaan cURL berikut menyertakan parameter fields dan nama Pengguna, email, dan gambar profil.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Data Dikembalikan

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Parameter Rumit

Sebagian besar jenis parameter bersifat primitif langsung, seperti bool, string, dan int, tetapi juga jenis list dan object yang dapat ditentukan dalam permintaan.

Jenis list ditentukan di sintaksis JSON, contoh: ["firstitem", "seconditem", "thirditem"]

Jenis object juga ditentukan di sintaksis JSON, contoh: {"firstkey": "firstvalue", "secondKey": 123}

Menerbitkan, Memperbarui, dan Menghapus

Kunjungi panduan Bagikan ke Facebook untuk mempelajari cara menerbitkan ke Facebook milik Pengguna atau dokumentasi Pages API untuk menerbitkan ke beranda Facebook milik Halaman.

Beberapa node membuat Anda dapat memperbarui kolom dengan operasi POST. Contoh: Anda dapat memperbarui kolom email Anda seperti ini:

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Baca Setelah Tulis/Read-After-Write (RAW)

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

Secara default, ID objek yang dibuat atau diperbarui akan dikembalikan. Untuk memasukkan lebih banyak informasi dalam tanggapan, sertakan parameter fields dalam permintaan Anda dan daftar kolom yang Anda ingin dikembalikan. Contoh: untuk menerbitkan pesan “Hello” ke beranda pengguna, Anda dapat membuat permintaan berikut:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
Contoh kode di atas diformat agar mudah dibaca.

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

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

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

Kesalahan

Jika pembacaan gagal karena alasan apa pun (contoh: meminta kolom yang tidak ada), Graph API akan menanggapi dengan tanggapan kesalahan standar. Kunjungi panduan Penanganan Kesalahan untuk informasi selengkapnya.

Anda biasanya dapat menghapus node, seperti node Postingan atau Foto, dengan melakukan operasi DELETE pada ID objek:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

Biasanya Anda hanya dapat menghapus node yang Anda buat, namun periksalah panduan referensi masing-masing node untuk melihat persyaratan operasi penghapusannya.

Webhooks

Anda dapat diberi tahu tentang perubahan node atau interaksi dengan node dengan berlangganan Webhooks. Lihat Webhooks.

Versi

Graph API memiliki beberapa versi dengan rilis setiap kuartal. Anda dapat menentukan versi dalam panggilan Anda dengan menambahkan "v" dan nomor versi ke awal jalur permintaan. Contoh: berikut adalah panggilan untuk versi 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Jika Anda tidak menyertakan nomor versi, maka kami akan secara default memberikan versi tertua yang ada, jadi direkomendasikan untuk menyertakan nomor versi di dalam permintaan Anda.

Anda dapat membaca selengkapnya tentang versi di panduan Versi dan pelajari semua versi yang tersedia dalam Catatan perubahan Graph API.

API Facebook, Facebook SDK, dan Platform Facebook

Hubungkan antarmuka dan kembangkan di seluruh platform menggunakan berbagai API, SDK, dan platform Facebook.

Langkah Berikutnya

Memulai dengan Graph API – Jelajahi Grafik Sosial Facebook menggunakan fitur Graph API Explorer dan jalankan beberapa permintaan untuk mendapatkan data.