Permintaan Asinkron dan Batch

Gunakan permintaan asinkron untuk membuat iklan dan mengirim banyak permintaan tanpa harus memblokir. Tentukan URL yang akan dipanggil setelah permintaan selesai atau periksa status permintaan. Lihat Iklan, Referensi.

Cara paling efisien untuk mengelola iklan melalui permintaan batch. Gunakan ini untuk melakukan beberapa permintaan yang lebih umum.

Permintaan Asinkron

Contoh: dapatkan status dari set permintaan asinkron:

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Ini mengembalikan status keseluruhan untuk permintaan asinkron yang ditetapkan sebagai objek JSON. Tidak semua kolom muncul secara default. Jika Anda ingin kueri Anda menyertakan kolom non-default, tentukanlah di fields, seperti fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Setelah Anda mendapatkan status keseluruhan dari set permintaan asinkron, dapatkan detail dari setiap permintaan:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

Ini mengembalikan status dan detail setiap permintaan di dalam set permintaan askinkron. Untuk pembuatan iklan asinkron, buat satu permintaan untuk membuat satu iklan. Parameter status digunakan untuk memfilter permintaan berdasarkan statusnya sendiri dan dapat berupa kombinasi nilai berikut:

• initial – Belum diproses.
• in_progress – Permintaan sedang diproses.
• success – Permintaan selesai dan berhasil.
• error – Permintaan selesai dan gagal
• canceled – Permintaan dibatalkan pengguna

Tangggapannya adalah array JSON dengan kolom default. Untuk menyertakan kolom non-default apa saja, tentukan di fields, seperti fields=id,scope_object_id,status,result,input,async_request_set.

Mendapatkan Detail Permintaan

Untuk mendapatkan detail permintaan asinkron tertentu, lakukan panggilan ini:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

Ini mengembalikan objek JSON dengan kolom yang tercantum di atas.

Daftar Set Permintaan untuk Akun

Anda dapat membuat beberapa set permintaan iklan asinkron. Untuk meng-kueri semua set permintaan iklan asinkron untuk akun iklan:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Ini mengembalikan array JSON dari objek set permintaan asinkron. Setiap objek sama seperti yang ditentukan di bagian set permintaan asinkron. Hasil dapat difilter dengan is_completed. Jika is_completed=true, Anda hanya melihat set permintaan asinkron yang selesai.

Daftar Permintaan untuk Set Iklan

Anda dapat melakukan panggilan asinkron untuk membuat iklan di set iklan yang berbeda. Untuk mendapatkan status setiap set iklan, dapatkan semua permintaan pembuatan iklan untuk satu set iklan:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_SET_ID>/asyncadrequests

Ini menampilkan array JSON dari objek permintaan asinkron. Status, filter kolom, dan kolom permintaan asinkron adalah sama seperti API https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests.

Memperbarui Set Permintaan

Anda dapat mengubah name, notification_uri, dan notification_mode untuk set permintaan asinkron.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Ini mengembalikan true saat pembaruan berhasil. Anda hanya dapat mengubah notification_uri dan notification_mode sebelum notifikasi dikirim.

Membatalkan Permintaan

Anda dapat membatalkan permintaan asinkron, tetapi permintaan tersebut hanya dapat dibatalkan jika belum diproses.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_ID>

Menampilkan true saat pembatalan berhasil. Anda juga dapat membatalkan permintaan yang belum diproses dalam set permintaan asinkron:

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Menampilkan true saat pembatalan berhasil.

Contoh Asinkronisasi

Mendapatkan status permintaan asinkron spesifik:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/"

Menampilkan nilai:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Mendapatkan hasil permintaan:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/requests"

Mengembalikan:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Mendapatkan daftar set permintaan untuk akun iklan:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_71597454/asyncadrequestsets"

Mengembalikan:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Mendapatkan daftar permintaan untuk kampanye:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/6008248529789/asyncadrequests"
    

Menampilkan nilai:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Permintaan Batch

Dengan permintaan batch, gabungkan sejumlah panggilan Graph API ke satu permintaan HTTP. Marketing API membagi permintaan ini menjadi permintaan konstituennya. Ini menjadikan permintaan batch cara paling efisien untuk berinteraksi dengan Marketing API. Untuk efisiensi yang lebih tinggi, Anda dapat membuat permintaan batch paralel menggunakan utas pemrosesan terpisah.

Permintaan batch untuk iklan, materi iklan, dan set iklan sangat mirip jadi kami tidak membahasnya secara terpisah di sini. Untuk informasi selengkapnya, lihat permintaan batch Graph API dan ETag.

Membuat Iklan

Anda dapat menyediakan materi iklan dan objek iklan lainnya dalam permintaan batch. Contoh: Anda dapat membuat tiga iklan menggunakan satu materi iklan dan tiga spesifikasi penargetan yang berbeda. Tentukan Materi Iklan Anda terlebih dahulu, lalu referensikan setiap Anda membuat iklan:

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

Tanggapan tersebut mencakup kode tanggapan individual untuk setiap permintaan dan tanggapan Graph API standar. Untuk detailnya, lihat Membuat Beberapa Permintaan API.

Proses permintaan batch menggunakan format ekspresi JSONPath untuk mereferensikan permintaan sebelumnya.

Memperbarui Iklan

Anda dapat memperbarui iklan dengan permintaan batch. Guna memperbarui tawaran untuk tiga iklan:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Jika Anda menyertakan redownload=1 di URL relatif, Anda akan mendapatkan detail iklan lengkap termasuk ID iklan. Ini membantu mengidentifikasi iklan mana yang Anda perbarui.

Untuk memperbarui materi iklan, tentukan seluruh materi iklan, atau berikan ID materi iklan baru. Ini karena Materi Iklan tidak dapat diedit setelah dibuat kecuali untuk nama dan status proses.

Membaca Iklan

Jika Anda memiliki iklan dalam jumlah besar, pisahkan permintaan menjadi beberapa permintaan dalam satu permintaan batch:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839 dan 6004164369439 adalah id iklan sementara 6003356307839 dan 6004164259439 adalah id set iklan.

Insight Iklan

Jika Anda memiliki Insight Iklan dalam jumlah besar, pisahkan permintaan menjadi beberapa permintaan dalam satu permintaan batch:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

Di contoh ini, 6003356308839 dan 6004164369439 adalah id iklan sementara 6003356307839 dan 6004164259439 adalah id set iklan.

Untuk akun Iklan dengan iklan dalam jumlah besar, penggunaan act_<account_ID>/adgroupstats tidak direkomendasikan karena dapat menyebabkan permintaan kehabisan waktu.

Permintaan Batch untuk Estimasi Jangkauan

Anda dapat meminta hingga 50 estimasi jangkauan dalam satu permintaan batch. Contoh berikut ini menunjukkan estimasi jangkauan yang diminta untuk 2 spesifikasi penargetan yang berbeda:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

Batch API

Batch API mengizinkan Anda mengelompokkan permintaan dan mengirimnya secara asinkron. Mengelompokkan beberapa panggilan API Graf menjadi satu permintaan HTTP, dan mengeksekusinya secara asinkron tanpa harus memblokir. Anda juga dapat menetapkan dependensi antar operasi terkait.

Facebook memproses setiap operasi independen dalam proses paralel dan operasi dependen Anda secara sekuensial. Setiap panggilan API dapat memiliki maksimal 1000 permintaan.

Membuat panggilan Batch API

Untuk membuat panggilan Batch API:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Sediakan array permintaan HTTP POST sebagai array JSON. Setiap permintaan memiliki:

• name
• relative_url - porsi URL setelah graph.facebook.com
• body

API menampilkan ID yang digunakan untuk melakukan kueri kemajuan permintaan.

Contoh: buat kampanye dengan set iklan dengan Format JSONPath untuk mereferensikan permintaan sebelumnya:

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Untuk mendapatkan status set permintaan:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>"

Ini menampilkan status keseluruhan untuk set permintaan asinkron sebagai objek JSON. Tidak semua kolom dikembalikan secara default. Untuk menyertakannya, tentukan fields, seperti fields=id,owner_id,name,total_count,success_count,error_count,is_completed

Setelah Anda mendapatkan status keseluruhan, Anda bisa mendapatkan detail untuk setiap permintaan:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests"

Ini menampilkan detail sebagai array JSON. Untuk menyertakan kolom non-default, tentukan di fields, seperti fields=id,scope_object_id,status,result,input,async_request_set.

Daftar Permintaan Batch API untuk Akun Iklan

Anda dapat membuat beberapa set permintaan Batch API Untuk meng-kueri semua set permintaan pada akun iklan:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_requests"

ETag

Marketing API mendukung Etag. Ini membantu Anda mengetahui apakah data yang Anda kueri telah berubah sejak terakhir kali Anda memeriksanya. Cara kerjanya:

1. Saat Anda melakukan panggilan, header tanggapan menyertakan ETag dengan nilai hash dari data yang dikembalikan dalam panggilan API. Simpan nilai ETag ini untuk digunakan di langkah berikutnya.
2. Lain kali Anda melakukan panggilan API yang sama, sertakan header permintaan If-None-Match dengan nilai ETag yang Anda simpan.
3. Jika data tidak berubah, kode status tanggapan adalah 304 – Not Modified dan tidak ada data yang dikembalikan.
4. Jika data telah berubah sejak kueri terakhir, data dikembalikan seperti biasa dengan ETag baru. Simpan nilai ETag baru dan gunakan untuk panggilan berikutnya.

Selagi ETag membantu mengurangi traffic data, If-None-Match GET masih dihitung terhadap batas laju untuk aplikasi Anda.

ETag dihitung menggunakan seluruh tanggapan dari panggilan API termasuk pemformatannya. Pemformatan tanggapan mungkin dipengaruhi oleh string agen pengguna. Oleh karena itu, Anda harus menjaga konsistensi agen pengguna Anda di antara panggilan yang dilakukan dari klien yang sama.

Contoh Etag

Untuk memeriksa apakah akun pengguna telah berubah.

Langkah 1: Tentukan ETag untuk data saat ini

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Tanggapannya akan seperti ini:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

Di contoh ini, ETag-nya "7776cdb01f44354af8bfa4db0c56eebcb1378975", perhatikan bahwa ETag termasuk tanda kutip (").

Langkah 2: Tentukan apakah ada perubahan pada data

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Jika tidak ada yang berubah, tanggapan akan seperti berikut:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Catat tanggapan 304 Not Modified. Jika data telah berubah, tanggapan API normal akan dikembalikan.

Contoh batch untuk memeriksa apakah iklan pengguna telah berubah.

Langkah 1: Tentukan ETag untuk data saat ini

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

Tanggapan akan berisi nilai ETag berikut:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

Di contoh ini, ETag-nya "21d371640127490b2ed0387e8af3f0f8c9eff012" dan "410e53bb257f116e8716e4ebcc76df1c567b87f4". Perhatikan bahwa ETag termasuk tanda kutip (").

Langkah 2: Tentukan apakah ada perubahan pada data:

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

Jika tidak ada yang berubah, tanggapannya:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Catat tanggapan 304 Not Modified. Jika data berubah, kami memberikan tanggapan API normal.