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

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

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

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

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

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

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

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

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

نمونه کد زیر نحوه دریافت یک گروه مخاطب را با استفاده از نام آن نشان می‌دهد، که معادل getContactGroup(name) در سرویس 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(emailAddress) در سرویس 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);
  }
}