تلقّي إشعارات فورية بشأن التغييرات في بيانات منتجاتك

يمكنك استخدام Merchant Notifications API للحصول على إشعارات فورية بشأن التغييرات التي تطرأ على بيانات المنتجات. على سبيل المثال، إذا اشتركت في إشعارات بشأن تغيير حالة المنتج، يمكن أن يتم إعلامك في الوقت الفعلي عند رفض منتج. يمكنك الاشتراك في الإشعارات لأي من حساباتك الفرعية أو حساباتك المرتبط الأخرى.

يوفّر هذا الدليل أمثلة على كيفية إدارة الإشعارات المتعلّقة بتغيُّرات حالة المنتج. يمكنك استخدام هذه الأمثلة لإدارة الإشعارات للأحداث الأخرى من خلال تغيير قيمة الحقل registeredEvent في طلباتك. للحصول على قائمة كاملة بأنواع الأحداث، اطّلِع على مرجع Merchant Notifications API.

اشتراك

لتلقّي الإشعارات، تحتاج إلى callBackUri. يجب أن يستوفي عنوان URL لطلب إعادة الاتصال المتطلبات التالية:

• يجب أن يكون عنوان HTTPS متاحًا للجميع وأن يتضمّن شهادة طبقة المقابس الآمنة (SSL) صالحة موقّعة من هيئة إصدار الشهادات.
• يجب قبول طلبات HTTP POST باستخدام العنوان Content-Type وقيمة application/json.
• يجب عرض أحد رموز الاستجابة التالية للإشارة إلى تلقّي الإشعار.
  • 102
  • 200
  • 201
  • 202
  • 204

يمكنك استخدام عنوان URL نفسه للرجوع إلى اشتراكات متعددة. ننصحك باستخدام معرّف فريد لعنوان URL للرجوع لكل حساب متقدّم، ولكل نوع حدث بهدف تقليل عدد طلبات الإرسال الفوري إلى عنوان URL واحد.

في ما يلي نموذج طلب للاشتراك في إشعارات بشأن حالة المنتج وتغييراته لحساب تاجر محدّد.

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

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

غيِّر القيم في السلسلة على الشكل التالي:

• ‫MERCHANT_ID: المعرّف الفريد للحساب الذي من المفترض أن يتلقّى الإشعارات.
• TARGETMERCHANT_ID: المعرّف الفريد للحساب الذي تريد تلقّي إشعارات بشأنه

إذا كان حسابك على Merchant Center مستقلاً بدون حسابات مرتبطة، وكنت تريد تلقّي إشعارات لحسابك، استبدِل كلا المتغيّرَين بمعرّف حسابك.

تؤدي المكالمات الناجحة إلى عرض رمز name لاشتراكك، بما في ذلك رقم تعريف الاشتراك:

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

يمكنك استخدام هذه الميزة في اشتراكات فردية من name إلى GET وDELETE.

يمكنك الاشتراك في الإشعارات بشأن تغييرات حالة المنتجات لجميع حسابات المرتبطة من خلال تضمين "allManagedAccounts": true بدلاً من targetAccount في طلبك:

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

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

لتعديل اشتراك حالي، استخدِم PATCH مع update_mask لتحديد الحقول التي تريد تعديلها والقيم الجديدة في نص JSON:

PATCH https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_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/TARGETMERCHANT_ID",
  "managingAccount": "accounts/MERCHANT_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/TARGETMERCHANT_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) من قيمة التعداد 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}

استجابةً لهذا الطلب، من المفترض أن يعرض معرّف الموارد المنتظم لمعاودة الاتصال رمز استجابة ناجحة. يجب أن تحتوي الرسالة التي تم فك تشفيرها على القيمة التالية:

{
  "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"
}