Vom Kontakte-Dienst zum erweiterten People API-Dienst migrieren

Google Apps Script hat den Kontaktdienst am 16. Dezember 2022 eingestellt und wird ihn am 31. Januar 2025 abschalten.

Verwenden Sie stattdessen den erweiterten Dienst der People API. Die People API verwendet ein neueres JSON-Protokoll und bietet erweiterte Funktionen wie das Zusammenführen von Kontakten mit Profilen.

In dieser Anleitung erfahren Sie, welche Methoden des Kontaktdienstes keine Entsprechung im erweiterten Dienst der People API haben, was Sie stattdessen verwenden können und finden Codebeispiele für die Migration allgemeiner Aufgaben. Weitere Informationen finden Sie im Migrationsleitfaden für die Contacts API.

Methoden ohne Entsprechung in der People API

In der folgenden Liste sind die getContacts-Methoden im Kontaktdienst aufgeführt, für die es im erweiterten Dienst der People API keine entsprechenden Möglichkeiten zum Suchen nach Kontakten gibt. 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 Entsprechung

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)

In der folgenden Tabelle sind die getContacts-Methoden aus dem Kontaktdienst aufgeführt, die einen zusätzlichen label-Parameter verwenden. Mit dem erweiterten Dienst der People API können Sie zwar Kontakte über das entsprechende Feld mit searchContactsabrufen, die Suche aber nicht auf ein bestimmtes Label beschränken.

Methoden mit teilweiser Entsprechung
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

Zusätzliche Funktionen der People API

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

• Datenquelle angeben: Wenn Sie nach Informationen zu einer Person suchen, können Sie angeben, wo gesucht werden soll, z. B. in einem Google-Kontakt oder einem Google-Profil.
• Nach Personen über einen Abfragestring suchen: Sie können eine Liste von Profilen und Kontakten abrufen, die mit einem bestimmten Abfragestring übereinstimmen.
• Batchanfragen: Sie können Ihre People API-Aufrufe zusammenfassen , um die Ausführungszeit Ihres Skripts zu verkürzen.

Codebeispiele für allgemeine Aufgaben

In diesem Abschnitt werden allgemeine Aufgaben aus dem Kontaktdienst aufgeführt. Die Codebeispiele zeigen, wie Sie die Aufgaben mit dem erweiterten Dienst der People API erstellen.

Kontaktgruppe nach Name abrufen

Das folgende Codebeispiel zeigt, wie Sie eine Kontaktgruppe anhand ihres Namens abrufen. Dies entspricht getContactGroup im Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

/**
 * 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 nach E-Mail-Adresse abrufen

Das folgende Codebeispiel zeigt, wie Sie einen Kontakt anhand seiner E-Mail-Adresse abrufen. Dies entspricht getContact im Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

/**
 * 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 Sie alle Kontakte eines Nutzers abrufen. Dies entspricht getContacts im Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

/**
 * 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. Dies entspricht getFullName im Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

/**
 * 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 Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

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

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 Kontaktdienst.

advanced/people.gs

Auf GitHub ansehen

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