MCP Tools Reference: people.googleapis.com

الأداة: search_directory_people

البحث عن مستخدمين ضمن دليل Google Workspace الخاص بمؤسستك تتوفّر هذه الميزة حصريًا لحسابات Google Workspace (التي تستخدمها الأنشطة التجارية والمؤسسات التعليمية والمؤسسات الأخرى)، ولا تتوفّر لحسابات Google الشخصية.

قواعد مهمة يجب اتّباعها:

  • إذا عرضت هذه الأداة نتائج متعددة، عليك عرض النتائج للمستخدم وطلب توضيح بشأن النتيجة التي يجب استخدامها قبل المتابعة.

  • يُحظر تمامًا نقل نتائج هذه الأداة إلى أداة أخرى (مثل إرسال رسالة إلكترونية أو إنشاء مسودة أو إنشاء حدث وما إلى ذلك) بدون تأكيد صريح من المستخدم.

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

  • إذا لم تعرض هذه الأداة أي نتائج، يمكنك استخدام أداة search_contacts كحلّ بديل.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة search_directory_people MCP.

طلب Curl 
curl --location 'https://people.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_directory_people",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

طلب رسالة SearchDirectoryPeople

SearchDirectoryPeopleMcpRequest

تمثيل JSON 
{
  "query": string,
  "pageSize": integer,
  "pageToken": string,
  "sources": [
    enum (DirectorySourceType)
  ]
}
الحقول
query

string

سلسلة طلب البحث المطلوب البحث عنها.
pageSize

integer

حجم الصفحة القيمة التلقائية هي 10، والحد الأقصى المسموح به هو 500.
pageToken

string

الرمز المميز للصفحة
sources[]

enum (DirectorySourceType)

مصادر الدليل المطلوب عرضها. يتم ضبط القيمة التلقائية على DOMAIN_PROFILE في حال عدم ضبطها.

DirectorySourceType

عمليات التعداد
DOMAIN_PROFILE الملف الشخصي لنطاق Google Workspace
DOMAIN_CONTACT جهة اتصال مشترَكة في نطاق Google Workspace

مخطط النتائج

رسالة الردّ على SearchDirectoryPeople

SearchDirectoryPeopleMcpResponse

تمثيل JSON 
{
  "results": [
    {
      object (SearchDirectoryResult)
    }
  ],
  "nextPageToken": string
}
الحقول
results[]

object (SearchDirectoryResult)

قائمة المستخدمين الذين تطابقوا مع طلب البحث
nextPageToken

string

رمز مميّز لاسترداد الصفحة التالية من النتائج.

SearchDirectoryResult

تمثيل JSON 
{
  "name": string,
  "email": string
}
الحقول
name

string

الاسم المعروض للشخص
email

string

عنوان البريد الإلكتروني الخاص بحساب المستخدم

التعليقات التوضيحية للأدوات

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

نطاقات التفويض

يجب توفير أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/directory.readonly