Bermigrasi dari layanan Kontak ke layanan lanjutan People API

Google Apps Script menghentikan penggunaan layanan Kontak pada 16 Desember 2022 dan menghentikan layanan tersebut pada 31 Januari 2025.

Sebagai gantinya, gunakan layanan lanjutan People API. People API menggunakan protokol JSON yang lebih baru dan menyediakan fitur lanjutan, seperti menggabungkan kontak dengan profil.

Gunakan panduan ini untuk mempelajari metode layanan Kontak mana yang tidak memiliki padanan dalam layanan lanjutan People API, mempelajari apa yang dapat Anda gunakan sebagai gantinya, dan menemukan contoh kode untuk memigrasikan tugas umum. Untuk mengetahui informasi selengkapnya, lihat Panduan Migrasi Contacts API.

Metode tanpa padanan People API

Berikut adalah daftar metode getContacts di layanan Kontak yang tidak memiliki cara yang setara untuk menelusuri kontak di layanan lanjutan People API. Dengan layanan lanjutan People API, Anda dapat menelusuri berdasarkan kolom names, nickNames, emailAddresses, phoneNumbers, dan organizations kontak yang berasal dari sumber CONTACT.

Metode tanpa padanan

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)

Tabel berikut mencantumkan metode getContacts dari layanan Kontak yang menggunakan parameter label tambahan. Meskipun layanan lanjutan People API memungkinkan Anda mendapatkan kontak berdasarkan kolom yang setara menggunakan searchContacts, Anda tidak dapat membatasi penelusuran ke label tertentu.

Metode dengan padanan sebagian
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

Fitur tambahan yang tersedia dengan People API

Saat bermigrasi ke layanan lanjutan People API, Anda dapat mengakses fitur People API berikut yang tidak tersedia di layanan Kontak:

• Tentukan sumber data–Saat Anda menelusuri informasi tentang seseorang, Anda dapat menentukan tempat untuk menelusuri, seperti kontak Google atau profil Google.
• Menelusuri orang berdasarkan string kueri–Anda dapat mendapatkan daftar profil dan kontak yang cocok dengan string tertentu.
• Permintaan batch–Anda dapat mengelompokkan panggilan People API untuk membantu mengurangi waktu eksekusi skrip.

Contoh kode untuk tugas umum

Bagian ini mencantumkan tugas umum dari layanan Kontak. Contoh kode menunjukkan cara membuat tugas menggunakan layanan lanjutan People API.

Mendapatkan grup kontak berdasarkan nama

Contoh kode berikut menunjukkan cara mendapatkan grup kontak berdasarkan namanya, yang setara dengan getContactGroup di layanan Kontak.

advanced/people.gs

Lihat di 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,
    );
  }
}

Mendapatkan kontak berdasarkan alamat email

Contoh kode berikut menunjukkan cara mendapatkan kontak berdasarkan alamat emailnya, yang setara dengan getContact di layanan Kontak.

advanced/people.gs

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

Mendapatkan semua kontak

Contoh kode berikut menunjukkan cara mendapatkan semua kontak pengguna, yang setara dengan getContacts di layanan Kontak.

advanced/people.gs

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

Mendapatkan nama lengkap kontak

Contoh kode berikut menunjukkan cara mendapatkan nama lengkap kontak, yang setara dengan getFullName di layanan Kontak.

advanced/people.gs

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

Mendapatkan semua nomor telepon untuk kontak

Contoh kode berikut menunjukkan cara mendapatkan semua nomor telepon untuk kontak, yang setara dengan getPhones di layanan Kontak.

advanced/people.gs

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

Mendapatkan nomor telepon tertentu untuk kontak

Contoh kode berikut menunjukkan cara mendapatkan nomor telepon tertentu untuk kontak, yang setara dengan getPhoneNumber di layanan Kontak.

advanced/people.gs

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