نظرة عامة على واجهة برمجة التطبيقات الفرعية للإشعارات

يمكنك استخدام واجهة برمجة التطبيقات الفرعية "الإشعارات" لتلقّي إشعارات فورية عند حدوث تغييرات في البيانات في حساباتك على Merchant Center. بدلاً من الاستطلاع الدوري لواجهة برمجة التطبيقات لرصد التغييرات، يمكنك الاشتراك في خلاصات الأحداث في الوقت الفعلي التي يتم تسليمها مباشرةً إلى نقطة نهاية HTTPS التي تحدّدها.

تتيح واجهة برمجة التطبيقات الفرعية "الإشعارات" إرسال إشعارات بشأن ما يلي:

  • التغييرات على حالة المنتج: تلقّي تنبيهات في الوقت الفعلي عند تغيُّر حالة الموافقة على منتج (مثلاً، عندما يصبح المنتج مرفوضًا أو مقبولاً) في أي من حساباتك المرتبطة أو حساباتك الفرعية
  • تغييرات خدمة الحساب: تلقّي تنبيهات في الوقت الفعلي عند إنشاء مورد AccountService أو تعديله أو حذفه (مثلما يحدث عند إنشاء علاقة بين حساب وخدمة أو تعديلها أو إزالتها)

المتطلبات الأساسية وإعداد معرّف الموارد المنتظم (URI) لمعاودة الاتصال

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

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

  • يجب أن تعرض إحدى رموز حالة HTTP التالية للإقرار باستلام الإشعار:

    • 102
    • 200
    • 201
    • 202
    • 204

يمكنك استخدام معرّف الموارد المنتظم (URI) نفسه لعدة اشتراكات. للحدّ من الحمل على نقطة نهاية واحدة، استخدِم معرّف موارد منتظمًا فريدًا لردّ الاتصال لكل حساب بامتيازات متقدّمة ونوع حدث.

إدارة الاشتراكات

توفّر واجهة برمجة التطبيقات الفرعية للإشعارات طرقًا لإنشاء عمليات ضبط الإشعارات وعرضها في قائمة واستردادها وتعديلها وحذفها.

إنشاء اشتراك

يقتصر إنشاء الاشتراك على نوع الحدث الذي تريد تلقّيه. يتطلّب كل نوع حدث حقول إعدادات مختلفة ويقدّم بنى حمولة مميّزة.

لمعرفة كيفية إنشاء الاشتراكات والاطّلاع على نماذج الطلبات لكل نوع من أنواع الأحداث، راجِع الأدلة ذات الصلة:

إدراج الاشتراكات

لإدراج جميع الاشتراكات في الإشعارات الخاصة بحساب، أرسِل طلب 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) الخاص بوظيفة رد الاتصال لاشتراك حالي، أرسِل طلب 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" المسجّل. يصل الإشعار الفوري في حزمة JSON مع حمولة data مرمّزة بترميز base64:

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

فك ترميز سلسلة البيانات للوصول إلى حمولة حدث 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