‏‎Workplace‎‏

مرجع Graph API

نظرة عامة

تُعد Graph API في Workplace طريقة برمجية لإدخال البيانات إلى Workplace والحصول عليها منها. فهي عبارة عن API بسيطة مستندة إلى HTTP يمكنك استخدامها في الاستعلام عن البيانات حول الكائنات في رسم بياني لـ Workplace.

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

كائنات Graph API في Workplace

يمكن الوصول إلى العُقد التالية من خلال Workplace Graph API باستخدام دمج مخصص أو رمز وصول لتطبيق تابع لجهة خارجية.

Community

مجتمع Workplace. المجموعة الجذرية لاستدعاءات واجهة Graph API في Workplace التي تجريها.

Groups

مجموعة Workplace.

Posts

تمثل منشورًا تمت كتابته في مجموعة أو على ملف شخصي لأحد الأعضاء.

Members

حساب مستخدم Workplace محدد. يتم استخدام هذه العقدة أيضًا لعرض الرسائل المستلمة والمرسلة بواسطة هذا المستخدم وتعديلها.

Skills

مهارة تُضاف إلى الملف الشخصي للعضو.

Event

حدث في مجموعة أو مجتمع Workplace

Category

فئة في مكتبة المعرفة لتخزين محتوى الشركة المهم.

People Set

مجموعة من الأشخاص يتم تحديدهم باستخدام المعايير أو القوائم.

Reported Content

المحتوى المتوفر على Workplace الذي تم الإبلاغ عنه للمراجعة بواسطة مسؤول.

Shift

بيانات جدول الورديات للعاملين بالساعة على Workplace.

Survey

الاستبيانات التي تم إنشاؤها على Workplace.

Data Export

وظائف تصدير البيانات لتصدير البيانات المجمّعة من Workplace.

للاطلاع على أمثلة حول دمج استدعاءات Graph API لحل مشكلات معينة، ألقِ نظرة على قائمة عينة من التطبيقات.

استخدام Graph API

كائنات واجهة Graph API

تُعد واجهة Graph API تمثيلاً للمعلومات على Workplace، وتتألف من:

  • العُقَد - كائنات مثل "مستخدم"، "صورة"، "منشور"، "تعليق"
  • عناصر الربط - الاتصالات بين هذه "الأشياء"، مثل ملف منشور أو تعليقات على صورة
  • الحقول - بيانات التعريف حول كائنات، مثل اسم شخص أو خصوصية مجموعة

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

إدارة المجتمع

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

لأغراض الوصول إلى Graph API، يتم التعامل مع مجتمعك باعتباره مجموعة. ويمكنك النظر إلى مجتمعك باعتباره مجموعة جذرية، حيث تتم إضافة كل مجموعاتك ضمنها كمجموعات تابعة. لاسترداد معلومات حول مجتمعك في واجهة Graph API، ستحتاج إلى معرف المجتمع، الذي تم استرداده برمجيًا من واجهة Graph API، عن طريق إجراء طلب HTTP GET إلى graph.facebook.com/community يتضمن رمز وصول تطبيق صالح.

تعيين إصدارات واجهة Graph API

تستند واجهة Graph API في Workplace إلى واجهة Graph API لمنصة فيسبوك. وهذا يعني أنها تكتسب سلوك تعيين إصدارات API نفسه المستخدم على فيسبوك.

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

عند إجراء استدعاء API لواجهة Graph API، يمكنك تحديد إصدار في مسار API، كما يلي:

      https://graph.facebook.com/v2.11/community/groups

ومع ذلك، توجد بعض التقييدات على الإصدارات المتوفرة:

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

عند إنشاء دمج مخصص جديد، سيكون الحد الأدنى لإصدار API المتوفر هو إصدار API الحالي في وقت الإنشاء. ويؤثر هذا الإصدار الأدنى على كل من استدعاءات واجهة Graph API واشتراكات Webhook.

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

التحقق من إصدار واجهة Graph API

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

      https://graph.facebook.com/community?debug=all

وسيؤدي هذا إلى إرجاع معلومات تصحيح أخطاء إضافية تؤكد على الإصدار المستخدم.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

إذا كنت تحاول استخدام إصدار أقدم من الحد الأدنى لإصدار API المخصص لتطبيقك، فستخبرك الرسالة debug.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

التحقق من إصدارات Webhook

تستخدم اشتراكات Webhook الحد الأدنى لإصدار API إذا تم إجراء الاشتراك عبر مربع الحوار المنبثق للدمج المخصص أو كان إصدار API المحدد هو الاشتراك الذي تم عبر نقطة نهاية واجهة Graph API للاشتراكات، /app/subscriptions.

يمكنك استخدام نقطة نهاية الاشتراكات لتأكيد إصدار webhook المستخدم لكل حقل أو موضوع webhook. تتطلب نقطة النهاية هذه رمز وصول التطبيق.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...

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

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

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

الحصول على رمز وصول التطبيق

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

لمعرفة المزيد حول إنشاء التطبيقات ونموذج الإذن، راجع دليل الأذونات.

الحصول على رمز وصول العضو

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

يمكنك استدعاء رمز وصول عضو ما من خلال إرسال طلب GET لنقطة النهاية /member_id المرتبطة برقم محدد، وذلك باستخدام رمز وصول المسؤول وطلب الحقل الإضافي impersonate_token.

تتطلب هذه الوظيفة إذن انتحال الشخصية للتطبيق الذي يُجري الاستدعاء.

انتحال الشخصية هو إذن تم إيقاف استخدامه. لذلك لا تحاول إنشاء وظيفة جديدة باستخدام هذا الإذن. لم يعد من الممكن إضافة هذا الإذن إلى عمليات الدمج المخصصة.

لا يمكن استدعاء رموز انتحال الشخصية إلا للحسابات التي تمت المطالبة بها.