Graph API

Permintaan Batch

Kirim satu permintaan HTTP yang berisi beberapa panggilan Meta Graph API. Operasi independen Anda diproses secara paralel sementara operasi dependen Anda diproses secara berurutan. Setelah operasi selesai, tanggapan terkonsolidasi akan diteruskan kembali kepada Anda dan koneksi HTTP akan ditutup.

Urutan tanggapan sesuai dengan urutan operasi dalam permintaan. Anda harus memproses tanggapan yang sesuai untuk menentukan operasi mana yang berhasil dan mana yang harus dicoba lagi dalam operasi berikutnya.

Batasan

  • Permintaan batch dibatasi hingga 50 permintaan per batch. Setiap panggilan di dalam batch dihitung secara terpisah untuk tujuan penghitungan batas panggilan API dan batas sumber daya. Contoh: batch 10 panggilan API akan dihitung sebagai 10 panggilan dan setiap panggilan dalam batch berkontribusi terhadap batas sumber daya dengan cara yang sama. Lihat Panduan Pembatasan Laju kami untuk informasi selengkapnya.
  • Permintaan batch tidak boleh berisi beberapa Set Iklan di bawah Kampanye yang sama. Pelajari selengkapnya tentang pembuatan batch permintaan Marketing API.

Permintaan Batch

Permintaan batch mengambil objek JSON yang terdiri dari array permintaan Anda. Permintaan batch mengembalikan array tanggapan HTTP logika yang diwakili sebagai array JSON. Setiap tanggapan memiliki kode status, array header opsional, dan isi opsional (yaitu string berenkode JSON).

Untuk membuat permintaan batch, kirim permintaan POST ke endpoint yang parameter batch adalah objek JSON Anda.

POST /ENDPOINT?batch=[JSON-OBJECT]

Contoh Permintaan Batch

Pada contoh ini, kami mendapatkan informasi tentang dua Halaman yang dikelola aplikasi kami.

Diformat agar mudah dibaca.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

Setelah semua operasi selesai, tanggapan dikirim dengan hasil dari setiap operasi. Karena header yang dikembalikan terkadang dapat jauh lebih besar daripada tanggapan API sebenarnya, Anda mungkin ingin menghapusnya demi efisiensi. Untuk memasukkan informasi header, hapus parameter include_headers atau atur ke true.

Contoh Tanggapan

Kolom isi berisi objek JSON berenkode string:

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Permintaan Batch Rumit

Ada kemungkinan menggabungkan operasi yang biasanya menggunakan metode HTTP yang berbeda ke dalam satu permintaan batch. Sementara operasi GET dan DELETE hanya dapat memiliki kolom relative_url dan method, POST dan operasi PUT dapat berisi kolom body. Isi ini harus diformat sebagai string HTTP POST mentah, sama seperti string kueri URL.

Contoh Permintaan

Contoh berikut menulis postingan baru ke Halaman yang kami kelola dan memiliki izin terbit, lalu ke beranda Halaman di satu operasi:

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

Output panggilan ini akan menjadi:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

Contoh berikut membuat iklan baru untuk kampanye, lalu mendapatkan detail objek yang baru saja dibuat. Perhatikan URLEncoding untuk parameter isi:

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

Contoh berikut menambahkan beberapa halaman ke Pengelola Bisnis:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Di mana:

  • <ACCESS_TOKEN> adalah token akses dengan izin business_management.
  • <BUSINESS_ID> adalah ID Pengelola Bisnis yang halamannya harus diklaim.
  • <PAGE_ID_n> adalah ID Halaman yang akan diklaim.

Kesalahan

Ada kemungkinan salah satu operasi yang Anda minta dapat mengakibatkan kesalahan. Ini dapat terjadi karena, misalnya Anda tidak memiliki izin melakukan operasi yang diminta. Tanggapannya mirip dengan Graph API standar, tetapi dikemas dalam sintaksis tanggapan batch:

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

Permintaan lain dalam batch akan tetap berhasil diselesaikan dan akan dikembalikan, seperti normalnya, dengan kode status 200.

Waktu habis

Waktu untuk batch besar atau kompleks dapat habis jika terlalu lama dalam menyelesaikan semua permintaan dalam batch. Dalam kondisi tersebut, hasilnya adalah batch yang selesai sebagian. Dalam batch yang selesai sebagian, permintaan yang berhasil diselesaikan akan mengembalikan output normal dengan kode status 200. Tanggapan untuk permintaan yang tidak berhasil adalah null. Anda dapat mencoba lagi permintaan yang gagal.

Panggilan batch dengan JSONP

API Batch mendukung JSONP, sama seperti Graph API lainnya - fungsi panggilan balik JSONP ditentukan menggunakan string kueri callback atau parameter postingan formulir.

Menggunakan Beberapa Token Akses

Permintaan individu dari satu permintaan batch dapat menentukan token aksesnya sendiri sebagai string kueri atau parameter postingan formulir. Dalam kasus tersebut, token akses level atas dianggap token fallback dan digunakan jika permintaan individual tidak menetapkan token akses secara tegas.

Hal ini dapat bermanfaat apabila Anda ingin meminta API menggunakan token akses pengguna yang berbeda, atau jika panggilan Anda akan dilakukan menggunakan token akses aplikasi.

Anda harus menyertakan token akses sebagai parameter level atas, meskipun semua permintaan individual berisi token mereka sendiri.

Mengunggah Data Biner

Anda dapat mengunggah beberapa item biner sebagai bagian dari panggilan batch. Untuk melakukannya, Anda harus menambahkan semua barang biner sebagai lampiran banyak bagian/mime ke permintaan, dan memerlukan tiap operasi untuk mereferensikan item binernya menggunakan properti attached_files dalam operasi. Properti attached_files dapat mengambil daftar nama lampiran yang dipisahkan koma dalam nilainya.

Contoh berikut memperlihatkan cara mengunggah 2 foto dalam satu panggilan batch:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->