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

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

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

اشتراك

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

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

يمكنك استخدام معرّف الموارد المنتظم (URI) نفسه لعدة اشتراكات. ننصحك باستخدام معرّف URI فريد لكل حساب متقدّم، ولكل نوع حدث، وذلك للحدّ من عدد طلبات الإرسال إلى معرّف 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) من قيمة التعداد 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"
}
السابق
Control access to your account
التالي
Enable automatic improvements