Bermigrasi dari layanan Kontak ke layanan lanjutan People API

Penting: Migrasikan skrip Anda dari layanan Kontak ke layanan lanjutan People API sebelum Apps Script menonaktifkan layanan Kontak pada 31 Januari 2025.

Apps Script tidak lagi menggunakan layanan Kontak pada 16 Desember 2022. 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 di layanan lanjutan People API, mempelajari apa yang dapat Anda gunakan sebagai gantinya, dan menemukan contoh kode untuk memigrasikan tugas umum. Untuk informasi selengkapnya, lihat Panduan Migrasi Contacts API.

Metode tanpa People API yang setara

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)

Berikut adalah daftar metode getContacts dari layanan Kontak yang menggunakan parameter label tambahan. Anda dapat menggunakan searchContacts dari layanan lanjutan People API untuk mendapatkan kontak berdasarkan kolom yang setara, tetapi Anda tidak dapat membatasi penelusuran ke label tertentu.

Metode dengan ekuivalen parsial
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:

• Menentukan sumber data–Saat menelusuri informasi tentang seseorang, Anda dapat menentukan tempat penelusuran, seperti kontak Google atau profil Google.
• Menelusuri orang berdasarkan string kueri–Anda bisa 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(name) 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(emailAddress) 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);
  }
}