API การตลาด

ขีดจำกัดและหลักปฏิบัติที่ดีที่สุด

API ข้อมูลเชิงลึกของ Facebook ให้ข้อมูลประสิทธิภาพการทำงานจากแคมเปญการตลาดบน Facebook ในการปกป้องประสิทธิภาพและความเสถียรของระบบ เราจัดตั้งมาตรการป้องกันเพื่อกระจายทรัพยากรของระบบไปยังแอพพลิเคชั่นต่างๆ อย่างเท่าเทียมกัน นโยบายทั้งหมดที่เราอธิบายด้านล่างมีการเปลี่ยนแปลงได้

ขีดจำกัดข้อมูลต่อการเรียก

เราจะใช้ขีดจำกัดข้อมูลต่อการเรียกเพื่อป้องกันไม่ให้การสืบค้นเรียกใช้ข้อมูลมากเกินกว่าที่ระบบจะจัดการได้ ขีดจำกัดข้อมูลมีสองชนิด ได้แก่

  1. ตามจำนวนแถวที่ตอบสนอง และ
  2. ตามจำนวนจุดข้อมูลที่ต้องใช้ในการคำนวณยอดรวม เช่น แถวสรุป

ขีดจำกัดนี้มีผลกับทั้งการเรียกใช้ /insights แบบซิงค์และไม่ซิงค์ และเราจะส่งคืนข้อผิดพลาดดังนี้

error_code = 100,  CodeException (error subcode: 1487534)

หลักปฏิบัติที่ดีที่สุดและขีดจำกัดข้อมูลต่อการเรียก

  • จำกัดการสืบค้นโดยการจำกัดช่วงวันที่หรือจำนวน ID โฆษณา นอกจากนี้คุณยังสามารถจำกัดการสืบค้นเฉพาะกับเกณฑ์ชี้วัดที่จำเป็นเท่านั้น หรือแยกย่อยเป็นการสืบค้นโดยให้แต่ละรายการขอเกณฑ์ชี้วัดชุดย่อยได้
  • หลีกเลี่ยงการสืบค้นระดับบัญชีที่ระบุข้อมูลที่ละเอียด เช่น action_target_id หรือ product_id และช่วงวันที่ที่กว้าง เช่น ตลอดอายุการใช้งาน
  • ให้ใช้จุดเชื่อมโยง /insights โดยตรงกับอ็อบเจ็กต์โฆษณาระดับต่ำเพื่อเรียกใช้ข้อมูลย่อยของระดับนั้น ตัวอย่างเช่น อันดับแรก ให้ใช้การสืบค้นระดับบัญชีเพื่อเรียกดูรายการ ID ของอ็อบเจ็กต์ระดับต่ำที่มีพารามิเตอร์ level และ filtering ในตัวอย่างนี้ เราจะเรียกดูแคมเปญทั้งหมดที่บันทึกอิมเพรสชั่นไว้บางส่วน ดังนี้
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'
  • จากนั้นเราจะสามารถใช้ /<campaign_id>/insights กับค่าที่ส่งคืนกลับมาแต่ละค่าเพื่อสืบค้นและรวมกลุ่มคำขอข้อมูลเชิงลึกสำหรับแคมเปญเหล่านี้ไว้ในการเรียกใช้ครั้งเดียว ดังนี้
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'
  • ใช้พารามิเตอร์ filtering เพื่อเรียกใช้ข้อมูลเชิงลึกสำหรับอ็อบเจ็กต์โฆษณาที่มีข้อมูลเท่านั้น ค่าของช่องที่ระบุใน filtering จะใช้เครื่องหมายจุด (DOT notation) กับช่องภายใต้อ็อบเจ็กต์ โปรดทราบว่าการกรองด้วย STARTS_WITH และ CONTAIN จะไม่เป็นการเปลี่ยนแปลงข้อมูลสรุป ในกรณีนี้ ให้ใช้ตัวดำเนินการ IN โปรดดูตัวอย่างคำขอ 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'
  • ใช้ date_preset หากทำได้ ช่วงวันที่ที่กำหนดเองจะมีประสิทธิภาพน้อยกว่าในการเรียกใช้ในระบบของเรา
  • ใช้คำขอแบบเป็นแบตช์สำหรับการเรียกใช้แบบซิงค์และไม่ซิงค์หลายรายการเพื่อสืบค้นข้อมูลปริมาณมากเพื่อหลีกเลี่ยงไม่ให้เกิดการหมดเวลา
  • พยายามใช้การเรียกแบบซิงค์ในกรณีที่การเรียกแบบไม่ซิงค์หมดเวลา
  • ข้อมูลเชิงลึกจะรีเฟรชทุกๆ 15 นาทีและจะไม่เปลี่ยนแปลงหลังรายงานแล้ว 28 วัน

ขีดจำกัดโหลดการเรียกข้อมูลเชิงลึก

เราเปลี่ยนแปลงขีดจำกัดอัตราของระดับบัญชีโฆษณาเพื่อให้ตอบโจทย์ปริมาณการเรียกใช้ API ที่จำเป็นมากยิ่งขึ้น โดยมีผลกับเวอร์ชั่นสาธารณะทั้งหมดและมีผลหลังจาก 90 วันนับตั้งแต่การเปิดตัวเวอร์ชั่น 3.3 เราคำนวณโควต้าขีดจำกัดอัตราตามระดับการเข้าถึง API การตลาดและธุรกิจที่เป็นเจ้าของแอพของคุณ โปรดดูการเข้าถึงและการยืนยันตัวตน การเปลี่ยนแปลงนี้จะใช้กับตำแหน่งข้อมูล 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.

เราใช้ขีดจำกัดโหลดเพื่อปรับประสบการณ์การรายงานให้เหมาะสม เราจะวัดผลอัตราการเรียก API รวมทั้งแหล่งที่มาที่ต้องระบุ เราอนุญาตให้ใช้ขีดจำกัดโหลดที่ตายตัวต่อแอพพลิเคชั่นต่อวินาที เมื่อเกินขีดจำกัดนั้นๆ คำขอจะล้มเหลว

ตรวจสอบส่วนหัว HTTP x-fb-ads-insights-throttle ในทุกการตอบกลับ API เพื่อดูว่าแอพของคุณใกล้จะถึงขีดจำกัดเท่าใดแล้ว รวมถึงเพื่อประมาณการณ์ว่าการสืบค้นแต่ละรายการจะมีปริมาณข้อมูลมากแค่ไหน การเรียกใช้ข้อมูลเชิงลึกจะยังมีขีดจำกัดเริ่มต้นของบัญชีโฆษณาตามที่แสดงในส่วนหัว HTTP x-ad-account-usage ด้วย ดูรายละเอียดเพิ่มเติมได้ที่ API การตลาด, หลักปฏิบัติที่ดีที่สุด

เมื่อแอพถึงขีดจำกัด การเรียกใช้จะได้รับการตอบกลับที่มีข้อผิดพลาด error_code = 4, CodedException คุณควรใช้งานโดยอยู่ภายใต้ขีดจำกัดของคุณเอง หากแอพถึงขีดจำกัดที่อนุญาตแล้ว จะมีเพียงคำขอไม่กี่เปอร์เซ็นต์เท่านั้นที่จะถูกส่งได้ ขึ้นอยู่กับการสืบค้นและอัตรา

เราบังคับใช้การจำกัดอัตรากับแต่ละแอพที่ส่งการเรียกใช้ /insights แบบซิงค์และไม่ซิงค์รวมกัน พารามิเตอร์หลัก 2 พารามิเตอร์จะมีการคำนวณตามแอพพลิเคชั่นและบัญชีผู้ใช้โฆษณา

นี่คือตัวอย่างส่วนหัว HTTP ที่แสดงคะแนนของแอพเป็นเปอร์เซ็นต์ของขีดจำกัดที่กำหนด:

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

ส่วนหัว “x-fb-ads-insights-throttle” เป็นค่า JSON ที่มีข้อมูลต่อไปนี้

  • app_id_util_pct - จำนวนความจุที่จัดสรรไว้ซึ่ง app_id ที่เชื่อมโยงอยู่ใช้ไป
  • app_id_util_pct - จำนวนความจุที่จัดสรรไว้ซึ่ง ad account_id ที่เชื่อมโยงอยู่ใช้ไป
  • ads_api_access_tier - ระดับจะเป็นตัวระบุสิทธิ์ของแอพในการเข้าใช้งาน API การตลาด โดย standard_access ให้การจำกัดอัตราในระดับต่ำ

การจำกัดอัตราทั่วโลก

ในช่วงที่มีการส่งโหลดทั่วโลกไปยังปลายทาง /insights สูงขึ้น ระบบจะสามารถจำกัดคำขอเพื่อปกป้องแบ็กเอนด์ได้ กรณีนี้อาจเกิดขึ้นได้ไม่บ่อยนักเมื่อมีการสืบค้นที่มีความซับซ้อนสูง (ช่วงเวลากว้าง เกณฑ์ชี้วัดที่ซับซ้อน และ/หรือมี ID อ็อบเจ็กต์โฆษณาจำนวนมาก) เข้ามาพร้อมกันมากเกินไป ซึ่งจะแสดงข้อผิดพลาดลักษณะดังนี้:

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

ในช่วงเวลาดังกล่าว แนะนำให้ลดจำนวนการเรียกใช้ รอสักครู่ แล้วสืบค้นอีกครั้ง

หลักปฏิบัติที่ดีที่สุดเกี่ยวกับขีดจำกัดอัตรา

  • การส่งการสืบค้นจำนวนมากในคราวเดียวมีแนวโน้มที่จะทริกเกอร์การจำกัดอัตราของเรา ลองกระจายการสืบค้น /insights โดยเว้นระยะระหว่างการสืบค้นแต่ละครั้งโดยตั้งเวลารอในงานของคุณ
  • ใช้ข้อมูลอัตราในส่วนหัวการตอบสนอง HTTP เพื่อควบคุมการเรียกของคุณ เพิ่มกลไกการพักงานเพื่อหน่วงเวลาหรือพักการสืบค้น /insights ของคุณเมื่อแอพพลิเคชั่นหรือบัญชีโฆษณามีการใช้งานใกล้จะถึง 100%
  • เรารายงานข้อมูลเชิงลึกของโฆษณาตามโซนเวลาของบัญชีผู้ใช้โฆษณา หากต้องการเรียกใช้ข้อมูลเชิงลึกสำหรับบัญชีผู้ใช้โฆษณาที่เชื่อมโยงรายวัน ให้ลองพิจารณาเวลาระหว่างวันโดยใช้โซนเวลาของบัญชีผู้ใช้ ซึ่งจะช่วยกระจายการสืบค้นให้ดำเนินการตลอดทั้งวันได้
  • ตรวจสอบ ads_api_access_tier ที่ระบุสิทธิ์ในการเข้าใช้งาน API การตลาด ตามค่าเริ่มเต้นแล้ว แอพจะอยู่ในระดับ development_access โดย Standard_access จะให้การจำกัดอัตราที่ต่ำกว่า หากต้องการขีดจำกัดอัตราที่สูงขึ้นและขึ้นถึงระดับมาตรฐาน คุณต้องสมัครรับ "สิทธิ์การเข้าถึงระดับสูง" กับฟีเจอร์สิทธิ์การเข้าถึงแบบมาตรฐานสำหรับการจัดการโฆษณา

งานที่ไม่ซิงค์ของ API ข้อมูลเชิงลึก

ดึงข้อมูลสถิติในอ็อบเจ็กต์จำนวนมาก และใช้งานการกรองและการเรียงลำดับ เราได้ทำให้ขั้นตอนการทำงานที่ไม่ซิงค์ง่ายดายยิ่งขึ้น:

  1. ส่งคำขอ POST ไปยังตำแหน่งข้อมูล <AD_OBJECT>/insights ซึ่งจะส่ง id ของการเรียกใช้รายงานโฆษณาคืนกลับมา
{
  "report_run_id": 6023920149050,
}

อย่าจัดเก็บ report_run_id ไว้สำหรับการใช้งานระยะยาว เนื่องจากรายการจะหมดอายุหลังจากผ่านไป 30 วัน

  1. การเรียกใช้รายงานโฆษณาจะมีข้อมูลเกี่ยวกับงานที่ไม่ซิงค์นี้ เช่น async_status ตรวจสอบสถานะช่องนี้จนกว่า async_status จะเป็น Job Completed และ async_percent_completion จะเป็น 100
{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
  1. จากนั้นคุณจะสามารถสืบค้นจุดเชื่อมโยง <AD_REPORT_RUN_ID>/insights เพื่อดึงข้อมูลผลลัพธ์ในขั้นสุดท้ายได้
{
  "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"
    }
  }
}

งานนี้จะได้รับข้อมูลสถิติทั้งหมดสำหรับบัญชีดังกล่าว และส่ง ID งานที่ไม่ซิงค์กลับมา ดังนี้

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

สถานะงานที่ไม่ซิงค์

สถานะคำอธิบาย

Job Not Started

งานยังไม่เริ่มต้น

Job Started

เริ่มต้นงานแล้ว แต่ยังไม่มีการดำเนินการ

Job Running

งานเริ่มต้นการเรียกใช้งานแล้ว

Job Completed

งานเสร็จสมบูรณ์แล้ว

Job Failed

งานล้มเหลว ตรวจสอบการสืบค้นของคุณแล้วลองอีกครั้ง

Job Skipped

งานหมดอายุและถูกข้ามไปแล้ว โปรดส่งงานของคุณใหม่ และลองอีกครั้ง

ส่งออกรายงาน

เราให้ตำแหน่งข้อมูลที่ใช้งานได้สะดวกสำหรับส่งออก <AD_REPORT_RUN_ID> เป็นรูปแบบที่มนุษย์อ่านได้และผ่านการแปลภาษาแล้ว

หมายเหตุ: ตำแหน่งข้อมูลนี้ไม่ได้เป็นส่วนหนึ่งของ API กราฟที่มีเวอร์ชั่นของเรา ดังนั้นจึงไม่เป็นไปตามนโยบายการเปลี่ยนแปลงที่สำคัญ สคริปต์และโปรแกรมต้องไม่ขึ้นอยู่กับรูปแบบของผลลัพธ์ เนื่องจากอาจมีการเปลี่ยนแปลงที่ไม่ได้คาดคิด

  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/'
ชื่อคำอธิบาย

name

สตริง

ชื่อไฟล์ที่ดาวน์โหลด

format

enum{csv,xls}

รูปแบบของไฟล์

report_run_id

จำนวนเต็ม

ID ของรายงานที่เรียกใช้

access_token

สตริง

สิทธิ์การอนุญาตที่ได้รับอนุญาตโดยผู้ใช้ที่เข้าสู่ระบบแล้ว ระบุรายการนี้เพื่อส่งออกรายงานให้กับผู้ใช้รายอื่น