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

مهم : قبل از اینکه Apps Script سرویس مخاطبین را در مارس 2023 خاموش کند، اسکریپت‌های خود را از سرویس Contacts به سرویس پیشرفته People API منتقل کنید.

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

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

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

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

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

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

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) در سرویس Contacts است.

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() در سرویس Contacts است.

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() در سرویس Contacts است.

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() در سرویس Contacts است.

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() در سرویس Contacts است.

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