تحديد مستخدمي Google Chat وتحديدهم

توضّح هذه الصفحة كيف يمكن لتطبيقات Google Chat والمطوّرين تحديد مستخدمي Chat وتحديدهم.

لإجراء أي مما يلي، يجب أن يحدّد تطبيق أو مطوّر Chat مستخدمًا:

كيفية تحديد هوية المستخدمين في Chat

ينشئ Google Chat API User موردًا لكل مستخدم وتطبيق يستخدمان Chat. يتضمّن مرجع User الحقول التالية:

  • name: اسم المورد، بالتنسيق users/{user}، حيث يمثّل {user} معرّفًا فريدًا وثابتًا. يمكنك استخدام users/app كاسم مستعار لتطبيق الاتصال في Chat.
  • ‫displayName: الإخراج فقط الاسم المعروض للمستخدم
  • ‫avatarUrl: الإخراج فقط عنوان URL لصورة الأفاتار الخاصة بالمستخدم
  • ‫email: الإخراج فقط عنوان البريد الإلكتروني للمستخدِم.
  • domainId: معرّف فريد لنطاق Google Workspace الخاص بالمستخدم.
  • ‫type: تشير إلى نوع المستخدم. يشير هذا الحقل إلى ما إذا كان المستخدم تطبيق دردشة (BOT) أو شخصًا (HUMAN).
  • ‫isAnonymous: الإخراج فقط عندما تكون القيمة true، يشير ذلك إلى أنّ المستخدم محذوف أو أنّ ملفه الشخصي غير مرئي.

تفاصيل ملف المستخدم الشخصي وقواعد إذن الوصول

عند طلب البيانات من واجهتَي Messages وMemberships API باستخدام مصادقة المستخدم، تملأ واجهة Google Chat API المورد User بتفاصيل الملف الشخصي. تعبئ واجهة برمجة التطبيقات الحقول displayName وemail وavatarUrl لكل من المستخدمين الداخليين (في مؤسسة Google Workspace) والمستخدمين الخارجيين (في مؤسسات خارجية أو حسابات Google شخصية).

تشمل الأمثلة على الأماكن التي تملأ فيها واجهة برمجة التطبيقات ملفات المستخدمين ما يلي:

  • تمثّل هذه السمة sender الخاصة بـ Message.
  • المستخدمون ضمن الرسالة annotations، مثل المستخدم @mentions
  • تمثّل member Membership المورد.

قواعد الخصوصية وإمكانية الوصول

لحماية خصوصية المستخدم، تطبّق واجهة برمجة التطبيقات Google Chat API قواعد ظهور معيّنة عند تحديد ما إذا كان سيتم ملء تفاصيل الملف الشخصي للمستخدم:

  • الملف الشخصي الذي تمّت تعبئته: تملأ واجهة برمجة التطبيقات تفاصيل الملف الشخصي (تتوفّر displayName وemail وavatarUrl، وتكون قيمة isAnonymous هي false) إذا قبل المستخدم دعوة إلى مساحة (أي إذا كان عضوًا في المساحة) أو إذا كان لديه تقارب سابق (مثل سجلّ التفاعل مع الرسائل المباشرة) مع المستخدم الذي يجري المكالمة.
  • الملف الشخصي المجهول: إذا تمت الإشارة إلى مستخدم في مساحة بدون أن يكون عضوًا فيها وبدون أن يكون لديه تقارب سابق مع المستخدم الذي أجرى المكالمة، سيظل ملفه الشخصي مجهولاً. بالنسبة إلى المستخدم المجهول، تكون قيمة isAnonymous هي true، ويتم حذف التفاصيل، مثل displayName وemail وavatarUrl. ومع ذلك، بالنسبة إلى طلبات البيانات من واجهة برمجة التطبيقات التي يتم إجراؤها باستخدام مصادقة التطبيق، تتم دائمًا تعبئة الحقل displayName.

يعرض مثال JSON التالي مورد User يتضمّن تفاصيل الملف الشخصي التي تم ملؤها والتي تم عرضها في استجابة واجهة برمجة التطبيقات أو حدث التفاعل:

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

يعرض مثال JSON التالي مصدر User مجهول الهوية لا تظهر فيه تفاصيل الملف الشخصي للمستخدم للمتصل:

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

تحديد مستخدم في طلب إلى Google Chat API

لتحديد مستخدم، استخدِم القيم التالية لسمة {user}:

  • بالنسبة إلى المستخدمين في مؤسسة Google Workspace، استخدِم إحدى الطرق التالية:

    • name من User المرجع في Chat API، مثل users/123456789
    • {person_id} هو معرّف اسم Person مورد في People API، حيث تكون قيمة resourceName هي people/{person_id}، على سبيل المثال، يمثّل users/123456789 في Chat API الشخص نفسه الذي يمثّله people/123456789 في People API.
    • يمثّل المعرّف id لمورد User في Directory API، مثل users/123456789 في Chat API، الشخص نفسه الذي يمثّله users/123456789 في Directory API.
    • بالنسبة إلى طلبات واجهة برمجة التطبيقات التي يتم إجراؤها باستخدام مصادقة المستخدم، يتم استخدام عنوان البريد الإلكتروني للمستخدم كاسم مستعار، مثلاً، users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • بالنسبة إلى مستخدم في مؤسسة خارجية على Google Workspace أو مستخدم يستخدم حسابًا على Google، استخدِم أحد الخيارَين التاليَين:

    • عنوان بريد إلكتروني بديل، مثل users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com أو users/EMAIL_USERNAME@gmail.com
    • تمثّل هذه السمة name الأساسي لمورد User (مثل users/12345678901234567890) الذي تم الحصول عليه من طلب بيانات سابق من واجهة برمجة التطبيقات أو حدث تفاعلي.

تحديد مستخدم من خلال ردّ واجهة برمجة التطبيقات أو حدث تفاعلي

يمكنك تحديد المستخدمين الذين تمّت إعادتهم من طلبات البيانات من واجهة برمجة التطبيقات أو الأحداث الواردة بعدّة طرق:

بما أنّ Google Chat API يملأ الملفات الشخصية للمستخدمين الداخليين والخارجيين عند استخدام مصادقة المستخدم، لا يحتاج المطوّرون إلى طلب البيانات من Directory API لحلّ الأسماء أو عناوين البريد الإلكتروني للأعضاء ومرسلي الرسائل.