نمای کلی زیر API اعلان‌ها

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

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

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

پیش‌نیازها و تنظیمات URI مربوط به فراخوانی

برای دریافت اعلان‌های فوری، باید یک callBackUri ارائه دهید. URL بازگشتی شما باید شرایط زیر را داشته باشد:

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

  • برای تأیید دریافت اعلان، باید یکی از کدهای وضعیت HTTP زیر را برگرداند:

    • 102
    • 200
    • 201
    • 202
    • 204

می‌توانید از یک URL فراخوانی برای چندین اشتراک استفاده کنید. برای به حداقل رساندن بار روی یک نقطه پایانی، از یک URL فراخوانی منحصر به فرد برای هر حساب پیشرفته و نوع رویداد استفاده کنید.

مدیریت اشتراک‌ها

زیر-API اعلان‌ها (Notifications) روش‌هایی برای ایجاد، فهرست کردن، بازیابی، به‌روزرسانی و حذف پیکربندی‌های اعلان ارائه می‌دهد.

ایجاد اشتراک

ایجاد اشتراک مختص نوع رویدادی است که می‌خواهید دریافت کنید. هر نوع رویداد به فیلدهای پیکربندی متفاوتی نیاز دارد و ساختارهای بار داده متمایزی را ارائه می‌دهد.

برای یادگیری نحوه ایجاد اشتراک و مشاهده درخواست‌های نمونه برای هر نوع رویداد، به راهنماهای مربوطه مراجعه کنید:

اشتراک‌ها را فهرست کنید

برای فهرست کردن تمام اشتراک‌های اعلان برای یک حساب کاربری، یک درخواست 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}

به‌روزرسانی اشتراک

برای به‌روزرسانی URL فراخوانی برای یک اشتراک موجود، یک درخواست 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}

رمزگشایی اعلان‌ها

وقتی رویدادی رخ می‌دهد، گوگل یک اعلان به callBackUri ثبت‌شده‌ی شما ارسال می‌کند. این اعلان در یک پاکت JSON با یک payload 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