סקירה כללית על Notifications sub-API

אתם יכולים להשתמש ב-Notifications sub-API כדי לקבל התראות כשהנתונים בחשבונות Merchant Center שלכם משתנים. במקום לדגום את ה-API מדי פעם כדי לזהות שינויים, אתם יכולים להירשם לפידים של אירועים בזמן אמת שנשלחים ישירות לנקודת קצה (endpoint) מסוג HTTPS שאתם מגדירים.

ממשק ה-API המשני Notifications תומך בהתראות לגבי:

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

דרישות מוקדמות והגדרת URI להתקשרות חזרה (callback)

כדי לקבל התראות, צריך לספק callBackUri. כתובת ה-URI של ה-callback צריכה לעמוד בדרישות הבאות:

  • זו צריכה להיות כתובת HTTPS שנגישה לכולם, עם אישור SSL תקף שחתום על ידי רשות אישורים מוכרת.
  • השרת חייב לקבל בקשות HTTP POST עם הכותרת Content-Type שמוגדרת כ-application/json.

  • כדי לאשר שההתראה התקבלה, צריך להחזיר את אחד מקודי הסטטוס הבאים של HTTP:

    • 102
    • 200
    • 201
    • 202
    • 204

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

ניהול מינויים

ממשק ה-API המשני Notifications מספק שיטות ליצירה, להצגה, לאחזור, לעדכון ולמחיקה של הגדרות התראות.

יצירת מינוי

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

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

הצגת רשימת המינויים

כדי להציג רשימה של כל המינויים להתראות בחשבון, שולחים בקשת GET לאוסף notificationsubscriptions:

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions

אחזור מינוי

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

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

עדכון מינוי

כדי לעדכן את ה-URI של פונקציית ה-callback במינוי קיים, שולחים בקשת PATCH עם update_mask שמציין את השדות שרוצים לעדכן:

PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}?update_mask=callBackUri

{
  "callBackUri": "https://example.com/updated-callback"
}

מחיקת מינוי

כדי להפסיק לקבל התראות, צריך למחוק את המינוי:

DELETE https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

פענוח התראות

כשאירוע מתרחש, Google שולחת התראה ל-callBackUri הרשום. התראת ה-Push מגיעה במעטפת JSON עם מטען ייעודי (payload) של data בקידוד base64:

{"message":{"data":"{base64_encoded_string}"}}

מפענחים את מחרוזת הנתונים כדי לגשת למטען הייעודי (payload) של אירוע ה-JSON. הדוגמה הבאה של בקר Spring Boot מראה איך לקבל ולפענח התראות:

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void handleNotification(@RequestBody String message) {
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        String encodedData = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(encodedData);
        String decodedPayload = new String(decodedBytes);
        // Process decodedPayload according to the registered event type
  }
}

השלבים הבאים

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

הבא
Product status changes