קבלת התראות על שינויים בנתוני המוצרים

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

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

הרשמה

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

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

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

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

POST https://merchantapi.googleapis.com/notifications/v1/accounts/ACCOUNT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETACCOUNT_ID",
  "callBackUri": "https://example.com"
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ACCOUNT_ID: המזהה הייחודי של החשבון שאליו יש לשלוח את ההתראות.
  • ‫TARGETACCOUNT_ID: המזהה הייחודי של החשבון שרוצים לקבל עליו התראות.

אם חשבון Merchant Center שלכם הוא חשבון עצמאי ללא חשבונות מקושרים, ואתם רוצים לקבל התראות לגבי החשבון שלכם, צריך להחליף את שני המשתנים האלה במזהה החשבון שלכם.

קריאות מוצלחות מחזירות name למינוי, כולל מזהה המינוי:

{
  "name":"accounts/ACCOUNT_ID/notificationsubscriptions/subscriptionId",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETACCOUNT_ID",
  "callBackUri": "https://example.com"
}

אפשר להשתמש בname הזה כדי GET וDELETE מינויים בודדים.

כדי להירשם לקבלת התראות על שינויים בסטטוס המוצר בכל החשבונות המקושרים, צריך לכלול "allManagedAccounts": trueבמקום targetAccount בבקשה:

POST https://merchantapi.googleapis.com/notifications/v1/accounts/ACCOUNT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com"
}

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

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

{
  "​callBackUri": "https://my-own-personal-domain.com"
}

פענוח התראות

אחרי שיוצרים מינוי, מקבלים התראות לכתובת callBackUri שצוינה בפורמט הבא:

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

נתוני ההתראה מקודדים. אפשר לפענח את הנתונים לפורמט טקסט קריא כדי להשתמש בהם בהטמעה. זו דוגמה לבקר spring boot שאפשר להשתמש בו כדי לעבד את הנתונים המקודדים:

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void doStuff(@RequestBody String message) {
        //wrapped message
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        message = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(message);
        String decodedMessage = new String(decodedBytes);
        // Implement your business logic here
  }
}

דוגמה ל-base64_encoded_string שעבר פענוח:

{
  "account": "accounts/TARGETACCOUNT_ID",
  "managingAccount": "accounts/ACCOUNT_ID",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/TARGETACCOUNT_ID/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

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

אם המוצר נמחק, השדה expirationTime לא יופיע.

השדה reportingContext תומך רק בערכים (SHOPPING_ADS, ‏ LOCAL_INVENTORY_ADS, ‏ YOUTUBE_SHOPPING, ‏ YOUTUBE_CHECKOUT, ‏ YOUTUBE_AFFILIATE) מתוך ערך ה-enum‏ ReportingContextEnum.

באירוע של שינוי סטטוס המוצר, השדות oldValue ו-newValue יכילו אחד מהערכים האלה : (approved, ‏ pending, ‏ disapproved, ‏ ``).

השדה eventTime מכיל את זמן היצירה של האירוע עצמו. אם רוצים לבצע סידור של ההודעות, צריך להסתמך על הערך בשדה הזה ולא על סדר קבלת ההודעות.

פרטים נוספים זמינים בפורמט ProductStatusChangeMessage.

מבצעים בדיקות של ההטמעה.

הנה הודעה לדוגמה שאפשר להשתמש בה כדי לבדוק את ה-URI של הקריאה החוזרת ואת הפענוח:

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}' https://{callBackUri}

בתגובה לשיחה הזו, ה-URI של הקריאה החוזרת צריך להחזיר קוד תגובה של הצלחה. הערך של ההודעה המפוענחת צריך להיות:

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}
הקודם
Control access to your account
הבא
Enable automatic improvements