주소록 서비스에서 People API 고급 서비스로 이전

중요: 2025년 1월 31일에 Apps Script에서 주소록 서비스를 종료하기 전에 스크립트를 주소록 서비스에서 People API 고급 서비스로 이전하세요.

Apps Script는 2022년 12월 16일에 연락처 서비스를 지원 중단했습니다. 대신 People API 고급 서비스를 사용하세요. People API는 최신 JSON 프로토콜을 사용하며 프로필과 연락처를 병합하는 등의 고급 기능을 제공합니다.

이 가이드를 사용하여 People API 고급 서비스에 상응하는 항목이 없는 연락처 서비스 메서드를 알아보고, 대신 사용할 수 있는 항목을 알아보고, 일반적인 작업을 이전하기 위한 코드 샘플을 찾습니다. 자세한 내용은 Contacts API 이전 가이드를 참고하세요.

People API에 상응하는 메서드가 없는 메서드

다음은 People API 고급 서비스에서 주소록을 검색하는 등가 방법이 없는 주소록 서비스의 getContacts 메서드를 보여줍니다. People API 고급 서비스를 사용하면 CONTACT 소스의 연락처 names, nickNames, emailAddresses, phoneNumbers, organizations 필드로 검색할 수 있습니다.

상응하는 메서드가 없는 메서드

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)

다음은 추가 label 매개변수를 사용하는 연락처 서비스의 getContacts 메서드 목록입니다. People API 고급 서비스의 searchContacts를 사용하여 상응하는 필드로 연락처를 가져올 수 있지만 검색을 특정 라벨로 제한할 수는 없습니다.

부분 등가 항이 있는 메서드
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

People API에서 사용할 수 있는 추가 기능

People API 고급 서비스로 이전하면 연락처 서비스에서 사용할 수 없는 다음 People API 기능에 액세스할 수 있습니다.

• 데이터 소스 지정: 사용자에 대한 정보를 검색할 때 Google 연락처 또는 Google 프로필과 같은 검색 위치를 지정할 수 있습니다.
• 검색 문자열로 사용자 검색: 특정 문자열과 일치하는 프로필 및 연락처 목록을 가져올 수 있습니다.
• 일괄 요청: People API 호출을 일괄 처리하여 스크립트 실행 시간을 줄일 수 있습니다.

일반적인 작업을 위한 코드 샘플

이 섹션에는 연락처 서비스의 일반적인 작업이 나와 있습니다. 코드 샘플은 People API 고급 서비스를 사용하여 태스크를 구성하는 방법을 보여줍니다.

이름으로 연락처 그룹 가져오기

다음 코드 샘플은 이름으로 연락처 그룹을 가져오는 방법을 보여줍니다. 이는 연락처 서비스에서 getContactGroup(name)에 상응합니다.

advanced/people.gs

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

이메일 주소로 연락처 가져오기

다음 코드 샘플은 이메일 주소로 연락처를 가져오는 방법을 보여줍니다. 이메일 주소는 연락처 서비스의 getContact(emailAddress)에 상응합니다.

advanced/people.gs

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

모든 연락처 가져오기

다음 코드 샘플은 사용자의 모든 연락처를 가져오는 방법을 보여줍니다. 이는 연락처 서비스의 getContacts()와 같습니다.

advanced/people.gs

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

연락처의 전체 이름 가져오기

다음 코드 샘플은 연락처의 전체 이름을 가져오는 방법을 보여줍니다. 이는 연락처 서비스의 getFullName()와 같습니다.

advanced/people.gs

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

연락처의 모든 전화번호 가져오기

다음 코드 샘플은 연락처의 모든 전화번호를 가져오는 방법을 보여줍니다. 이는 연락처 서비스의 getPhones()와 같습니다.

advanced/people.gs

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

연락처의 특정 전화번호 가져오기

다음 코드 샘플은 연락처의 특정 전화번호를 가져오는 방법을 보여줍니다. 이는 연락처 서비스의 getPhoneNumber()와 같습니다.

advanced/people.gs

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