Migracja z usługi Kontakty do zaawansowanej usługi People API

16 grudnia 2022 r. usługa Kontakty została wycofana z Apps Script. Zamiast tego użyj zaawansowanego interfejsu People API. Interfejs People API korzysta z nowszego protokołu JSON i oferuje zaawansowane funkcje, takie jak scalanie kontaktów z profilami.

Z tego przewodnika dowiesz się, których metod usługi Kontakty nie ma odpowiedników w usłudze zaawansowanej People API, co możesz użyć zamiast nich i gdzie znajdziesz przykłady kodu do przenoszenia typowych zadań. Więcej informacji znajdziesz w Przewodniku po migracji interfejsu Contacts API.

Metody bez odpowiedników w People API

Poniższa lista zawiera metody getContacts w usłudze Kontakty, które nie mają odpowiednich sposobów wyszukiwania kontaktów w zaawansowanej usłudze People API. Dzięki zaawansowanemu interfejsowi People API możesz wyszukiwać kontakty według pól names, nickNames, emailAddresses, phoneNumbers i organizations pochodzących ze źródła CONTACT.

Metody bez odpowiedników
  • 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)

Poniższa lista zawiera metody getContacts z usługi Kontakty, które używają dodatkowego parametru label. Aby pobrać kontakty według odpowiedniego pola, możesz użyć metody searchContacts z usługi People API Advanced, ale nie możesz ograniczyć wyszukiwania do konkretnej etykiety.

Metody z częściowymi odpowiednikami
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Dodatkowe funkcje dostępne w People API

Po migracji do zaawansowanej usługi People API możesz uzyskać dostęp do tych funkcji People API, które nie są dostępne w usłudze Kontakty:

Przykłady kodu do typowych zadań

W tej sekcji znajdziesz listę typowych zadań związanych z usługą Kontakty. Przykłady kodu pokazują, jak tworzyć zadania za pomocą zaawansowanego interfejsu People API.

Pobieranie grupy kontaktów według nazwy

Poniższy przykładowy kod pokazuje, jak pobrać grupę kontaktów według jej nazwy, która jest odpowiednikiem getContactGroup(name) w usłudze Kontakty.

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

Wyszukiwanie kontaktów według adresu e-mail

Poniższy przykładowy kod pokazuje, jak pobrać kontakt po adresie e-mail, który jest odpowiednikiem funkcji getContact(emailAddress) w usłudze Kontakty.

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

Pobieranie wszystkich kontaktów

Poniższy przykładowy kod pokazuje, jak pobrać wszystkie kontakty użytkownika, co jest równoznaczne z użyciem funkcji getContacts() w usłudze Kontakty.

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

Pobieranie pełnego imienia i nazwiska osoby kontaktowej

Poniższy przykładowy kod pokazuje, jak uzyskać imię i nazwisko kontaktu, co jest równoznaczne z polem getFullName() w usłudze Kontakty.

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

Pobieranie wszystkich numerów telefonów kontaktu

Ten przykładowy kod pokazuje, jak uzyskać wszystkie numery telefonów kontaktu, co jest odpowiednikiem getPhones() w usłudze Kontakty.

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

Uzyskiwanie konkretnego numeru telefonu kontaktu

Poniższy przykładowy kod pokazuje, jak pobrać konkretny numer telefonu kontaktu, który jest odpowiednikiem getPhoneNumber() w usłudze Kontakty.

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