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

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

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

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

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

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

  • يجب أن يكون عنوان HTTPS متاحًا للجميع مع شهادة طبقة مقابس آمنة (SSL) صالحة موقَّعة من مرجع تصديق معترَف به.
  • يجب قبول طلبات 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