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

Google Apps Script đã ngừng cung cấp dịch vụ Danh bạ vào ngày 16 tháng 12 năm 2022 và ngừng hoạt động dịch vụ này vào ngày 31 tháng 1 năm 2025.

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 người liên hệ 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 của 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 thay thế 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ó phương thức tương đương trong API 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 của API People. 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 người liên hệ từ 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)

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

Các phương thứ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 bổ sung có sẵn với API People

Khi di chuyển sang dịch vụ nâng cao của API People, bạn có thể truy cập vào các tính năng sau của API People 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ể lấy 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ể yêu cầu hàng loạt các lệnh gọi API People để giúp 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 từ dịch vụ Danh bạ. Mã mẫu cho biết cách tạo các tác vụ bằng dịch vụ nâng cao của API People.

Lấy 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. Đây là phương thức tương đương với getContactGroup trong dịch vụ Danh bạ.

advanced/people.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,
    );
  }
}

Lấy người liên hệ theo địa chỉ email

Mã mẫu sau đây cho biết cách lấy một người liên hệ theo địa chỉ email. Đây là phương thức tương đương với getContact trong dịch vụ Danh bạ.

advanced/people.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 tất cả người liên hệ

Mã mẫu sau đây cho biết cách lấy tất cả người liên hệ của người dùng. Đây là phương thức tương đương với getContacts trong dịch vụ Danh bạ.

advanced/people.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);
  }
}

Lấy 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 người liên hệ. Đây là phương thức tương đương với getFullName trong dịch vụ Danh bạ.

advanced/people.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);
  }
}

Lấy tất cả số điện thoại của 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 người liên hệ. Đây là phương thức tương đương với getPhones trong dịch vụ Danh bạ.

advanced/people.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 một số điện thoại cụ thể của người liên hệ

Mã mẫu sau đây cho biết cách lấy một số điện thoại cụ thể của người liên hệ. Đây là phương thức tương đương với getPhoneNumber trong dịch vụ Danh bạ.

advanced/people.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);
  }
}