Chuyển từ dịch vụ Danh bạ sang dịch vụ nâng cao API People

Apps Script đã ngừng cung cấp dịch vụ Danh bạ từ ngày 16 tháng 12 năm 2022. Thay vào đó, hãy sử dụng dịch vụ nâng cao People API. People API sử dụng một giao thức JSON mới hơn và cung cấp các tính năng nâng cao, chẳng hạn như hợp nhất danh bạ với hồ sơ.

Hãy tham khảo hướng dẫn này để tìm hiểu những phương thức của dịch vụ Danh bạ không có phương thức tương đương trong dịch vụ nâng cao People API, tìm hiểu những phương thức bạn có thể sử dụng thay thế và tìm các mẫu mã để di chuyển các tác vụ phổ biến. Để biết thêm thông tin, hãy tham khảo Hướng dẫn di chuyển Contacts API.

Các phương thức không có phương thức tương đương trong People API

Sau đây là danh sách các phương thức getContacts trong dịch vụ Danh bạ không có cách tương đương để tìm kiếm người liên hệ trong dịch vụ nâng cao của People API. Với dịch vụ nâng cao People API, bạn có thể tìm kiếm theo các trường names, nickNames, emailAddresses, phoneNumbers và organizations của một người liên hệ. Các trường này có trong nguồn CONTACT.

Các phương thức không có phương thức tương đương
  • 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)

Sau đây là danh sách các phương thức getContacts từ dịch vụ Danh bạ sử dụng một tham số bổ sung label. Bạn có thể sử dụng searchContacts từ dịch vụ nâng cao People API để lấy danh bạ theo trường tương đương, nhưng bạn không thể giới hạn phạm vi tìm kiếm trong một nhãn cụ thể.

Phương thức có các phương thức tương đương một phần
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Các tính năng khác có trong People API

Khi di chuyển sang dịch vụ nâng cao People API, bạn có thể truy cập vào các tính năng sau của People API không có trong dịch vụ Danh bạ:

Mã mẫu cho các tác vụ phổ biến

Phần này liệt kê các tác vụ thường gặp trong dịch vụ Danh bạ. Các mẫu mã cho biết cách tạo các tác vụ bằng dịch vụ nâng cao People API.

Lấy một nhóm người liên hệ theo tên

Mẫu mã sau đây cho biết cách lấy một nhóm người liên hệ theo tên. Đây là tên tương đương với getContactGroup(name) trong dịch vụ Danh bạ.

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

Lấy thông tin liên hệ theo địa chỉ email

Mẫu mã sau đây cho thấy cách lấy một người liên hệ theo địa chỉ email của họ, tương đương với getContact(emailAddress) trong dịch vụ Danh bạ.

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

Lấy tất cả người liên hệ

Mã mẫu sau đây cho biết cách lấy tất cả danh bạ của người dùng, tương đương với getContacts() trong dịch vụ Danh bạ.

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

Lấy họ và tên của một người liên hệ

Mẫu mã sau đây cho biết cách lấy tên đầy đủ của một người liên hệ, tương đương với getFullName() trong dịch vụ Danh bạ.

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

Lấy tất cả số điện thoại của một người liên hệ

Đoạn mã mẫu sau đây cho thấy cách lấy tất cả số điện thoại của một người liên hệ, tương đương với getPhones() trong Dịch vụ danh bạ.

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

Lấy một số điện thoại cụ thể của người liên hệ

Mẫu mã sau đây cho thấy cách lấy một số điện thoại cụ thể cho một người liên hệ, tương đương với getPhoneNumber() trong dịch vụ Danh bạ.

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