تكامل Google Contacts

نظرة عامة

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

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

قبل استخدام تكامل Google Contacts، تأكد من توفر ما يلي:

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

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

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

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

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

uv add crewai-tools

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

export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"

أو أضفه إلى ملف .env:

CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token

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

google_contacts/get_contacts

الوصف: استرجاع جهات اتصال المستخدم من 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

google_contacts/search_contacts

الوصف: البحث عن جهات اتصال باستخدام سلسلة استعلام.

المعاملات:

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

google_contacts/list_directory_people

الوصف: عرض قائمة الأشخاص في دليل المستخدم المصادق عليه.

المعاملات:

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

google_contacts/search_directory_people

الوصف: البحث عن أشخاص في الدليل.

المعاملات:

query (string, مطلوب): استعلام البحث
sources (string, مطلوب): مصادر الدليل (استخدم ‘DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE’)
pageSize (integer, اختياري): عدد النتائج المراد إرجاعها
readMask (string, اختياري): الحقول المراد قراءتها

google_contacts/list_other_contacts

الوصف: عرض جهات الاتصال الأخرى (غير الموجودة في جهات الاتصال الشخصية).

المعاملات:

pageSize (integer, اختياري): عدد جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000
pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
readMask (string, اختياري): الحقول المراد قراءتها
requestSyncToken (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false

google_contacts/search_other_contacts

الوصف: البحث في جهات الاتصال الأخرى.

المعاملات:

query (string, مطلوب): استعلام البحث
readMask (string, مطلوب): الحقول المراد قراءتها (مثال: ‘names,emailAddresses’)
pageSize (integer, اختياري): عدد النتائج

google_contacts/get_person

الوصف: الحصول على معلومات الاتصال لشخص واحد بواسطة اسم المورد.

المعاملات:

resourceName (string, مطلوب): اسم المورد للشخص المراد الحصول عليه (مثال: ‘people/c123456789’)
personFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘names,emailAddresses,phoneNumbers’). الافتراضي: names,emailAddresses,phoneNumbers

google_contacts/create_contact

الوصف: إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم.

المعاملات:

names (array, اختياري): أسماء الشخص

[
  {
    "givenName": "John",
    "familyName": "Doe",
    "displayName": "John Doe"
  }
]

emailAddresses (array, اختياري): عناوين البريد الإلكتروني
```
[
  {
    "value": "[email protected]",
    "type": "work"
  }
]
```

phoneNumbers (array, اختياري): أرقام الهاتف

[
  {
    "value": "+1234567890",
    "type": "mobile"
  }
]

addresses (array, اختياري): العناوين البريدية

[
  {
    "formattedValue": "123 Main St, City, State 12345",
    "type": "home"
  }
]

organizations (array, اختياري): المؤسسات/الشركات

[
  {
    "name": "Company Name",
    "title": "Job Title",
    "type": "work"
  }
]

google_contacts/update_contact

الوصف: تحديث معلومات جهة اتصال موجودة.

المعاملات:

resourceName (string, مطلوب): اسم المورد للشخص المراد تحديثه (مثال: ‘people/c123456789’)
updatePersonFields (string, مطلوب): الحقول المراد تحديثها (مثال: ‘names,emailAddresses,phoneNumbers’)
names (array, اختياري): أسماء الشخص
emailAddresses (array, اختياري): عناوين البريد الإلكتروني
phoneNumbers (array, اختياري): أرقام الهاتف

google_contacts/delete_contact

الوصف: حذف جهة اتصال من دفتر عناوين المستخدم.

المعاملات:

resourceName (string, مطلوب): اسم المورد للشخص المراد حذفه (مثال: ‘people/c123456789’)

google_contacts/batch_get_people

الوصف: الحصول على معلومات عن عدة أشخاص في طلب واحد.

المعاملات:

resourceNames (array, مطلوب): أسماء موارد الأشخاص المراد الحصول عليهم. الحد الأقصى: 200 عنصر
personFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘names,emailAddresses,phoneNumbers’). الافتراضي: names,emailAddresses,phoneNumbers

google_contacts/list_contact_groups

الوصف: عرض مجموعات جهات اتصال المستخدم (التصنيفات).

المعاملات:

pageSize (integer, اختياري): عدد مجموعات جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000
pageToken (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها.
groupFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘name,memberCount,clientData’). الافتراضي: name,memberCount

google_contacts/get_contact_group

الوصف: الحصول على مجموعة جهات اتصال محددة بواسطة اسم المورد.

المعاملات:

resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: ‘contactGroups/myContactGroup’)
maxMembers (integer, اختياري): الحد الأقصى لعدد الأعضاء المراد تضمينهم. الحد الأدنى: 0، الحد الأقصى: 20000
groupFields (string, اختياري): الحقول المراد تضمينها (مثال: ‘name,memberCount,clientData’). الافتراضي: name,memberCount

google_contacts/create_contact_group

الوصف: إنشاء مجموعة جهات اتصال جديدة (تصنيف).

المعاملات:

name (string, مطلوب): اسم مجموعة جهات الاتصال
clientData (array, اختياري): بيانات خاصة بالعميل
```
[
  {
    "key": "data_key",
    "value": "data_value"
  }
]
```

google_contacts/update_contact_group

الوصف: تحديث معلومات مجموعة جهات اتصال.

المعاملات:

resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: ‘contactGroups/myContactGroup’)
name (string, مطلوب): اسم مجموعة جهات الاتصال
clientData (array, اختياري): بيانات خاصة بالعميل
```
[
  {
    "key": "data_key",
    "value": "data_value"
  }
]
```

google_contacts/delete_contact_group

الوصف: حذف مجموعة جهات اتصال.

المعاملات:

resourceName (string, مطلوب): اسم المورد لمجموعة جهات الاتصال المراد حذفها (مثال: ‘contactGroups/myContactGroup’)
deleteContacts (boolean, اختياري): ما إذا كان يجب حذف جهات الاتصال في المجموعة أيضاً. الافتراضي: false

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

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

from crewai import Agent, Task, Crew

# Create an agent with Google Contacts capabilities
contacts_agent = Agent(
    role="Contact Manager",
    goal="Manage contacts and directory information efficiently",
    backstory="An AI assistant specialized in contact management and directory operations.",
    apps=['google_contacts']  # All Google Contacts actions will be available
)

# Task to retrieve and organize contacts
contact_management_task = Task(
    description="Retrieve all contacts and organize them by company affiliation",
    agent=contacts_agent,
    expected_output="Contacts retrieved and organized by company with summary report"
)

# Run the task
crew = Crew(
    agents=[contacts_agent],
    tasks=[contact_management_task]
)

crew.kickoff()

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

from crewai import Agent, Task, Crew

directory_manager = Agent(
    role="Directory Manager",
    goal="Search and manage directory people and contacts",
    backstory="An AI assistant that specializes in directory management and people search.",
    apps=[
        'google_contacts/search_directory_people',
        'google_contacts/list_directory_people',
        'google_contacts/search_contacts'
    ]
)

# Task to search and manage directory
directory_task = Task(
    description="Search for team members in the company directory and create a team contact list",
    agent=directory_manager,
    expected_output="Team directory compiled with contact information"
)

crew = Crew(
    agents=[directory_manager],
    tasks=[directory_task]
)

crew.kickoff()

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

from crewai import Agent, Task, Crew

contact_curator = Agent(
    role="Contact Curator",
    goal="Create and update contact information systematically",
    backstory="An AI assistant that maintains accurate and up-to-date contact information.",
    apps=['google_contacts']
)

# Task to create and update contacts
curation_task = Task(
    description="""
    1. Search for existing contacts related to new business partners
    2. Create new contacts for partners not in the system
    3. Update existing contact information with latest details
    4. Organize contacts into appropriate groups
    """,
    agent=contact_curator,
    expected_output="Contact database updated with new partners and organized groups"
)

crew = Crew(
    agents=[contact_curator],
    tasks=[curation_task]
)

crew.kickoff()

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

from crewai import Agent, Task, Crew

group_organizer = Agent(
    role="Contact Group Organizer",
    goal="Organize contacts into meaningful groups and categories",
    backstory="An AI assistant that specializes in contact organization and group management.",
    apps=['google_contacts']
)

# Task to organize contact groups
organization_task = Task(
    description="""
    1. List all existing contact groups
    2. Analyze contact distribution across groups
    3. Create new groups for better organization
    4. Move contacts to appropriate groups based on their information
    """,
    agent=group_organizer,
    expected_output="Contacts organized into logical groups with improved structure"
)

crew = Crew(
    agents=[group_organizer],
    tasks=[organization_task]
)

crew.kickoff()

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

from crewai import Agent, Task, Crew

contact_specialist = Agent(
    role="Contact Management Specialist",
    goal="Provide comprehensive contact management across all sources",
    backstory="An AI assistant that handles all aspects of contact management including personal, directory, and other contacts.",
    apps=['google_contacts']
)

# Complex contact management task
comprehensive_task = Task(
    description="""
    1. Retrieve contacts from all sources (personal, directory, other)
    2. Search for duplicate contacts and merge information
    3. Update outdated contact information
    4. Create missing contacts for important stakeholders
    5. Organize contacts into meaningful groups
    6. Generate a comprehensive contact report
    """,
    agent=contact_specialist,
    expected_output="Complete contact management performed with unified contact database and detailed report"
)

crew = Crew(
    agents=[contact_specialist],
    tasks=[comprehensive_task]
)

crew.kickoff()

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

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

أخطاء الصلاحيات

تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة للوصول إلى جهات الاتصال
تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Contacts API
تحقق من منح صلاحيات الوصول للدليل لجهات اتصال المؤسسة

مشاكل صيغة اسم المورد

تأكد من أن أسماء الموارد تتبع الصيغة الصحيحة (مثال: ‘people/c123456789’ لجهات الاتصال)
تحقق من أن أسماء موارد مجموعات جهات الاتصال تستخدم الصيغة ‘contactGroups/groupId’
تأكد من وجود أسماء الموارد وإمكانية الوصول إليها

مشاكل البحث والاستعلام

تأكد من صحة صيغة استعلامات البحث وعدم كونها فارغة
استخدم حقول readMask المناسبة للبيانات التي تحتاجها
تحقق من صحة تحديد مصادر البحث (جهات اتصال مقابل ملفات تعريف)

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

تأكد من توفير الحقول المطلوبة عند إنشاء جهات الاتصال
تحقق من صحة صيغة عناوين البريد الإلكتروني وأرقام الهاتف
تأكد من أن معامل updatePersonFields يتضمن جميع الحقول التي يتم تحديثها

مشاكل الوصول إلى الدليل

تأكد من أن لديك الصلاحيات المناسبة للوصول إلى دليل المؤسسة
تحقق من صحة تحديد مصادر الدليل
تأكد من أن مؤسستك تسمح بالوصول عبر API إلى معلومات الدليل

الترقيم والحدود

انتبه لحدود حجم الصفحة (تختلف حسب نقطة النهاية)
استخدم pageToken للترقيم عبر مجموعات النتائج الكبيرة
احترم حدود معدل API وطبّق تأخيرات مناسبة

مجموعات جهات الاتصال والتنظيم

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

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

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

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