نمای کلی زیرمیانای برنامه‌سازی کاربردی اعلان‌ها

می‌توانید از زیرمیانای برنامه‌سازی کاربردی «اعلان‌ها» برای دریافت اعلان لحظه‌ای هنگام تغییر داده‌ها در حساب‌های Merchant Center خود استفاده کنید. به‌جای نظرسنجی دوره‌ای از API برای شناسایی تغییرات، می‌توانید در فیدهای رویداد هم‌زمان که مستقیماً به نقطه پایانی HTTPS که پیکربندی می‌کنید ارسال می‌شوند مشترک شوید.

‫Notifications sub-API از اعلان‌های موارد زیر پشتیبانی می‌کند:

• تغییرات وضعیت محصول: هنگامی که وضعیت تأیید محصول تغییر می‌کند (برای مثال، وقتی محصولی رد یا تأیید می‌شود) در هریک از حساب‌های پیوندشده یا حساب‌های فرعی خود، هشدارهای هم‌زمان دریافت کنید.
• تغییرات سرویس حساب: هنگام ایجاد، به‌روزرسانی، یا حذف منبع AccountService، هشدارهای هم‌زمان دریافت کنید (مثلاً وقتی رابطه سرویس حساب برقرار، اصلاح، یا برداشته می‌شود).

پیش‌نیازها و راه‌اندازی URI فراخوانی برگشتی

برای دریافت اعلان‌های لحظه‌ای، باید callBackUri ارائه دهید. شناسه منبع یکسان فراخوانی برگشتی شما باید الزامات زیر را برآورده کند:

• باید نشانی HTTPS با دسترسی عمومی و گواهی SSL معتبر باشد که توسط مرجع صدور گواهی معتبر امضا شده باشد.
• باید درخواست‌های HTTP POST را با سرصفحه Content-Type تنظیم‌شده روی application/json بپذیرد.

• باید یکی از رمزهای وضعیت اچ‌تی‌تی‌پی‌اس زیر را برگرداند تا تأیید کند که اعلان دریافت شده است:

  • 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
  }
}

مراحل بعدی

برای پیکربندی اشتراک‌ها و مدیریت بارداده‌های رمزگشایی‌شده برای رویدادهای خاص، به این موارد مراجعه کنید:

• دریافت اعلان لحظه‌ای برای تغییرات وضعیت محصول: با نحوه مشترک شدن در به‌روزرسانی‌های تأیید و رد محصول و تجزیه کردن بارداده ProductStatusChangeMessage آشنا شوید.
• دریافت اعلان لحظه‌ای برای تغییرات سرویس حساب: با نحوه مشترک شدن در به‌روزرسانی‌های رابطه حساب و تجزیه کردن ResourceChangeMessage بار داده آشنا شوید.