نقل البيانات من خدمة جهات الاتصال إلى خدمة People API المتقدمة

ملاحظة مهمة: يمكنك نقل بيانات النصوص البرمجية من خدمة "جهات الاتصال" إلى واجهة People API. قبل أن توقف "برمجة التطبيقات" خدمة جهات الاتصال في آذار (مارس)، 2023.

أوقفت "برمجة تطبيقات Google" خدمة "جهات الاتصال" في 16 كانون الأول (ديسمبر) 2022. بدلاً من ذلك، استخدام الخدمة المتقدمة في واجهة برمجة تطبيقات الأشخاص. تستخدم واجهة برمجة تطبيقات "الأشخاص" بروتوكول JSON أحدث ويوفر الميزات المتقدمة، مثل دمج جهات الاتصال مع الملفات الشخصية.

يمكنك استخدام هذا الدليل للتعرّف على طرق خدمة جهات الاتصال التي ليس لها مكافئ في خدمة "واجهة برمجة تطبيقات الأشخاص" المتقدمة، والتعرّف على ما يمكنك استخدامه بدلاً من ذلك، والعثور على الرموز نماذج لنقل المهام الشائعة. لمزيد من المعلومات، راجع دليل نقل بيانات واجهة برمجة تطبيقات جهات الاتصال

الطرق بدون مكافئات People API

في ما يلي قائمة بالطرق getContacts المسموح بها في خدمة "جهات الاتصال" يمتلك طرق مماثلة للبحث عن جهات الاتصال في خدمة People API المتقدمة. مع خدمة People API المتقدمة، يمكنك البحث حسب names لجهة الاتصال. حقول nickNames وemailAddresses وphoneNumbers وorganizations من CONTACT المصدر.

طرق بدون مكافئات
  • getContactsByAddress(query)
  • getContactsByAddress(query, label)
  • getContactsByAddress(query, label)
  • getContactsByCustomField(query, label)
  • getContactsByDate(month, day, label)
  • getContactsByDate(month, day, year, label)
  • getContactsByDate(month, day, year, label)
  • getContactsByIM(query)
  • getContactsByIM(query, label)
  • getContactsByJobTitle(query)
  • getContactsByNotes(query)
  • getContactsByUrl(query)
  • getContactsByUrl(query, label)
  • getContactsByGroup(group)

في ما يلي طرق getContacts من خدمة "جهات الاتصال" التي تستخدم إضافية مَعلمة label. يمكنك استخدام searchContacts من خدمة People API المتقدمة للحصول على جهات الاتصال حسب الحقل المقابل. ولكن لا يمكنك قصر البحث على تصنيف معين.

الطرق ذات المكافئات الجزئية
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

الميزات الإضافية المتوفرة مع People API

عند نقل البيانات إلى خدمة People API المتقدمة، يمكنك الوصول إلى الميزات التالية في واجهة برمجة تطبيقات "الأشخاص" غير المتوفّرة في خدمة "جهات الاتصال":

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

عيّنات التعليمات البرمجية للمهام الشائعة

يسرد هذا القسم المهام الشائعة من خدمة "جهات الاتصال". الرمز نماذج توضح كيفية إنشاء المهام باستخدام واجهة برمجة تطبيقات "الأشخاص" المتقدمة خدمة ما.

الحصول على مجموعة جهات اتصال حسب الاسم

يوضح نموذج الرمز التالي كيفية الحصول على مجموعة جهات اتصال حسب اسمها، يعادل getContactGroup(name) في خدمة جهات الاتصال.

متقدِّم/people.gs
/**
 * Gets a contact group with the given name
 * @param {string} name The group name.
 * @see https://developers.google.com/people/api/rest/v1/contactGroups/list
 */
function getContactGroup(name) {
  try {
    const people = People.ContactGroups.list();
    // Finds the contact group for the person where the name matches.
    const group = people['contactGroups'].find((group) => group['name'] === name);
    // Prints the contact group
    console.log('Group: %s', JSON.stringify(group, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the contact group with an error %s', err.message);
  }
}

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

يعرض نموذج الرمز التالي كيفية التواصل مع جهة اتصال باستخدام عنوان البريد الإلكتروني: يعادل تطبيق "getContact(emailAddress)" في خدمة "جهات الاتصال".

متقدِّم/people.gs
/**
 * Gets a contact by the email address.
 * @param {string} email The email address.
 * @see https://developers.google.com/people/api/rest/v1/people.connections/list
 */
function getContactByEmail(email) {
  try {
    // Gets the person with that email address by iterating over all contacts.
    const people = People.People.Connections.list('people/me', {
      personFields: 'names,emailAddresses'
    });
    const contact = people['connections'].find((connection) => {
      return connection['emailAddresses'].some((emailAddress) => emailAddress['value'] === email);
    });
    // Prints the contact.
    console.log('Contact: %s', JSON.stringify(contact, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

الحصول على جميع جهات الاتصال

يوضح نموذج الرمز التالي كيفية الحصول على جميع جهات اتصال المستخدم، وهو الـ يعادل getContacts() في خدمة جهات الاتصال.

متقدِّم/people.gs
/**
 * Gets a list of people in the user's contacts.
 * @see https://developers.google.com/people/api/rest/v1/people.connections/list
 */
function getConnections() {
  try {
    // Get the list of connections/contacts of user's profile
    const people = People.People.Connections.list('people/me', {
      personFields: 'names,emailAddresses'
    });
    // Print the connections/contacts
    console.log('Connections: %s', JSON.stringify(people, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception here
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

الحصول على الاسم الكامل لجهة الاتصال

يوضح نموذج الرمز التالي كيفية الحصول على الاسم الكامل لجهة الاتصال، وهو يعادل getFullName() في خدمة جهات الاتصال.

متقدِّم/people.gs
/**
 * Gets the full name (given name and last name) of the contact as a string.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getFullName() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'names'});
    // Prints the full name (given name + family name)
    console.log(`${people['names'][0]['givenName']} ${people['names'][0]['familyName']}`);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

الحصول على جميع أرقام الهاتف لجهة اتصال

يوضح نموذج الرمز التالي كيفية الحصول على جميع أرقام الهواتف جهة اتصال، تعادل getPhones() في خدمة جهات الاتصال.

متقدِّم/people.gs
/**
 * Gets all the phone numbers for this contact.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getPhoneNumbers() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'phoneNumbers'});
    // Prints the phone numbers.
    console.log(people['phoneNumbers']);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

الحصول على رقم هاتف محدّد لجهة اتصال

يعرض نموذج الرمز التالي كيفية الحصول على رقم هاتف محدّد جهة اتصال، تعادل getPhoneNumber() في خدمة جهات الاتصال.

متقدِّم/people.gs
/**
 * Gets a phone number by type, such as work or home.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getPhone() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'phoneNumbers'});
    // Gets phone number by type, such as home or work.
    const phoneNumber = people['phoneNumbers'].find((phone) => phone['type'] === 'home')['value'];
    // Prints the phone numbers.
    console.log(phoneNumber);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}