الترحيل من خدمة جهات الاتصال إلى خدمة "واجهة برمجة تطبيقات الأشخاص" المتقدمة

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

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

يمكنك استخدام هذا الدليل لمعرفة طرق خدمة جهات الاتصال التي ليس لها مكافئ في خدمة People 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 من خدمة "جهات الاتصال" التي تستخدم مَعلمة 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);
  }
}