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

Lưu ý quan trọng: Hãy di chuyển các tập lệnh của bạn từ dịch vụ Danh bạ sang dịch vụ nâng cao API Người dùng trước khi Apps Script ngừng dịch vụ Danh bạ vào tháng 3 năm 2023.

Apps Script đã ngừng sử dụng dịch vụ Danh bạ kể từ ngày 16 tháng 12 năm 2022. Thay vào đó, hãy sử dụng dịch vụ nâng cao dành cho People API. API người dùng sử dụng giao thức JSON mới hơn và cung cấp các tính năng nâng cao, 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 xem những phương thức dịch vụ Danh bạ nào không có phương thức tương đương trong dịch vụ nâng cao API Người dùng, tìm hiểu xem bạn có thể sử dụng những gì 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 cho người dùng

Sau đây liệt kê các phương thức getContacts trong dịch vụ Danh bạ không có các cách tương đương để tìm người liên hệ trong dịch vụ nâng cao API Người dùng. Với dịch vụ nâng cao API Người dùng, bạn có thể tìm kiếm theo các trường names, nickNames, emailAddresses, phoneNumbers và organizations của một mục liên hệ từ 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)

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

Các phương thức có kết quả tương đương một phần
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

Các tính năng bổ sung có trong API Người dùng

Khi chuyển sang dịch vụ nâng cao của API Người dùng, bạn có thể sử dụng các tính năng sau đây của API Người dùng không có trong dịch vụ Danh bạ:

• Chỉ định nguồn dữ liệu–Khi tìm kiếm thông tin về một người, bạn có thể chỉ định nơi tìm kiếm, chẳng hạn như người liên hệ trên Google hoặc hồ sơ trên Google.
• Tìm kiếm người theo chuỗi truy vấn–Bạn có thể nhận danh sách hồ sơ và người liên hệ khớp với một chuỗi cụ thể.
• Yêu cầu hàng loạt – Bạn có thể gộp nhóm các lệnh gọi API Người dùng để giảm thời gian thực thi tập lệnh.

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ã mẫu cho thấy cách xây dựng nhiệm vụ bằng dịch vụ nâng cao API Người dùng.

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

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

nâng cao/mọi người.gs

Xem trên GitHub

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

Nhận thông tin liên hệ theo địa chỉ email

Mã mẫu sau đây cho biết cách nhận 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ạ.

nâng cao/mọi người.gs

Xem trên GitHub

/**
 * 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 toàn bộ địa chỉ liên hệ

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

nâng cao/mọi người.gs

Xem trên GitHub

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

Xem họ và tên của người liên hệ

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

nâng cao/mọi người.gs

Xem trên GitHub

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

Nhận 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ạ.

nâng cao/mọi người.gs

Xem trên GitHub

/**
 * 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ã mẫu sau đây cho biết cách lấy số điện thoại cụ thể của một người liên hệ, tương đương với getPhoneNumber() trong dịch vụ Danh bạ.

nâng cao/mọi người.gs

Xem trên GitHub

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