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

중요: Apps Script에서 2023년 3월에 연락처 서비스를 종료하기 전에 주소록 서비스에서 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);
  }
}