Batas dan Praktik Terbaik

Insights API Meta memberikan data kinerja dari kampanye marketing Meta. Guna melindungi kinerja dan stabilitas sistem, kami memiliki upaya perlindungan agar sumber daya sistem dapat didistribusikan secara merata di semua aplikasi. Semua kebijakan yang kami jelaskan di bawah ini dapat berubah sewaktu-waktu.

Data Per Batas Panggilan

Kami menggunakan batas data per panggilan untuk mencegah agar kueri tidak mengambil data melebihi yang dapat ditangani sistem. Ada 2 jenis batas data:

1. Berdasarkan jumlah baris tanggapan, dan
2. Berdasarkan poin data yang diharuskan untuk menghitung total, seperti baris rangkuman.

Batas tersebut berlaku untuk panggilan /insights sinkron dan asinkron, dan kami mengembalikan kesalahan:

error_code = 100,  CodeException (error subcode: 1487534)

Praktik Terbaik, Batas Data Per Panggilan

• Batasi kueri Anda dengan membatasi rentang tanggal atau jumlah id iklan. Anda juga dapat membatasi kueri Anda ke metrik yang diperlukan, atau memerincinya ke dalam beberapa kueri dengan setiap kueri yang meminta subset metrik.
• Hindari kueri level akun yang menyertakan perincian kardinalitas tinggi seperti action_target_id atau product_id, dan rentang tanggal yang lebih lama seperti sepanjang masa.
• Gunakan edge /insights langsung dengan objek iklan berlevel lebih rendah untuk mengambil data granular untuk level itu. Contoh: pertama-tama gunakan kueri tingkat akun untuk mengambil daftar ID objek tingkat rendah dengan parameter level dan filtering. Dalam contoh ini, kami mengambil semua kampanye yang merekam beberapa impresi:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

• Lalu, kami dapat menggunakan /<campaign_id>/insights dengan tiap nilai yang dimunculkan untuk di-kueri dan mengelompokkan permintaan insight untuk kampanye itu dalam satu panggilan:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'

• Gunakan parameter filtering hanya untuk mendapatkan insight untuk objek iklan beserta data. Nilai kolom yang ditentukan dalam filtering menggunakan notasi DOT untuk menampilkan kolom-kolom di bawah objek. Harap diperhatikan bahwa pemfilteran dengan STARTS_WITH dan CONTAIN tidak mengubah data ringkasan. Dalam kasus ini, gunakan operator IN. Lihat contoh permintaan filtering:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'

• Gunakan date_preset jika memungkinkan. Rentang tanggal khusus kurang efisien untuk dijalankan di sistem kami.
• Gunakan permintaan batch untuk beberapa panggilan sinkron dan asinkron untuk meng-kueri data dalam volume besar dan menghindari waktu habis.
• Coba panggilan sinkron terlebih dahulu, lalu gunakan panggilan asinkron jika waktu panggilan sinkron habis
• Insight diperbarui setiap 15 menit dan tidak berubah setelah 28 hari dilaporkan

Batas Pemuatan Panggilan Insight

Sembilan puluh hari sejak rilis v3.3 dan berlaku untuk semua versi publik, kami mengubah batas laju level akun iklan untuk lebih mencerminkan volume panggilan API yang diperlukan. Kami menghitung kuota batas laju pada tingkat akses Marketing API dan bisnis yang memiliki aplikasi Anda. Lihat Akses dan Autentikasi. Perubahan ini berlaku untuk semua endpoint Ads Insights API: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.

Kami menggunakan batas pemuatan demi pengalaman pelaporan yang optimal. Kami mengukur laju panggilan API serta sumber daya yang diperlukannya. Kami mengizinkan batas pemuatan tetap per aplikasi per detik. Saat Anda melampaui batas itu, permintaan Anda gagal.

Lihat header HTTP x-fb-ads-insights-throttle di setiap tanggapan API untuk mengetahui seberapa dekat aplikasi Anda dengan batas, serta untuk memperkirakan berat suatu kueri. Panggilan Insight juga memiliki batas akun iklan default yang ditampilkan dalam header HTTP x-ad-account-usage. Detail selengkapnya terdapat di Marketing API, Praktik Terbaik

Setelah aplikasi mencapai batasnya, panggilan akan mendapat tanggapan kesalahan dengan error_code = 4, CodedException. Anda sebaiknya terus menjaga jarak dari batas. Jika aplikasi Anda mencapai batasnya, hanya sebagian dari permintaan yang akan masuk, bergantung pada kueri dan lajunya.

Kami menerapkan pembatasan laju pada tiap aplikasi yang mengirimkan panggilan /insights sinkron dan asinkron yang terpadu. Dua batas parameter utamanya dihitung menurut aplikasi, dan menurut akun iklan.

Berikut ini contoh header HTTP yang menunjukkan skor yang dihasilkan aplikasi dalam hitungan persen dari batasnya:

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

Header "x-fb-ads-insights-throttle" adalah nilai JSON yang berisi info ini:

• app_id_util_pct — Persentase dari alokasi kapasitas yang sudah digunakan app_id terkait.
• acc_id_util_pct — Persentase dari alokasi kapasitas yang sudah digunakan account_id iklan terkait.
• ads_api_access_tier — Tingkatan memungkinkan aplikasi Anda untuk mengakses Marketing API. standard_access memungkinkan pembatasan laju yang lebih rendah.

Batas Laju Global

Selama periode peningkatan muatan global ke endpoint /insights, sistem dapat memperlambat permintaan untuk melindungi backend. Hal ini dapat terjadi dalam kasus yang jarang terjadi ketika terlalu banyak kueri dengan kompleksitas tinggi (rentang waktu yang besar, metrik yang kompleks, dan/atau jumlah ID objek iklan yang tinggi) datang secara bersamaan. Hal ini akan terwujud dalam kesalahan yang terlihat seperti ini:

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

Selama periode ini, disarankan untuk mengurangi panggilan, menunggu untuk periode singkat, dan melakukan kueri lagi.

Praktik Terbaik Batas Laju

• Pembatasan laju kami lebih mungkin terpicu jika Anda mengirimkan beberapa kueri sekaligus. Cobalah untuk membagi-bagi kueri /insights Anda dengan menjedanya dengan waktu tunggu dalam tugas Anda.
• Gunakan informasi laju dalam header tanggapan HTTP untuk memoderasi panggilan Anda. Tambahkan mekanisme penghambat untuk memperlambat atau menjeda kueri /insights Anda saat hampir mencapai batas 100% untuk aplikasi, atau akun iklan Anda.
• Kami melaporkan data insight iklan dalam zona waktu akun iklan. Untuk mengambil data insight mengenai akun iklan terkait tiap hari, atur waktu Anda menggunakan zona waktu akun. Ini membantu pengaturan laju kueri di sepanjang hari.
• Periksa ads_api_access_tier yang memungkinkan Anda untuk mengakses Marketing API. Secara default, aplikasi ada di tingkat development_access dan standard_access memungkinkan pembatasan laju yang lebih rendah. Untuk mendapatkan batas laju yang lebih tinggi dan mencapai tingkat standar, Anda dapat mengajukan "Akses Lanjutan" ke fitur Akses Standar Pengelolaan Iklan.

Tugas Asinkron Insights API

Dari mengambil statistik tentang banyak objek hingga menerapkan pemfilteran dan pengurutan, kami menyederhanakan alur kerja asinkron:

1. Kirimkan permintaan POST ke endpoint <AD_OBJECT>/insights, yang memberikan id dariOperasi Laporan Iklan.

{
  "report_run_id": 6023920149050,
}
    

Jangan menyimpan report_run_id untuk jangka panjang, karena masa berlakunya hanya 30 hari.

1. Operasi Laporan Iklan berisi informasi tentang tugas asinkron ini, seperti async_status. Polling kolom ini sampai async_status jadi Job Completed dan async_percent_completion jadi 100.

{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
    

1. Lalu Anda dapat meng-kueri edge <AD_REPORT_RUN_ID>/insights untuk mengambil hasil akhir.

{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}
    

Tugas ini mengambil semua statistik akun tersebut dan menampilkan ID tugas asinkron:

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

Status Tugas Asinkron

Mengekspor Laporan

Kami menyediakan endpoint yang sesuai untuk mengekspor <AD_REPORT_RUN_ID> ke dalam format yang telah dilokalkan dan dapat dibaca pengguna.

Catatan: endpoint ini bukan bagian dari Graph API versi kami dan oleh karena itu tidak sesuai dengan kebijakan perubahan sela. Skrip dan program tidak boleh bergantung pada format hasil karena dapat berubah secara tidak terduga.

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'