Vom Kontakte-Dienst zum erweiterten People API-Dienst migrieren

Wichtig: Migrieren Sie Ihre Skripts vom Kontakte-Dienst zur People API bevor Google Kontakte im März eingestellt wird. 2023

Apps Script hat den Kontakte-Dienst am 16. Dezember 2022 eingestellt. Stattdessen verwenden Sie die Erweiterter People API-Dienst: Die People API verwendet ein neueres JSON-Protokoll und bietet erweiterte Funktionen wie das Zusammenführen von Kontakten mit Profilen.

In diesem Leitfaden erfahren Sie, welche Kontakt-Dienstmethoden kein Äquivalent im Erweiterter People API-Dienst, Informationen dazu, was Sie stattdessen verwenden können, und Code finden Beispiele für die Migration gängiger Aufgaben. Weitere Informationen finden Sie in der Migrationsanleitung zur Contact API

Methoden ohne People API-Entsprechungen

Im Folgenden finden Sie eine Liste der getContacts-Methoden im Kontakte-Dienst, die keine haben Möglichkeiten zur Suche nach Kontakten im erweiterten Service der People API. Mit Mit dem erweiterten Dienst der People API können Sie anhand der names eines Kontakts, nickNames, emailAddresses, phoneNumbers und organizations, die stammen aus CONTACT Quelle.

Methoden ohne Äquivalente
  • 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)

Im Folgenden sind die getContacts-Methoden aus Google Kontakte aufgeführt, die eine Extra label-Parameter. Sie können searchContacts aus dem erweiterten Dienst der People API verwenden, um Kontakte nach dem entsprechenden Feld abzurufen: Sie können die Suche jedoch nicht auf ein bestimmtes Label beschränken.

Methoden mit partiellen Äquivalenten
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Zusätzliche Funktionen, die mit der People API verfügbar sind

Bei der Migration zum erweiterten People API-Dienst können Sie auf die die folgenden People API-Funktionen, die nicht im Kontakte-Dienst verfügbar sind:

  • Datenquelle angeben: Wenn Sie nach Informationen zu einer Person suchen, können Sie angeben, wo die Datenquelle gespeichert werden soll. etwa nach einem Google-Kontakt oder einem Google-Profil.
  • Personen anhand eines Abfragestrings suchen: Sie können eine Liste mit Profilen und Kontakten abrufen, die einem bestimmten String entsprechen.
  • Batchanfragen: Sie können Batchanfragen ausführen. Ihre People API-Aufrufe an, um die Ausführungszeit Ihres Skripts zu verkürzen.

Codebeispiele für häufige Aufgaben

In diesem Abschnitt werden häufige Aufgaben von Google Kontakte aufgeführt. Der Code Beispiele zeigen, wie die Aufgaben mit der erweiterten People API erstellt werden. Service.

Kontaktgruppe nach Namen abrufen

Das folgende Codebeispiel zeigt, wie Sie eine Kontaktgruppe nach ihrem Namen abrufen. entspricht getContactGroup(name) im Kontakte-Dienst.

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

Kontakt über E-Mail-Adresse anfordern

Das folgende Codebeispiel zeigt, wie Sie einen Kontakt über seine E-Mail-Adresse erhalten, Dies entspricht getContact(emailAddress) im Kontakte-Dienst.

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

Alle Kontakte abrufen

Das folgende Codebeispiel zeigt, wie alle Kontakte eines Nutzers abgerufen werden. die getContacts() im Kontakte-Dienst gleich.

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

Vollständigen Namen eines Kontakts abrufen

Im folgenden Codebeispiel wird gezeigt, wie Sie den vollständigen Namen eines Kontakts abrufen. Das ist der getFullName() im Kontakte-Dienst gleich.

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

Alle Telefonnummern für einen Kontakt abrufen

Das folgende Codebeispiel zeigt, wie Sie alle Telefonnummern für eine contact, was getPhones() im Kontakte-Dienst entspricht.

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

Eine bestimmte Telefonnummer für einen Kontakt abrufen

Das folgende Codebeispiel zeigt, wie Sie eine bestimmte Telefonnummer für eine contact, was getPhoneNumber() im Kontakte-Dienst entspricht.

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