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

أوقفت خدمة "جهات الاتصال" نهائيًا في برمجة تطبيقات Google في 16 ديسمبر 2022 وأغلقتها في 31 يناير 2025.

بدلاً من ذلك، استخدِم الخدمة المتقدّمة في 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. على الرغم من أنّ خدمة People API المتقدّمة تتيح لك الحصول على جهات الاتصال من خلال الحقل المكافئ باستخدام searchContacts، لا يمكنك حصر البحث على تصنيف معيّن.

الطُرق التي تتضمّن معادِلات جزئية
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

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

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

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

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

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

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

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

advanced/people.gs

عرض على GitHub

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

advanced/people.gs

عرض على GitHub

/**
 * 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

عرض على GitHub

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

advanced/people.gs

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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

عرض على GitHub

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