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

חשוב: חשוב להעביר את הסקריפטים מהשירות של 'אנשי קשר' לשירות המתקדם שלPeople API, לפני ההוצאה משימוש של שירות 'אנשי קשר' במרץ 2023.

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

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

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

ברשימה הבאה מפורטות שיטות getContacts בשירות 'אנשי קשר' שאין להן דרכים מקבילות לחיפוש אנשי קשר בשירות המתקדם שלPeople API. בעזרת השירות המתקדם של Contact 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) בשירות 'אנשי קשר'.

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

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

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

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

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

מתקדמות/אנשים.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);
  }
}