‏API التسويق‏

تعيين الإصدارات

الإصدار الحالي من API التسويق هو v21.0.

تتضمن منصة فيسبوك نموذجًا أساسيًا وموسّعًا لتعيين الإصدارات. عند تعيين الإصدارات في API التسويق، سيتم طرح كل التغييرات العاجلة في إصدار جديد. يمكن أن تتواجد عدة إصدارات من واجهات API التسويق أو مجموعات SDK في وقت واحد مع توفر وظائف مختلفة في كل إصدار.

يجب أن يدرك المطوّرون مسبقًا متى ستتغير API التسويق أو مجموعة SDK. على الرغم من توفر إطار زمني مقداره 90 يومًا لإدخال التغييرات، فإن اختيار طريقة الانتقال إلى الإصدار الجديد وموعده يرجع لك.

الجداول الزمنية للإصدارات

عند طرح إصدار جديد من API التسويق، سنستمر في دعم الإصدار السابق من API التسويق لمدة 90 يومًا على الأقل. تتوفر لديك مدة 90 يومًا على الأقل للانتقال إلى الإصدار الجديد. خلال فترة السماح البالغة 90 يومًا، يمكنك استدعاء كل من الإصدار الحالي والإصدار الذي تم إيقاف استخدامه، ولديك فترة سماح مدتها 90 يومًا للانتقال إلى الإصدار الجديد. بعد انتهاء فترة الـ 90 يومًا المحددة، يتوقف الإصدار الذي تم إيقاف استخدامه عن العمل. بمجرد أن يصبح الإصدار غير متوفر، قد تفشل أي استدعاءات يتم إجراؤها لرقم الإصدار هذا أو تتم ترقيتها إلى الإصدار التالي المتوفر.

على سبيل المثال، تم طرح الإصدار 17.0 من API التسويق في 23 مايو 2023، وانتهت صلاحية الإصدار 16.0 من API التسويق في 6 فبراير 2024، ما يوفر 90 يومًا على الأقل للانتقال إلى الإصدار الجديد.

فيما يلي عينة من اليوميات. لاحظ أنه ليس بالضرورة دائمًا أن نطرح إصدارًا جديدًا في نهاية فترة السماح البالغة 90 يومًا من إيقاف استخدام الإصدار السابق. في المثال التالي، تم إيقاف استخدام الإصدار 16.0 قبل فترة من طرح الإصدار 18.0:

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

إجراء طلبات محددة الإصدار

تتوفر كل نقاط النهاية في API التسويق من خلال مسار محدد الإصدار. ضع معرف الإصدار في بداية مسار الطلب. على سبيل المثال:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

يناسب ذلك كل الإصدارات حسب النموذج العام التالي:

https://graph.facebook.com/v{n}/{request-path}

حيث تشير n إلى الإصدار المطلوب. يمكنك الاطلاع على قائمة كاملة بالإصدارات المتوفرة في سجل التغييرات. توفر جميع مراجع API التسويق لدينا معلومات حسب الإصدار.

عمليات الترحيل

لا تختص عمليات الترحيل إلا بسيناريوهات خاصة حيث يلزم فيها إجراء تغييرات لا يمكن أن تدخل في عملية تعيين الإصدارات. غالبًا يكون ذلك في حالة تغيير نموذج البيانات الأساسية. تنطبق عمليات الترحيل على كل الإصدارات.

يتم إدراج عمليات الترحيل التي لا تزال قيد التقدم في صفحة عمليات الترحيل. توفر عمليات الترحيل إطارًا زمنيًا مدته 90 يومًا على الأقل بحيث يجب عليك ترحيل تطبيقك خلاله. بمجرد بدء الإطار الزمني، يصبح سلوك ما بعد الترحيل هو الإعداد الافتراضي للتطبيقات الجديدة. بعد ذلك وعند اكتمال الإطار الزمني المسموح به للترحيل، لن يتوفر سلوك ما قبل الترحيل بعد ذلك مطلقًا.

إدارة عمليات الترحيل عبر Graph API

يمكن إدارة عمليات الترحيل عبر حقل عمليات الترحيل في العقدة /app:

يمكنك إجراء استدعاء تحديث على عنصر الربط لتنشيط عمليات الترحيل وإلغاء تنشيطها.

إدارة عمليات الترحيل عبر لوحة معلومات التطبيق

يمكنك تنشيط عمليات الترحيل المتوفرة وإلغاء تنشيطها من لوحة معلومات التطبيق ضمن الإعدادات > عمليات الترحيل. يرجى ملاحظة أنه قد لا تتطابق قائمة عمليات الترحيل كما هو موضح في الصورة التالية حيث تختلف عمليات الترحيل المتوفرة باختلاف التطبيقات والأوقات. إذا رأيت Use Graph API v2.0 by default لترحيل ما، فيختص ذلك بـ Graph API فقط وليس API التسويق.

التنشيط المؤقت لعمليات الترحيل من جانب العميل

بدلاً من تنشيط الترحيل من خلال لوحة معلومات التطبيق أو عبر API التسويق، يمكن بدلاً من ذلك إضافة علامة خاصة إلى استدعاءات API التسويق التي تقوم بتعيين الترحيل. تُعرف العلامة باسم migrations_override وتتطلب منك تحديد فقاعة بلغة JSON تشرح عمليات الترحيل التي تريد تشغيلها أو إيقاف تشغيلها. على سبيل المثال، إذا كنت تقوم بإجراء استدعاء صف، فيمكنك إدخال:

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

عند استخدام ذلك، يمكنك استدعاء API التسويق الجديدة من خلال تحديثات العميل بدلاً من الحاجة إلى فرض التحديث على كل القائمين بالاستدعاء بشأن استدعاء API التسويق الجديدة في الوقت نفسه. يمكن الاستفادة من ذلك بشكل كبير أيضًا في تصحيح الأخطاء.

يمكن العثور على أسماء عمليات الترحيل هذه في العقدة /app المذكورة أعلاه.

الترقية التلقائية للإصدار

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

على سبيل المثال، في 14 مايو 2024، سيتم إيقاف استخدام الإصدار 17.0. وفقًا لسجل تغييرات الإصدار 18.0، ستتأثر نقاط النهاية التالية:

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

إذا قام التطبيق باستدعاء POST /{adset-id} من خلال الإصدار 17.0 بعد إيقاف استخدامه في 14 مايو 2024، فسيفشل طلب API هذا حيث إنه لم يتم تطبيق الترقية التلقائية على نقاط النهاية المتأثرة في الإصدار التالي المتوفر (18.0).

إذا قام التطبيق باستدعاء GET /{ad-account-id}/insights من خلال الإصدار 17.0 بعد إيقاف استخدامه، فستعمل المنصة على ترقية الاستدعاء إلى الإصدار التالي المتوفر (18.0).

ملاحظة: إذا كان التطبيق يعمل بالفعل على إجراء استدعاءات من خلال إصدارات أحدث من الإصدار 17.0، فمن المفترض ألا يتغير شيء في تاريخ إيقاف استخدام الإصدار.

للتحقق من نقاط النهاية المتأثرة في كل إصدار، يُرجى الرجوع إلى سجل تغييرات API التسويق.

الأسئلة المتكررة

الجداول الزمنية للإصدارات

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

الرابط الثابت

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
الرابط الثابت

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
الرابط الثابت

إجراء طلبات محددة الإصدار

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

الرابط الثابت

الترقية التلقائية للإصدار

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

الرابط الثابت

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
الرابط الثابت

You can look up affected endpoints from Marketing API Changelog.

الرابط الثابت

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

الرابط الثابت

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
الرابط الثابت