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

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

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

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

שיטות עם אנלוגיות חלקיות
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

תכונות נוספות שזמינות ב-People API

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

• ציון מקור הנתונים – כשמחפשים מידע על אדם מסוים, אפשר לציין איפה לחפש, למשל אנשי קשר בחשבון 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() בשירות אנשי הקשר.

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

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