مقدمة
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك واجهة برمجة تطبيقات "الأشخاص" ما يلي:
- قراءة وإدارة جهات اتصال المستخدم الذي تمت المصادقة عليه
- قراءة ونسخ "جهات الاتصال الأخرى" للمستخدم الذي تمت المصادقة عليه
- الاطّلاع على معلومات الملف الشخصي للمستخدمين الذين تمت مصادقتهم وجهات اتصالهم
- قراءة جهات الاتصال والملفات الشخصية في النطاق
على سبيل المثال، افترض أن المستخدم الذي تمت المصادقة عليه، جين، لديه فابيان ورانجيث في جهات اتصالها الخاصة. عندما يطلب تطبيقك الرمز people.connections.list لقراءة قائمة الاتصال الخاصة بها، تظهر لجين على شاشة طلب الموافقة تطلب منها منح التطبيق إذن الوصول إلى القائمة. إذا وافقت "جين" على الطلب، يقرأ التطبيق قائمة تتضمّن person resources لكل من "فابيان" و"رانجيث".
إذا كان التطبيق بحاجة إلى معلومات عن شخص معيّن، يمكنه حينئذٍ الاتصال بـ
people.get، مع إدخال اسم المورد، للحصول على
person resource لهذا الشخص.
يمكن للتطبيق أيضًا إدارة جهات الاتصال من خلال إنشاء جهات اتصال جديدة باستخدام people.createContact وتعديل جهات الاتصال الحالية التي قرأ منها people.connections.list باستخدام people.updateContact وحذف جهات الاتصال باستخدام people.deleteContact.
يمكن لمستخدمي Google Workspace أيضًا إدراج الملفات الشخصية في نطاق الدليل وجهات اتصال النطاق
باستخدام
people.listDirectoryPeople أو البحث
عنها باستخدام
people.searchDirectoryPeople.
يتم دمج معلومات الأشخاص التي تقرأها واجهة برمجة التطبيقات لتطبيق People API من مصادر مختلفة، استنادًا إلى الشروط التالية:
فهم بيانات الشخص المدمج
يتم استخلاص البيانات المتعلقة بأحد الأشخاص من نوع مصدر رئيسي واحد. يتم دمج البيانات من مصادر أخرى مع هذه البيانات إذا كانت المصادر مرتبطة من خلال عناوين بريد إلكتروني تم التحقق منها أو أرقام هواتف أو عناوين URL للملفات الشخصية. وهذه هي الطرق التي يمكن أن ينشئ بها الشخص:
يمكن تعديل الأشخاص المستندين إلى جهة الاتصال فقط من خلال نقاط نهاية التحويل. لا يتم توفير عمليات تغيير جهات اتصال
الملف الشخصي والنطاق.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe People API allows reading and managing the authenticated user's contacts, including private contacts and "Other contacts".\u003c/p\u003e\n"],["\u003cp\u003eUsers can access profile information for authenticated users and their contacts, including public Google profile data and, when permitted, Google Workspace domain profile data.\u003c/p\u003e\n"],["\u003cp\u003eThe API facilitates managing contacts by creating, updating, and deleting contacts through specific endpoints.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Workspace users can utilize the API to list and search domain profiles and domain contacts.\u003c/p\u003e\n"],["\u003cp\u003eThe People API merges data from various sources like public profiles, private profiles, contacts, and domain information based on verified email addresses, phone numbers, or profile URLs.\u003c/p\u003e\n"]]],["The People API enables reading and managing authenticated user contacts, \"Other contacts,\" and profile information, including domain profiles. Apps can list connections via `people.connections.list`, retrieve specific person data using `people.get`, create contacts with `people.createContact`, update contacts with `people.updateContact`, and delete contacts via `people.deleteContact`. Google Workspace users can access domain contacts using `people.listDirectoryPeople` or `people.searchDirectoryPeople`. The data is merged from sources like public profiles, domain data, and private information, depending on user consent and scopes granted.\n"],null,["The People API lets you:\n\n- Read and manage the authenticated user's [Contacts](https://contacts.google.com)\n- Read and copy the authenticated user's [\"Other contacts\"](https://contacts.google.com/other)\n- Read profile information for authenticated users and their contacts\n- Read domain profiles and contacts\n\nFor example, suppose that the authenticated user, Jen, has Fabian and Ranjith in\nher private contacts. When your app calls\n[`people.connections.list`](/people/api/rest/v1/people.connections/list) to read a\nlist of her connections, Jen is presented with a consent screen asking to give\nthe app access to the list. If Jen consents, the app reads a list containing\n[`person resources`](/people/api/rest/v1/people) for Fabian and Ranjith.\n\nIf the app needs information for a specific person, it can then call\n[`people.get`](/people/api/rest/v1/people/get), passing in a resource name, to get\nthe [`person resource`](/people/api/rest/v1/people) for that person.\n\nThe app can also manage contacts by creating new contacts using\n[`people.createContact`](/people/api/rest/v1/people/createContact), update existing\ncontacts it has read from\n[`people.connections.list`](/people/api/rest/v1/people.connections/list) using\n[`people.updateContact`](/people/api/rest/v1/people/updateContact), and delete contacts\nusing [`people.deleteContact`](/people/api/rest/v1/people/deleteContact).\n\nGoogle Workspace users can also list their directory domain profiles and domain\ncontacts using\n[`people.listDirectoryPeople`](/people/api/rest/v1/people/listDirectoryPeople) or search\nthem using\n[`people.searchDirectoryPeople`](/people/api/rest/v1/people/searchDirectoryPeople).\n\nA merged view of people information\n\nThe people information that the People API reads is merged from various\nsources, depending on the following conditions:\n\n| Source | Condition |\n|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Public Google profile data | Always. |\n| Google Workspace domain profile data | The domain admin has [enabled external contact and profile sharing](https://support.google.com/a/answer/6343701) of domain-scoped data and the [`directory.readonly` scope](/people/v1/how-tos/authorizing#directory) has been granted |\n| The authenticated user's private profile information | One of the [`profile` scopes](/people/v1/how-tos/authorizing#OAuth2Authorizing) has been granted. |\n| The authenticated user's contacts | The [`contacts` scope](/people/v1/how-tos/authorizing#contacts) has been granted. |\n\nUnderstanding Merged Person Data\n\nThe data for a person is derived from one main source type. Data from other\nsources is merged with this data if the sources are connected through verified\nemail addresses, phone numbers, or profile URLs. These are the ways a person may\nbe composed:\n\n| Main Source | Contacts | Profiles | Google Workspace Domain Profiles | Google Workspace Domain Contacts | Usage |\n|----------------|----------|----------|----------------------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Contact | 1 | 0+ | 0+ | 0+ | Returned for most endpoints |\n| Profile | 0+ | 1 | 0 or 1 | 0 | Returned in [`people.get`](/people/api/rest/v1/people/get) when it is used to get the person [for the signed-in user](/people/v1/profiles#get_the_person_for_the_authenticated_user) or get a person for [another user's Google Account](/people/v1/read-people#get_the_person_for_a_google_account_id). |\n| Domain Contact | 0+ | 0 | 0 | 1 | Returned in [`people.listDirectoryPeople`](/people/api/rest/v1/people/listDirectoryPeople) or [`people.searchDirectoryPeople`](/people/api/rest/v1/people/searchDirectoryPeople). |\n\nOnly contact based people can be modified by mutation endpoints. Profile and\ndomain contact mutations are not supported."]]
