סקירה כללית על השילוב

מודעות לשירותים מקומיים (LSA) כדי לשתף פעולה עם אתרי צבירה ולהציג את כרטיסי המוצר שלהם (או של ספקי השירותים) ב-Google.com. במדריך הזה מתואר איך אתרי צבירה יכולים לספק נתונים מובנים של מודעות לשירותים מקומיים לגבי ספקי השירותים שלהם. במסמכים שלנו מפורטות נקודות הקצה של ה-API שצריך להטמיע כדי לשלב את המערכת עם LSA.

מילון מונחים

אגרגטור (או שותף): אלה שותפים שמצבירים ספקים שהם מספקים להם שירותים, והנתונים שלהם עשויים להישלח אל LSA.

ספק (או כרטיס מוצר) של צד שלישי: אלה הם עסקים קטנים פרטיים (למשל, שרברב) שיכול להיות שיש לו קשר עסקי עם אתרי צבירה. אתרי אגרגטור מספקים ל-Local Services מידע על העסקים האלה.

סקירה כללית

מצטברים יספקו נתונים על הספקים שלהם (עסקים) ל-Local Services באמצעות פידים. כל פיד מורכב מנתונים על כמה ספקים. בתוך פיד, נתונים על ספק יחיד מוצגים בפריט פיד. בכל פיד מצוינת גם חותמת זמן של הפיד, שמציינת את עדכניות הפיד. בכל פיד מצוין גם סוג הפיד: יכול להיות שזה מידע על פרופיל הספק או על ביקורות על הספק, כמו שמתואר בהמשך.

סוגי פידים

באינטגרציה הראשונית, כל פיד יכול להיות אחד מסוגי הפידים הבאים:

• פידים של פרופילים: הפיד הזה מספק מידע על פרופילים של ספקים. כל פריט פיד כולל מידע על פרופיל של ספק מסוים. הפרטים האלה כוללים מזהה עסק ייחודי, שם העסק, מיקומי ההצגה, השירותים המוצעים, שעות הפתיחה וכו'. בנוסף, הפריט בפיד מכיל מטא-נתונים של הצגת המודעות עבור העסק הזה (למשל, סכום התקציב החודשי, סטטוס המודעה וכו').

• פידים של ביקורות: הפיד הזה מספק מידע על ביקורות של ספקים. כל פריט פיד מכיל רשימה של ביקורות מפורטות של צרכנים על ספק מסוים. כל ביקורת של צרכן כוללת את שם הצרכן, דירוג (1 עד 5), טקסט הביקורת, חותמת הזמן של הביקורת וכו'.

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

הטמעת פידים

נתוני הפיד עוברים סריאליזציה כ-JSON. כדי לשלוח נתונים, LSA תתמוך רק במנגנון משיכה. בעתיד אנחנו מתכננים לתמוך במנגנון של שליחת נתונים.

מנגנון משיכה

במנגנון השליפה, צוברים תומכים בקבוצה של נקודות קצה מוגדרות מראש של REST ‏(URL) ששולחות ומקבלות אובייקטים של JSON. זה דומה לאירוח של קובץ אחד או יותר בשרת אינטרנט. ‫LSA ישלח מעת לעת בקשות HTTP GET לכתובות ה-URL האלה כדי לאחזר נתונים. פרטים על כתובות ה-URL המוגדרות מראש מופיעים בקטע הבא בנושא נקודות קצה של API.

מנגנון Push

במנגנון הדחיפה, LSA מספקת נקודת קצה למצביעים כדי להתקשר ולספק נתונים. מבחינה סמנטית, זהה לפעולת משיכה, אבל מאפשר גמישות במקרים שבהם צוברים רוצים לדחוף נתונים ספציפיים אל 'Google בעלי מקצוע'. כל הסמנטיקה, הכללים או האילוצים שמתוארים בפרוטוקול חלים על פעולות push ו-pull באותו אופן.

נקודות קצה ל-API

אתרי אגרגטור צריכים לתמוך בנקודות הקצה הבאות: אחת לביקורות על הפרופיל ואחת לביקורות על המוצרים.

נתיב מומלץ לנקודות קצה

מומלץ שנקודות הקצה יכללו פרטי גרסה כמו בדוגמה שלמטה. אנחנו מתחילים עם v1.

נקודת קצה	נתיב
פיד הפרופיל	/feeds/{version}/profile
פיד ביקורות	/feeds/{version}/review

פרמטר של נקודת קצה

פרמטרים	תיאור
maxresults	זוהי המגבלה למספר הפריטים בפיד שאפשר לבקש בדף.
nextpagetoken	אסימון עימוד לקבלת דף התוצאות הבא

אימות של נקודות קצה

האימות מתבצע באמצעות אימות גישה בסיסי של HTTP: שם משתמש וסיסמה בקידוד Base64 לאימות. הנה דוגמה.

• username 'הרשאה' (למטרות המחשה)
• ‫password J9adfdsafc3RfMjpVU1yif5XMw” (למטרות המחשה)

חשבון SFTP להעלאה

נתיב Dropbox: partnerupload.google.com:19321

אזהרה: קבצים שנטענים לתיבת הדואר הנכנס של SFTP נמחקים אוטומטית אחרי 24 שעות.

אימות של נקודות קצה

• זוג מפתחות ציבורי/פרטי (מומלץ)

  • אפשר להשתמש במדריך הזה כדי ליצור צמדי מפתחות.
  • שולחים ל-LSA את המפתח הציבורי ושומרים את המפתח הפרטי לאימות
  • מערכת LSA תשתמש במפתח הציבורי כדי ליצור שם משתמש ותשלח אותו בחזרה אל המצטבר.

• אימות באמצעות סיסמה

  • ‫LSA ייצור את שם המשתמש והסיסמה וישלח אותם בחזרה למצטבר

הפניה מהירה לפקודות SFTP

1. מתחברים לחשבון. משתמשים בפקודה הזו כדי להתחבר. (אל תכללו את ‎-i אם אתם לא משתמשים במפתח פרטי).

   sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

2. העתקת קובץ מעתיקים את הקובץ למערכת המרוחקת. אפשר להשתמש ב-lls/lcd כדי ls/cd למערכת המקומית ולמצוא את הקובץ. אחר כך מעתיקים את הקובץ באמצעות:

   put <path_to_local_file>

3. אימות. משתמשים בפקודה ls כדי לראות רשימה של תיקיות וקבצים בספריית SFTP ולוודא שהקובץ הועתק למערכת המרוחקת

קטגוריות פיד

כמו שצוין קודם, כל פיד מקביל לקובץ ומורכב מכמה פריטי פיד. כל פריט בפיד מכיל נתונים על ספק מסוים (מזהה עסק ייחודי). לכל פיד יש גם חותמת זמן שמציינת את עדכניות הפיד. קטגוריית הפיד מציינת איך LSA מפרש פיד נתון. יש שני סוגים של פידים, כפי שמתואר בהמשך.

פיד תמונת המצב מכיל רשימה מלאה של ספקים (במסגרת אגרגטור) בחותמת זמן מסוימת. אחרי עיבוד פיד התמונות הזה, חלים כללי הסמנטיקה הבאים:

• לכל ספק שמופיע בפיד, המערכת תעדכן את הנתונים של הספק הזה במסד הנתונים של מודעות לקידום עסקים מקומיים (למשל, תיצור ספק חדש אם זה הספק הראשון שנתקלה בו, או תעדכן את נתוני הספק אם הספק עבר עיבוד בפיד קודם).

• אם ספק מסוים שמופיע כרגע במסד הנתונים של LSA, אבל לא מופיע בפיד, הוא יימחק.

פיד עדכון (או פיד מצטבר) מכיל רשימה חלקית של ספקים (במסגרת צד שלישי) בחותמת זמן מסוימת. אחרי עיבוד פיד מצטבר, יחולו הסמנטיקה הבאה:

• לכל ספק שמופיע בפיד, המערכת תעדכן את הנתונים של הספק הזה במסד הנתונים של מודעות לקידום עסקים מקומיים אם הספק נוצר בפיד של תמונת מצב קודמת. (לדוגמה, אם נתקלים בספק בפעם הראשונה, לא תתבצע פעולה)

• אם ספק מסוים מופיע כרגע במסד הנתונים של מודעות לשירותים מקומיים, אבל לא מופיע בפיד, לא יקרה כלום (כלומר, לא יבוצע שינוי בספק הזה).

יש הבדלים קלים בין המשמעות של פרופיל לבין המשמעות של פיד ביקורות. לפרטים על העיבוד, אפשר לעיין בסמנטיקה של פידים ספציפיים.

פידים של פרופילים: * פידים של תמונות מצב מבוססות-משיכה * פידים של תמונות מצב מבוססות-דחיפה * פידים של עדכונים מבוססי-דחיפה פידים של ביקורות: * פידים של תמונות מצב מבוססות-משיכה * פידים של תמונות מצב מבוססות-דחיפה

חובה להשתמש בפידים נפרדים של פרופילים במקרים הבאים:

1. ספקים שעומדים בדרישות לקבלת התג אומת על ידי Google או נבדק על ידי Google.

2. ספקים שלא עומדים בדרישות לקבלת התג.

דוגמאות

פידים של תמונות מצב

כדאי לזכור שפיד תמונת מצב יכלול רשימה מלאה של ספקים. לדוגמה, אם אגרגטור רוצה להוסיף 100 ספקים ל-LSA, פיד תמונת המצב צריך להכיל את המצב העדכני של כל 100 הספקים.

איך זה עובד

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

• תמונת מצב 1 כוללת Pro 1, ‏ Pro 2
• תמונת מצב 2 כוללת Pro 1, ‏ Pro 3

אחרי העיבוד של תמונת המצב 1, מסד הנתונים של LSA יכלול את Pro 1 ואת Pro 2. במהלך העיבוד של צילום המסך 2, LSA יעודכן ב-Pro 1, ייצור את Pro 3 וימחק את Pro 2. כלומר, אחרי העיבוד של תמונת המצב 2, מסד הנתונים של LSA יכלול את Pro 1 ואת Pro 3.

עדכון פידים (מצטבר)

כדאי לזכור שפיד עדכונים מכיל רשימה חלקית של ספקים שמשתמשים באגרגטור. לדוגמה, אם צובר רוצה לעדכן רק 5 מתוך 100 הספקים שהוא סיפק בעבר, פיד העדכון צריך להכיל רק את המצב העדכני של 5 הספקים האלה.

איך זה עובד

הדוגמה הפשוטה הבאה ממחישה איך פועלת קטגוריית העדכונים 'פידים של פרופילים'.

• עדכון 1: Pro 1, ‏ Pro 2
• עדכון 2: Pro 1, ‏ Pro 3

אחרי העיבוד של עדכון 1, מסד הנתונים של LSA יכלול את Pro 1 ואת Pro 2. במהלך העיבוד של עדכון 2, ‏ LSA יעודכן לגרסה Pro 1, וייצור את גרסה Pro 3. שימו לב ש-Pro 2 לא משתנה. כלומר, אחרי העיבוד של עדכון 2, מסד הנתונים של LSA יכלול את Pro1, ‏ Pro2 ו-Pro 3.

ההשלכות של Snapshot ו-Pull

מנגנון הפידים של תמונת המצב + משיכה מרמז על ההגבלות הבאות:

• יכול להיות שיעברו כמה שעות עד ששותפים יוכלו להוסיף או למחוק ספקי תוכן, לעדכן את פרטי הפרופיל, להשהות מודעות או לשנות תקציבים. העיכוב קשור ישירות לתדירות של בקשות המשיכה.
• אם יש צורך בעדכוני נתונים דחופים, יכול להיות שנצטרך לתמוך באופן ידני בשליפה חד-פעמית או אד-הוק.

ההשלכות של תמיכה מצטברת ותמיכה בדחיפה

הפעלת המנגנון עדכון פידים + שליחה מובילה לשיפורים הבאים:

• השותפים יכולים לספק את פיד התמונות בשיטת Push או בשיטת Pull. שותפים שלא רוצים לתחזק את נקודת הקצה (לשליפה) יכולים להשתמש במקום זאת בדחיפה כדי להפחית את עלות התחזוקה של נקודת הקצה. השותף כבר תומך בפידים של תמונות מצב בשיטת המשיכה (pull). אפשר להמשיך לשלוח תמונות מצב בשיטת המשיכה.
• שותפים יכולים להשתמש בשיטת העדכון המצטבר כדי לעדכן רק קבוצת משנה של ספקים בשינויים בפרופיל. כך משפרים את עדכניות נתוני הפרופיל.
• בקטע הזה מוסבר איך לבחור בין צילום מצב לבין נתונים מצטברים, ובין שליחה לבין משיכה.

גישה מומלצת לשילוב

השותפים נדרשים להשתמש בפידים של תמונות מצב תקופתיות, בין אם באמצעות שליחה או משיכה. כך, LSA יכול לטפל במקרי חירום כמו חזרה לגרסה קודמת ושחזור מערכת במקרה של עדכונים שהוחמצו.

• במנגנון הפוש, השותפים צריכים לשלוח פידים של פרופילים של תמונות מצב כל שעתיים, ולבדוק פידים כל 6 שעות כדי להבטיח את עדכניות הנתונים הבסיסית.
• במנגנון השליפה, LSA שולף פידים של פרופילים של תמונות מצב כל שעתיים ופידים של ביקורות כל 6 שעות כדי להבטיח עדכניות של נתוני הבסיס.
• השותפים צריכים להשתמש רק באחד מהמנגנונים (push או pull), ולא בשניהם, כדי לספק פידים של תמונות מצב.

לחלופין, שותפים שרוצים לשפר את עדכניות הנתונים יכולים לשלוח פידים של עדכונים באמצעות push. התכונה 'חיפוש מקומי' לא תמשוך פידים של עדכונים.

• פידים של עדכונים משמשים להפצת פריטים שהשתנו מאז תמונת המצב האחרונה, בלי לחכות לתמונת המצב הבאה.
• מומלץ לספקי LSA להגדיר מרווח של יותר מ-5 דקות בין שני פוש.
• מומלץ לאגד פריטי פיד בצורה סבירה בפיד עדכון. כדי לעדכן 5 ספקים, עדיף להשתמש בפיד עדכון אחד עם 5 פריטי פיד במקום ב-5 פידי עדכון עם פריט פיד אחד בכל אחד מהם.
• התכונה 'מודעות לקידום העסק המקומי' תומכת בפידים מצטברים רק עבור פידים של פרופילים, ולא עבור פידים של ביקורות.

ה-LSA יתייחס לשדה feedTimestampMicros במטא-נתונים כדי להבטיח עקביות בנתונים. אם המערכת קולטת פריט עדכני יותר שמעדכן את אותו מוצר, היא תדלג על פריט פיד עם חותמת זמן ישנה יותר כדי למנוע הצגה של נתונים לא עדכניים. השותף אחראי לשקף את עדכניות הנתונים בצורה נכונה באמצעות התג feedTimestampMicros בפידים של תמונת מצב ובפידים של עדכונים.

השותפים צריכים להשתמש ב-Reporting API כדי לקבל מידע על לידים וחיובים לכל ספק.