التقييدات وأفضل الممارسات

توفر API الرؤى في فيسبوك بيانات حول الأداء من الحملات التسويقية على فيسبوك. ولحماية أداء النظام وضمان استقراره، نحرص على اتخاذ تدابير وقائية لتوزيع موارد النظام بين التطبيقات بطريقة متساوية. علمًا بأن كل السياسات الموضحة أدناه خاضعة للتغيير.

تقييدات البيانات لكل استدعاء

نستخدم تقييدات البيانات لكل استدعاء لمنع الاستعلام من استرداد كمية كبيرة جدًا من البيانات لا يمكن للنظام معالجتها. ويتوفر لدينا نوعان من تقييدات البيانات:

1. حسب عدد الصفوف في الاستجابة،
2. وحسب عدد نقاط البيانات المطلوبة لحساب الإجمالي، مثل صف الملخص.

يسري هذان النوعان من التقييدات على استدعاءات /insights المتزامنة وغير المتزامنة، وسنقوم بإرجاع رسالة خطأ:

error_code = 100,  CodeException (error subcode: 1487534)

أفضل الممارسات، تقييدات البيانات لكل استدعاء

• يمكنك تقييد استعلامك من خلال تقييد نطاق التاريخ أو عدد معرفات الإعلانات. ويمكنك أيضًا تقييد استعلامك بأدوات القياس الضرورية، أو تقسيمه إلى عدة استعلامات بحيث يختص كل منها بطلب مجموعة فرعية من أدوات القياس.
• يمكنك تجنب الاستعلامات على مستوى الحساب والتي تتضمن تقسيمات تعددية مثل action_target_id أو product_id ونطاقات تواريخ أوسع مثل الحملة كلها.
• استخدم عنصر الربط /insights مباشرة مع كائنات الإعلانات بالمستوى الأدنى لاسترداد البيانات التفصيلية لهذا المستوى. فعلى سبيل المثال، استخدم أولًا استعلامًا على مستوى الحساب للحصول على قائمة بمعرفات الكائنات بالمستوى الأدنى مع المعلمتين 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) للتعبير عن الحقول التي تندرج ضمن الكائن. لذا يرجى ملاحظة أن الفلترة باستخدام 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 يومًا من تقديم تقارير بشأنها

تقييدات تحميل استدعاء الرؤى

بعد مرور تسعين يومًا على طرح الإصدار 3.3 ويكون ساريًا على جميع الإصدارات العامة، نجري تغييرًا على تقييد معدلات الاستدعاء على مستوى الحساب الإعلاني بحيث يعكس الحجم اللازم لاستدعاءات واجهة API. ونحسب حصة تقييد معدلات الاستدعاء بناءً على طبقة الوصول إلى واجهة 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 لمعرفة معدلها، بالإضافة إلى الموارد التي تطلبها. ونسمح بحد ثابت للتحميل لكل تطبيق في الثانية الواحدة. وعند تجاوز هذا الحد، تتعرض طلباتك للفشل.

تحقق من عنوان x-fb-ads-insights-throttle HTTP الموجود في كل استجابة لواجهة API لمعرفة مدى اقتراب تطبيقك من الحد المخصص له، بالإضافة إلى إمكانية تقييم مدى أهمية استعلام معين. وتخضع استدعاءات الرؤى أيضًا إلى تقييدات الحساب الإعلاني الافتراضي الموضحة في عنوان HTTP لـ x-ad-account-usage. ويمكن العثور على مزيد من التفاصيل في واجهة API التسويق، أفضل الممارسات

بمجرد وصول تطبيق ما إلى الحد الأقصى المسموح به، يتلقى الاستدعاء استجابة خطأ مع error_code = 4, CodedException. يجب أن تحتفظ بحد أقل من الحد االأقصى المسموح به بقدر مناسب. وإذا بلغ تطبيقك الحد الأقصى المسموح به، فيتم السماح بنسبة محدودة فقط من الطلبات استنادًا إلى الاستعلام والتقييم.

نطبق تقييد معدلات الاستدعاء على كل تطبيق يرسل استدعاءات /insights متزامنة وغير متزامنة معًا. ويتم حساب تقييدات لاثنتين من المعلمات الرئيسية حسب التطبيق والحساب الإعلاني.

فيما يلي مثال على عنوان 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 ذي الصلة.
• acc_id_util_pct — تم استهلاك النسبة المئوية للسعة المخصصة للمعرف الإعلاني account_id ذي الصلة.
• ads_api_access_tier — تسمح المستويات للتطبيق بالوصول إلى API التسويق. يعمل standard_access على تمكين تقييد معدلات الاستدعاء الأقل.

تقييدات معدلات الاستدعاء العالمية

خلال فترات الحمل العالمي المرتفع لنقطة النهاية /insights، بإمكان النظام تقييد الطلبات لحماية الخلفية. يمكن أن يحدث ذلك في حالات نادرة عندما تأتي العديد من الاستعلامات ذات تعقيد عالي (نطاقات زمنية كبيرة وأدوات قياس معقدة و/أو عدد كبير من معرفات الكائنات الإعلانية) في الوقت ذاته. سيؤدي ذلك إلى خطأ يبدو كما يلي:

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"
    }
  }
}
    

تحصل هذه الوظيفة على كل إحصاءات الحساب وتقوم بإرجاع أي معرف وظيفة غير متزامنة:

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

حالة الوظيفة غير المتزامنة

تصدير التقارير

نوفر نقطة نهاية سهلة لتصدير <AD_REPORT_RUN_ID> إلى تنسيق محلي يمكن للأشخاص قراءته.

ملاحظة: لا تمثل نقطة النهاية هذه جزءًا من واجهة Graph 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/'