از سرویس مخاطبین به سرویس پیشرفته People API مهاجرت کنید

اسکریپت برنامه‌های گوگل (Google Apps Script) سرویس مخاطبین (Contacts) را در ۱۶ دسامبر ۲۰۲۲ منسوخ کرد و این سرویس را در ۳۱ ژانویه ۲۰۲۵ غیرفعال نمود.

در عوض، از سرویس پیشرفته People API استفاده کنید. People API از پروتکل JSON جدیدتری استفاده می‌کند و ویژگی‌های پیشرفته‌ای مانند ادغام مخاطبین با پروفایل‌ها را ارائه می‌دهد.

از این راهنما استفاده کنید تا یاد بگیرید کدام متدهای سرویس Contacts معادلی در سرویس پیشرفته People API ندارند، یاد بگیرید که به جای آنها از چه چیزی می‌توانید استفاده کنید و نمونه‌های کد برای انتقال وظایف رایج را بیابید. برای اطلاعات بیشتر، به راهنمای انتقال Contacts API مراجعه کنید.

روش‌هایی بدون معادل‌های API افراد

لیست‌های زیر متدهای getContacts در سرویس Contacts را نشان می‌دهند که روش‌های معادلی برای جستجوی مخاطبین در سرویس پیشرفته 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 از سرویس Contacts را که از یک پارامتر label اضافی استفاده می‌کنند، فهرست می‌کند. اگرچه سرویس پیشرفته People API به شما امکان می‌دهد مخاطبین را با استفاده از فیلد معادل searchContacts دریافت کنید، اما نمی‌توانید جستجو را به یک برچسب خاص محدود کنید.

روش‌هایی با معادل‌های جزئی
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

ویژگی‌های اضافی موجود با People API

وقتی به سرویس پیشرفته People API مهاجرت می‌کنید، می‌توانید به ویژگی‌های People API زیر که در سرویس مخاطبین در دسترس نیستند، دسترسی پیدا کنید:

• منبع داده را مشخص کنید - وقتی اطلاعاتی در مورد یک شخص جستجو می‌کنید، می‌توانید مشخص کنید که کجا جستجو شود، مانند یک مخاطب گوگل یا یک پروفایل گوگل.
• جستجوی افراد بر اساس رشته جستجو - می‌توانید فهرستی از پروفایل‌ها و مخاطبینی که با یک رشته خاص مطابقت دارند را دریافت کنید.
• درخواست‌های دسته‌ای - می‌توانید فراخوانی‌های API افراد خود را دسته‌ای کنید تا به کاهش زمان اجرای اسکریپت خود کمک کنید.

نمونه‌های کد برای کارهای رایج

این بخش وظایف رایج از سرویس مخاطبین را فهرست می‌کند. نمونه‌های کد نحوه ساخت وظایف با استفاده از سرویس پیشرفته People API را نشان می‌دهند.

دریافت گروه مخاطبین بر اساس نام

نمونه کد زیر نحوه دریافت یک گروه مخاطب را با استفاده از نام آن نشان می‌دهد، که معادل getContactGroup در سرویس Contacts است.

پیشرفته/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 در سرویس Contacts است.

پیشرفته/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 در سرویس Contacts است.

پیشرفته/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 در سرویس Contacts است.

پیشرفته/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 در سرویس Contacts است.

پیشرفته/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 در سرویس Contacts است.

پیشرفته/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);
  }
}