מעבר משירות 'אנשי קשר' לשירות המתקדם שלPeople API

שירות אנשי הקשר הוצא משימוש ב-Google Apps Script ב-16 בדצמבר 2022, והשירות יושבת ב-31 בינואר 2025.

במקום זאת, כדאי להשתמש בשירות המתקדם של People API. ה-People API משתמש בפרוטוקול JSON חדש יותר ומספק תכונות מתקדמות, כמו מיזוג אנשי קשר עם פרופילים.

במדריך הזה מוסבר אילו methods של שירות אנשי הקשר לא מקבילות לשירות המתקדם People API, אילו methods אפשר להשתמש במקומן ומוצגות דוגמאות קוד להעברת משימות נפוצות. מידע נוסף זמין במדריך להעברת נתונים של Contacts API.

שיטות ללא מקבילות ב-People API

ברשימה הבאה מפורטות getContacts שיטות בשירות 'אנשי קשר' שאין להן דרכים מקבילות לחיפוש אנשי קשר בשירות המתקדם של People API. בעזרת השירות המתקדם People API, אפשר לחפש לפי השדות names, nickNames, emailAddresses, phoneNumbers ו-organizations של איש הקשר, שמגיעים מהמקור CONTACT.

שיטות ללא מקבילות

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)

בטבלה הבאה מפורטות getContacts שיטות משירות אנשי הקשר שמשתמשות בפרמטר נוסף label. למרות ששירות ה-People API המתקדם מאפשר לקבל אנשי קשר לפי השדה המקביל באמצעות searchContacts, אי אפשר להגביל את החיפוש לתווית ספציפית.

‫Methods עם מקבילות חלקיות
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

תכונות נוספות שזמינות עם People API

כשעוברים לשירות המתקדם People API, אפשר לגשת לתכונות הבאות של People API שלא זמינות בשירות Contacts:

• ציון מקור הנתונים – כשמחפשים מידע על אדם מסוים, אפשר לציין איפה לחפש, למשל באנשי קשר בחשבון Google או בפרופיל ב-Google.
• חיפוש אנשים לפי מחרוזת שאילתה – אפשר לקבל רשימה של פרופילים ואנשי קשר שתואמים למחרוזת ספציפית.
• בקשות מקובצות – אפשר לקבץ את הקריאות ל-People API כדי לקצר את זמן הביצוע של הסקריפט.

דוגמאות קוד למשימות נפוצות

בקטע הזה מפורטות משימות נפוצות משירות אנשי הקשר. בדוגמאות הקוד מוסבר איך ליצור את המשימות באמצעות השירות המתקדם של People API.

קבלת קבוצת אנשי קשר לפי שם

בדוגמת הקוד הבאה אפשר לראות איך מקבלים קבוצת אנשי קשר לפי השם שלה, שזה שווה ערך ל-getContactGroup בשירות Contacts.

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 בשירות 'אנשי קשר'.

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 בשירות Contacts.

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 בשירות Contacts.

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 בשירות Contacts.

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