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

חשוב: צריך להעביר את הסקריפטים משירות Contacts ל-People API לפני ששירות Contacts ייסגר ב-Apps Script ב-31 בינואר 2025.

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

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

‫Methods ללא מקבילות ב-People API

ברשימה הבאה מפורטות שיטות ב-Contacts service שאין להן דרכים מקבילות לחיפוש אנשי קשר בשירות המתקדם People API.getContacts בעזרת שירות מתקדם של 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 נוסף. אפשר להשתמש ב-searchContacts משירות People API advanced כדי לקבל אנשי קשר לפי השדה המקביל, אבל אי אפשר להגביל את החיפוש לתווית ספציפית.

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

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

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

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

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

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

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

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

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

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

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

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