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

Apps Script ngừng sử dụng 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 của API People. API People 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 sử dụng hướng dẫn này để tìm hiểu những phương thức dịch vụ Danh bạ không có phương thức tương đương trong dịch vụ nâng cao của API People, tìm hiểu những phương thức bạn có thể sử dụng và tìm mã mẫu để 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 API Danh bạ.

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

Danh sách sau đây liệt kê 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 People API. Với dịch vụ nâng cao của API People, 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ệ trong nguồn CONTACT.

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)

Danh sách sau đây liệt kê các phương thức getContacts của dịch vụ Danh bạ sử dụng một tham số label bổ sung. Bạn có thể sử dụng searchContacts từ dịch vụ nâng cao của API People để lấy thông tin liên hệ theo trường tương đương, nhưng bạn không thể giới hạn nội dung tìm kiếm ở một nhãn cụ thể.

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

Các tính năng bổ sung có trong API People

Khi di chuyển sang dịch vụ nâng cao của API People, bạn có thể sử dụng các tính năng sau của API People 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ụ phổ biến trong dịch vụ Danh bạ. Các mẫu mã cho biết cách tạo tác vụ bằng dịch vụ nâng cao của API People.

Tìm nhóm người liên hệ theo tên

Mã mẫu sau đây cho biết cách lấy một nhóm người liên hệ theo tên của nhóm đó, 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);
  }
}

Tìm người liên hệ theo địa chỉ email

Mẫu mã sau đây cho thấy cách lấy thông tin 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ọ tên đầy đủ của người liên hệ

Mã mẫu 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ệ

Mã mẫu sau đây cho biết 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 số điện thoại cụ thể của một 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);
  }
}