Vom Kontakte-Dienst zum erweiterten People API-Dienst migrieren

Wichtig: Migrieren Sie Ihre Skripts vom Kontakte-Dienst zum erweiterten Dienst der People API, bevor der Kontakte-Dienst von Apps Script im März 2023 eingestellt wird.

Der Kontaktedienst wurde am 16. Dezember 2022 in Apps Script eingestellt. Verwenden Sie stattdessen den erweiterten Dienst People API. 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, für welche Methoden des Kontakte-Dienstes im erweiterten Dienst der People API kein Äquivalent vorhanden ist. Außerdem erfahren Sie, was Sie stattdessen verwenden können, und finden Codebeispiele für die Migration häufiger Aufgaben. Weitere Informationen finden Sie in der Migrationsanleitung zur Contacts API.

Methoden ohne People API-Entsprechungen

Im Folgenden sind getContacts-Methoden im Kontaktedienst aufgeführt, die keine vergleichbaren Möglichkeiten für die Suche nach Kontakten im erweiterten Dienst der People API bieten. Mit dem erweiterten Dienst der People API können Sie nach den Feldern names, nickNames, emailAddresses, phoneNumbers und organizations eines Kontakts suchen, die aus der CONTACT-Quelle stammen.

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 getContacts-Methoden aus dem Kontaktedienst aufgeführt, die einen zusätzlichen label-Parameter verwenden. Sie können searchContacts aus dem erweiterten Dienst der People API verwenden, um Kontakte anhand des entsprechenden Felds abzurufen, aber Sie können die Suche 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

Wenn Sie zum erweiterten People API-Dienst migrieren, können Sie auf die folgenden People API-Funktionen zugreifen, die im Kontakte-Dienst nicht verfügbar sind:

  • Datenquelle angeben: Wenn Sie nach Informationen zu einer Person suchen, können Sie angeben, wo gesucht werden soll, z. B. nach einem Google-Kontakt oder einem Google-Profil.
  • Personen anhand eines Abfragestrings suchen: Sie können eine Liste der Profile und Kontakte abrufen, die mit einem bestimmten String übereinstimmen.
  • Batchanfragen: Sie können Ihre People API-Aufrufe in einem Batch zusammenfassen, um die Ausführungszeit des Skripts zu reduzieren.

Codebeispiele für häufige Aufgaben

In diesem Abschnitt werden häufige Aufgaben des Kontakte-Dienstes aufgeführt. Die Codebeispiele zeigen, wie die Aufgaben mit dem erweiterten Dienst der People API erstellt werden.

Kontaktgruppe anhand des Namens abrufen

Das folgende Codebeispiel zeigt, wie Sie eine Kontaktgruppe anhand ihres Namens abrufen. Dieser entspricht getContactGroup(name) im Kontaktedienst.

fortgeschritten/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 abrufen

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

fortgeschritten/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

Im folgenden Codebeispiel wird gezeigt, wie Sie alle Kontakte eines Nutzers abrufen. Dies entspricht getContacts() im Kontaktedienst.

fortgeschritten/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

Das folgende Codebeispiel zeigt, wie Sie den vollständigen Namen eines Kontakts abrufen, der getFullName() im Kontaktedienst entspricht.

fortgeschritten/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 einen Kontakt abrufen. Dies entspricht getPhones() im Kontaktedienst.

fortgeschritten/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 einen Kontakt abrufen. Dies entspricht getPhoneNumber() im Kontaktedienst.

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