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

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

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

الطرق التي لا تتضمّن مكافئات 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 من خدمة "جهات الاتصال" التي تستخدِم مَعلمة extra label. يمكنك استخدام searchContacts من الخدمة المتقدّمة People API للحصول على جهات الاتصال حسب الحقل المكافئ، ولكن لا يمكنك حصر البحث في تصنيف معيّن.

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

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

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

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

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

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

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

advanced/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) في خدمة "جهات الاتصال".

advanced/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() في خدمة "جهات الاتصال".

advanced/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() في خدمة "جهات الاتصال".

advanced/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() في خدمة "جهات الاتصال".

advanced/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() في خدمة "جهات الاتصال".

advanced/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);
  }
}