مرجع واجهة Graph API

نظرة عامة

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

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

يمكن العثور على المزيد من المعلومات حول كيفية استخدام واجهة Graph API في Workplace فيما يلي:

كائنات واجهة Graph API في Workplace

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

المجتمع

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

المجموعات

مجموعة Workplace.

المنشورات

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

الأعضاء

حساب مستخدم 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 تقريبًا كل ثلاثة أشهر ويتم نشر التغييرات عبر كل واجهات Graph 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 الذي يمكن استخدامه مع تطبيقك، يمكنك إضافة المعلمة 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"
              },
      ...
    

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

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

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

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