الطلبات المُجمعة

يمكنك إرسال طلب HTTP فردي يحتوي على عدة استدعاءات لواجهة Graph API من فيسبوك. وتتم معالجة العمليات المستقلة بالتوازي بينما تتم معالجة العمليات غير المستقلة على التوالي. وبمجرد اكتمال جميع العمليات، تتم إعادة إرسال استجابة تجميع إليك وإغلاق اتصال HTTP.

يتطابق ترتيب الاستجابات مع ترتيب العمليات داخل الطلب. ويجب عليك معالجة الاستجابات وفقًا لذلك لتحديد العمليات الناجحة والعمليات التي تحتاج لإعادة المحاولة خلال عملية لاحقة.

التقييدات

• تقتصر طلبات التجميع على 50 طلبًا لكل دفعة. يتم احتساب كل استدعاء ضمن هذا التجميع بشكل منفصل بغرض حساب تقييدات معدلات استدعاء واجهة API وتقييدات الموارد. فعلى سبيل المثال، سيتم احتساب عملية تجميع تتألف من 10 استدعاءات لواجهة API على أنها 10 استدعاءات ويسهم كل استدعاء ضمن التجميع في حساب تقييدات موارد CPU بالطريقة نفسها. لمزيد من المعلومات، يرجى مراجعة دليل تقييد معدلات الاستدعاء.
• لا يمكن أن تتضمن طلبات التجميع مجموعات إعلانية متعددة ضمن الحملة الإعلانية نفسها. تعرَّف على المزيد حول تجميع طلبات واجهة API التسويق.

الطلب المُجمع

يتطلب أي طلب مُجمع وجود كائن JSON يتكون من مصفوفة من طلباتك. ويُرجع مصفوفة من استجابات HTTP المنطقية المتوفرة في صورة مصفوفات بلغة JSON. ولكل استجابة رمز برمجي لحالة ما ومصفوفة عناوين اختيارية ونص أساسي اختياري (عبارة عن سلسلة مشفّرة بلغة JSON).

لإجراء طلب مُجمع، أرسل طلب POST إلى نقطة نهاية حيث تكون المعلمة batch كائن JSON الخاص بك.

POST /ENDPOINT?batch=[JSON-OBJECT]

عينة من طلب التجميع

ففي هذا المثال، نحصل على معلومات حول صفحتين يديرهما تطبيقنا.

curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

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

عينة من الاستجابة

يحتوي حقل النص الأساسي على كائن سلسلة مشفّرة بلغة JSON:

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

طلبات التجميع المعقدة

يمكن تجميع العمليات التي تستخدم عادةً أساليب HTTP مختلفة ضمن طلب تجميع واحد. وعلى الرغم من أن العمليتين GET وDELETE لا يمكنهما سوى أن تتضمنا الحقلين relative_url وmethod، فإن العمليتين POST وPUT قد تتضمنان حقل body الاختياري. ويجب تنسيق النص الأساسي كسلسلة HTTP POST جديدة مشابهة لسلسلة استعلام عنوان URL.

عينة من الطلب

ففي المثال التالي، يتم نشر المنشور في إحدى الصفحات التي نديرها ونتمتع بأذونات النشر بها، ثم في موجز الصفحة خلال عملية واحدة:

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

تكون مخرجات هذا الاستدعاء كما يلي:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

ففي المثال التالي، يتم إنشاء إعلان جديد لحملة إعلانية، ثم الحصول على تفاصيل حول الكائن الذي تم إنشاؤه حديثًا. ولاحظ URLEncoding لمعلمة النص الأساسي:

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

يضيف المثال التالي صفحات متعددة إلى مدير الأعمال:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

حيث يكون:

• <ACCESS_TOKEN> هو رمز وصول يتضمن الإذن business_management.
• <BUSINESS_ID> هو معرف مدير الأعمال الذي يجب مطالبة الصفحات إليه.
• <PAGE_ID_n> هي معرفات الصفحة التي يجب مطالبتها.

الأخطاء

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

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

ويجب أن تكتمل الطلبات الأخرى داخل عملية التجميع بنجاح وسيتم إرجاعها كالمعتاد برمز الحالة 200.

حالات انتهاء المهلة

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

استدعاءات التجميع باستخدام JSONP

تدعم واجهة API التجميع JSONP كما هو الحال في بقية واجهة Graph API - يتم تحديد وظيفة استدعاء JSONP باستخدام معلمة نشر نموذج أو معلمة سلسلة استعلام callback.

استخدام رموز الوصول المتعددة

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

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

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

تحميل البيانات الثنائية

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

يعرض المثال التالي كيفية تحميل صورتين في استدعاء تجميع واحد:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com