الانتقال إلى المحتوى الرئيسي

نظرة عامة

مكّن وكلاءك من إدارة جهات الاتصال ومعلومات الدليل عبر Google Contacts. يمكنك الوصول إلى جهات الاتصال الشخصية، والبحث في أشخاص الدليل، وإنشاء معلومات الاتصال وتحديثها، وإدارة مجموعات جهات الاتصال باستخدام الأتمتة المدعومة بالذكاء الاصطناعي.

المتطلبات الأساسية

قبل استخدام تكامل Google Contacts، تأكد من توفر ما يلي:
  • حساب CrewAI AMP مع اشتراك فعّال
  • حساب Google مع إمكانية الوصول إلى Google Contacts
  • ربط حساب Google الخاص بك عبر صفحة التكاملات

إعداد تكامل Google Contacts

1. ربط حساب Google الخاص بك

  1. انتقل إلى تكاملات CrewAI AMP
  2. ابحث عن Google Contacts في قسم تكاملات المصادقة
  3. انقر على Connect وأكمل عملية OAuth
  4. امنح الصلاحيات اللازمة للوصول إلى جهات الاتصال والدليل
  5. انسخ رمز المؤسسة من إعدادات التكامل

2. تثبيت الحزمة المطلوبة

3. إعداد متغير البيئة

لاستخدام التكاملات مع Agent(apps=[]), يجب تعيين متغير البيئة CREWAI_PLATFORM_INTEGRATION_TOKEN برمز المؤسسة الخاص بك.
أو أضفه إلى ملف .env:

الإجراءات المتاحة

الوصف: استرجاع جهات اتصال المستخدم من Google Contacts.المعاملات:
  • pageSize (integer, اختياري): عدد جهات الاتصال المراد إرجاعها (الحد الأقصى 1000). الحد الأدنى: 1، الحد الأقصى: 1000
  • pageToken (string, اختياري): رمز الصفحة المراد استرجاعها.
  • personFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘names,emailAddresses,phoneNumbers’). الافتراضي: names,emailAddresses,phoneNumbers
  • requestSyncToken (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false
  • sortOrder (string, اختياري): ترتيب الفرز للاتصالات. الخيارات: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING
الوصف: البحث عن جهات اتصال باستخدام سلسلة استعلام.المعاملات:
  • query (string, مطلوب): سلسلة استعلام البحث
  • readMask (string, مطلوب): الحقول المراد قراءتها (مثال: ‘names,emailAddresses,phoneNumbers’)
  • pageSize (integer, اختياري): عدد النتائج المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 30
  • pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
  • sources (array, اختياري): المصادر المراد البحث فيها. الخيارات: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. الافتراضي: READ_SOURCE_TYPE_CONTACT
الوصف: عرض قائمة الأشخاص في دليل المستخدم المصادق عليه.المعاملات:
  • sources (array, مطلوب): مصادر الدليل المراد البحث فيها. الخيارات: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. الافتراضي: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE
  • pageSize (integer, اختياري): عدد الأشخاص المراد إرجاعهم. الحد الأدنى: 1، الحد الأقصى: 1000
  • pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
  • readMask (string, اختياري): الحقول المراد قراءتها (مثال: ‘names,emailAddresses’)
  • requestSyncToken (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false
  • mergeSources (array, اختياري): بيانات إضافية لدمجها في استجابات أشخاص الدليل. الخيارات: CONTACT
الوصف: البحث عن أشخاص في الدليل.المعاملات:
  • query (string, مطلوب): استعلام البحث
  • sources (string, مطلوب): مصادر الدليل (استخدم ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’)
  • pageSize (integer, اختياري): عدد النتائج المراد إرجاعها
  • readMask (string, اختياري): الحقول المراد قراءتها
الوصف: عرض جهات الاتصال الأخرى (غير الموجودة في جهات الاتصال الشخصية).المعاملات:
  • pageSize (integer, اختياري): عدد جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000
  • pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
  • readMask (string, اختياري): الحقول المراد قراءتها
  • requestSyncToken (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false
الوصف: البحث في جهات الاتصال الأخرى.المعاملات:
  • query (string, مطلوب): استعلام البحث
  • readMask (string, مطلوب): الحقول المراد قراءتها (مثال: ‘names,emailAddresses’)
  • pageSize (integer, اختياري): عدد النتائج
الوصف: الحصول على معلومات الاتصال لشخص واحد بواسطة اسم المورد.المعاملات:
  • resourceName (string, مطلوب): اسم المورد للشخص المراد الحصول عليه (مثال: ‘people/c123456789’)
  • personFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘names,emailAddresses,phoneNumbers’). الافتراضي: names,emailAddresses,phoneNumbers
الوصف: إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم.المعاملات:
  • names (array, اختياري): أسماء الشخص
  • emailAddresses (array, اختياري): عناوين البريد الإلكتروني
  • phoneNumbers (array, اختياري): أرقام الهاتف
  • addresses (array, اختياري): العناوين البريدية
  • organizations (array, اختياري): المؤسسات/الشركات
الوصف: تحديث معلومات جهة اتصال موجودة.المعاملات:
  • resourceName (string, مطلوب): اسم المورد للشخص المراد تحديثه (مثال: ‘people/c123456789’)
  • updatePersonFields (string, مطلوب): الحقول المراد تحديثها (مثال: ‘names,emailAddresses,phoneNumbers’)
  • names (array, اختياري): أسماء الشخص
  • emailAddresses (array, اختياري): عناوين البريد الإلكتروني
  • phoneNumbers (array, اختياري): أرقام الهاتف
الوصف: حذف جهة اتصال من دفتر عناوين المستخدم.المعاملات:
  • resourceName (string, مطلوب): اسم المورد للشخص المراد حذفه (مثال: ‘people/c123456789’)
الوصف: الحصول على معلومات عن عدة أشخاص في طلب واحد.المعاملات:
  • resourceNames (array, مطلوب): أسماء موارد الأشخاص المراد الحصول عليهم. الحد الأقصى: 200 عنصر
  • personFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘names,emailAddresses,phoneNumbers’). الافتراضي: names,emailAddresses,phoneNumbers
الوصف: عرض مجموعات جهات اتصال المستخدم (التصنيفات).المعاملات:
  • pageSize (integer, اختياري): عدد مجموعات جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000
  • pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
  • groupFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘name,memberCount,clientData’). الافتراضي: name,memberCount
الوصف: الحصول على مجموعة جهات اتصال محددة بواسطة اسم المورد.المعاملات:
  • resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: ‘contactGroups/myContactGroup’)
  • maxMembers (integer, اختياري): الحد الأقصى لعدد الأعضاء المراد تضمينهم. الحد الأدنى: 0، الحد الأقصى: 20000
  • groupFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘name,memberCount,clientData’). الافتراضي: name,memberCount
الوصف: إنشاء مجموعة جهات اتصال جديدة (تصنيف).المعاملات:
  • name (string, مطلوب): اسم مجموعة جهات الاتصال
  • clientData (array, اختياري): بيانات خاصة بالعميل
الوصف: تحديث معلومات مجموعة جهات اتصال.المعاملات:
  • resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: ‘contactGroups/myContactGroup’)
  • name (string, مطلوب): اسم مجموعة جهات الاتصال
  • clientData (array, اختياري): بيانات خاصة بالعميل
الوصف: حذف مجموعة جهات اتصال.المعاملات:
  • resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال المراد حذفها (مثال: ‘contactGroups/myContactGroup’)
  • deleteContacts (boolean, اختياري): ما إذا كان يجب حذف جهات الاتصال في المجموعة أيضاً. الافتراضي: false

أمثلة الاستخدام

إعداد Agent أساسي لـ Google Contacts

البحث في الدليل وإدارته

إنشاء جهات الاتصال وتحديثاتها

إدارة مجموعات جهات الاتصال

إدارة جهات الاتصال الشاملة

استكشاف الأخطاء وإصلاحها

المشاكل الشائعة

أخطاء الصلاحيات
  • تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة للوصول إلى جهات الاتصال
  • تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Contacts API
  • تحقق من منح صلاحيات الوصول للدليل لجهات اتصال المؤسسة
مشاكل صيغة اسم المورد
  • تأكد من أن أسماء الموارد تتبع الصيغة الصحيحة (مثال: ‘people/c123456789’ لجهات الاتصال)
  • تحقق من أن أسماء موارد مجموعات جهات الاتصال تستخدم الصيغة ‘contactGroups/groupId’
  • تأكد من وجود أسماء الموارد وإمكانية الوصول إليها
مشاكل البحث والاستعلام
  • تأكد من صحة صيغة استعلامات البحث وعدم كونها فارغة
  • استخدم حقول readMask المناسبة للبيانات التي تحتاجها
  • تحقق من صحة تحديد مصادر البحث (جهات اتصال مقابل ملفات تعريف)
إنشاء جهات الاتصال وتحديثاتها
  • تأكد من توفير الحقول المطلوبة عند إنشاء جهات الاتصال
  • تحقق من صحة صيغة عناوين البريد الإلكتروني وأرقام الهاتف
  • تأكد من أن معامل updatePersonFields يتضمن جميع الحقول التي يتم تحديثها
مشاكل الوصول إلى الدليل
  • تأكد من أن لديك الصلاحيات المناسبة للوصول إلى دليل المؤسسة
  • تحقق من صحة تحديد مصادر الدليل
  • تأكد من أن مؤسستك تسمح بالوصول عبر API إلى معلومات الدليل
الترقيم والحدود
  • انتبه لحدود حجم الصفحة (تختلف حسب نقطة النهاية)
  • استخدم pageToken للترقيم عبر مجموعات النتائج الكبيرة
  • احترم حدود معدل API وطبّق تأخيرات مناسبة
مجموعات جهات الاتصال والتنظيم
  • تأكد من أن أسماء مجموعات جهات الاتصال فريدة عند إنشاء مجموعات جديدة
  • تحقق من وجود جهات الاتصال قبل إضافتها إلى المجموعات
  • تأكد من أن لديك صلاحيات تعديل مجموعات جهات الاتصال

الحصول على المساعدة

تحتاج مساعدة؟

تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Contacts أو استكشاف الأخطاء وإصلاحها.