‏‎Graph API‎‏

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

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

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

لا تتشارك كل واجهات API ومجموعات SDK في نظام تعيين الإصدارات نفسه. فعلى سبيل المثال، يتم تعيين إصدار واجهة Graph API بنِسب مختلفة وترقيم مختلف مقارنة بمجموعة Facebook SDK لنظام iOS. وتدعم كل مجموعات Facebook SDK إمكانية التفاعل مع إصدارات مختلفة من واجهات API التي نوفرها. كما يمكن أن تتواجد إصدارات متعددة من واجهات API أو مجموعات SDK في الوقت ذاته مع وجود وظائف مختلفة في كل إصدار.

ما أحدث إصدار من واجهة Graph API؟

أحدث إصدار من واجهة Graph API هو v21.0

لماذا توجد لدينا إصدارات؟

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

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

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

يتم ضمان تشغيل كل إصدار لمدة عامين على الأقل. لن يتم السماح باستخدام الإصدار بعد مرور عامين من تاريخ طرح الإصدار الذي يليه. على سبيل المثال، إذا تم طرح الإصدار 2.3 من واجهة API في 25 مارس 2015 وتم طرح الإصدار 2.4 من واجهة API في 7 أغسطس 2015، فستنتهي صلاحية الإصدار 2.3 في 7 أغسطس 2017، أي بعد عامين من طرح الإصدار 2.4.

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

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

يمكنك العثور على معلومات محددة حول الجداول الزمنية لإصداراتنا والتغييرات وتواريخ الإصدار في صفحة سجل التغييرات المتوفرة لدينا.

ألن يطرأ أي تغيير على الإطلاق على أي إصدار؟

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

ماذا يحدث إذا لم أحدد إصدارًا لواجهة API؟

نشير إلى استدعاء واجهة API الذي تم إجراؤه دون تحديد الإصدار على أنه استدعاء غير محدد الإصدار. فعلى سبيل المثال، لنفترض أن الإصدار الحالي هو الإصدار 4.0. يكون الاستدعاء كما يلي:

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

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

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

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

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

نوصي بتحديد الإصدار دائمًا حيثما أمكن.

التقييدات

  • لا يمكنك إجراء استدعاءات واجهة API غير محددة الإصدار على مجموعة Facebook SDK للغة JavaScript.

هل يمكن لتطبيقي إجراء استدعاءات إلى إصدارات أقدم من الإصدار الحالي؟

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

تعيين إصدارات واجهة API التسويق

تتمتع واجهة API التسويق بنظام تعيين إصدارات خاص بها. تختلف كل من أرقام الإصدارات وجداولها الزمنية عن حالة الأشياء في واجهة Graph API.

تعرف على المزيد عن تعيين إصدارات واجهة API التسويق

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

واجهة Graph API

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

مربعات الحوار

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

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

المكونات الإضافية للتواصل الاجتماعي

إذا كنت تستخدم إصدارات HTML5 أو xfbml لـ المكونات الإضافية للتواصل الاجتماعي التي نوفرها، فسيتم تحديد الإصدار الذي يتم عرضه من خلال الإصدار المحدد عندما تعمل على تهيئة مجموعة JavaScript SDK.

إذا كنت تُدخل إصدار iframe أو رابطًا عاديًا لأحد مكوناتنا الإضافية، فستحتاج إلى إضافة رقم الإصدار إلى المسار المصدر في المكوِّن الإضافي:

<iframe
  src="//www.facebook.com/v21.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

إجراء طلبات محددة الإصدار من مجموعات SDK

إذا كنت تستخدم مجموعة Facebook SDK لنظام iOS أو Android أو Facebook SDK for Javascript، فستكون استدعاءات تعيين الإصدارات تلقائية إلى حدٍ كبير. لاحظ أن هذا يختلف عن كل نظام تعيين إصدارات خاص بمجموعات SDK.

JavaScript

لا يمكن أن تستخدم مجموعة JavaScript SDK إصدارات API مختلفة إلا إذا كنت تستخدم المسار sdk.js.

إذا كنت تستخدم FB.init() من مجموعة JavaScript SDK، فيجب استخدام معلمة الإصدار، على النحو التالي:

FB.init({
  appId      : '{app-id}',
  version    : 'v21.0'
});

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

إذا كنت بحاجة إلى ذلك، فيمكنك تجاوز إصدار ما عن طريق إلحاق الإصدار بمسار نقطة النهاية في استدعاء FB.api().

نظام iOS

يرتبط كل إصدار من إصدارات مجموعة Facebook SDK لنظام iOS تم طرحه بالإصدار المتوفر في تاريخ الإصدار. وهذا يعني أنه إذا كنت تعمل على الترقية إلى مجموعة SDK جديدة، فأنت تقوم أيضًا بالترقية إلى أحدث إصدار من واجهة API (على الرغم من أنه يمكنك تحديد أي إصدار متوفر وسابق لواجهة API يدويًا من خلال [FBSDKGraphRequest initWithGraphPath]). ويتم إدراج إصدار واجهة API بالتزامن مع طرح كل إصدار من إصدارات مجموعة Facebook SDK لنظام iOS.

وعلى غرار مجموعة JavaScript SDK، تتم إضافة الإصدار مسبقًا إلى أي استدعاءات تجريها لواجهة graph API من خلال مجموعة Facebook SDK لنظام iOS. على سبيل المثال، إذا كان v2.7 هو أحدث إصدار لواجهة API، فسيعمل الاستدعاء /me/friends، الذي تم استخدامه في عينة الرمز البرمجي التالية، على استدعاء /v2.7/me/friends في الواقع:

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

يمكنك تجاوز إصدار الاستدعاء من خلال [FBSDKGraphRequestConnection overrideVersionPartWith].

نظام Android

يرتبط كل إصدار من إصدارات مجموعة Facebook SDK لنظام Android تم طرحه بالإصدار المتوفر في تاريخ الإصدار. وهذا يعني أنه إذا كنت تعمل على الترقية إلى مجموعة SDK جديدة، فأنت تقوم أيضًا بالترقية إلى أحدث إصدار من واجهة API (على الرغم من أنه يمكنك تحديد أي إصدار متوفر وسابق لواجهة API يدويًا من خلال GraphRequest.setVersion()). ويتم إدراج إصدار واجهة API بالتزامن مع طرح كل إصدار من إصدارات مجموعة Facebook SDK لنظام Android.

وعلى غرار مجموعة JavaScript SDK، تتم إضافة الإصدار مسبقًا إلى أي استدعاءات تجريها لواجهة graph API من خلال مجموعة Facebook SDK لنظام Android. على سبيل المثال، إذا كان v2.7 هو أحدث إصدار لواجهة API، فسيعمل الاستدعاء /me، الذي تم استخدامه في عينة الرمز البرمجي التالية، على استدعاء /v2.7/me في الواقع:

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

يمكنك تجاوز إصدار الاستدعاء من خلال GraphRequest.setVersion().