روش های API

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

GetReader به ناشر اجازه می‌دهد تا بررسی کند که آیا یکی از خوانندگانش با PPID شناخته‌شده، اشتراک خود را به گوگل مرتبط کرده است یا خیر. با استفاده از یک درخواست GET ، ناشر درخواست PPID متعلق به یک شناسه انتشار خاص را می‌دهد.

درخواست

API REST: درخواست GET

https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid

کتابخانه کلاینت (Node.js)

async function getReader(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.get({
    name: `publications/${publicationId}/readers/${ppid}`,
  });
};

پاسخ

نقطه پایانی یا یک مقدار ۲۰۰ با بدنه JSON حاوی created_time اشتراک لینک‌شده برمی‌گرداند، یا اگر هیچ PPID برای انتشار پیدا نشود، خطایی نمایش می‌دهد. برای اطلاعات بیشتر به بخش خطاها مراجعه کنید.

{
  "name": "publications/CAowqfCKCw/readers/22553",
  "createTime": "2025-07-30T18:26:58.050224Z",
  "publicationId": "CAowqfCKCw",
  "ppid": "22553",
  "originatingPublicationId": "CAowqfCKCw"
}

GetReaderEntitlements

GetReaderEntitlements به ناشر اجازه می‌دهد تا برای PPID که قبلاً ارائه داده است، درخواست مجوز کند. با استفاده از درخواست GET، ناشر با ارائه PPID و شناسه انتشار، مجوزها را درخواست می‌کند.

درخواست

API REST: درخواست GET

https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid/entitlements

کتابخانه کلاینت (Node.js)

async function getReaderEntitlements(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.getEntitlements({
    name: `publications/${publicationId}/readers/${ppid}/entitlements`
  });
};

پاسخ

برای یک درخواست موفق، فرمت بازگشتی با فرمتی که برای ذخیره‌ی مقادیر دسترسی در درخواست UpdateReaderEntitlements PATCH استفاده شده است، یکسان است.

{
  "name": "publications/dailybugle.com/readers/6789/entitlements",
  "entitlements": [
      {
        "product_id": "dailybugle.com:basic",
        "subscription_token": "dnabhdufbwinkjanvejskenfw",
        "detail": "This is our basic plan",
        "expire_time": "2022-08-19T04:53:40+00:00"
      },
      {
        "product_id": "dailybugle.com:premium",
        "subscription_token": "wfwhddgdgnkhngfw",
        "detail": "This is our premium plan",
        "expire_time": "2022-07-19T04:53:40+00:00"
      },
      {
        "product_id": "dailybugle.com:deluxe",
        "subscription_token": "fefcbwinkjanvejfefw",
        "detail": "This is our deluxe plan",
        "expire_time": "2022-08-20T04:53:40+00:00"
      }
  ]
}

برای کاربرانی که مجوز ندارند، اما یک PPID مرتبط دارند (برای مثال، مجوزی که منقضی شده و حذف شده است)، درخواست مجوزها یک آرایه خالی از مجوزهای موجود را به عنوان بخشی از شیء استاندارد مجوزها برمی‌گرداند.

{
  "name": "publications/dailybugle.com/readers/6789/entitlements"
}

UpdateReaderEntitlements

UpdateReaderEntitlements برای ایجاد و به‌روزرسانی مجوزهای یک خواننده، بر اساس PPID آنها، استفاده می‌شود.

این نمونه داده به خواننده‌ای که PPID 6789 دارد، حق دسترسی به سه شناسه محصول برای روزنامه دیلی بیوگل را می‌دهد: dailybugle.com:basic ، dailybugle.com:premium و dailybugle.com:deluxe . هنگامی که خواننده 6789 متعاقباً از سطوح گوگل برای جستجو و کشف استفاده می‌کند، لیست «از اشتراک‌های شما» هر نتیجه مرتبطی از مقالات dailybugle.com را که با هر یک از این شناسه‌های محصول برچسب‌گذاری شده باشند، نمایش می‌دهد.

درخواست

API REST: درخواست PATCH

https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid/entitlements

بدنه درخواست: برای اطلاعات بیشتر در مورد شیء entitlements ، به صفحه واژه‌نامه مراجعه کنید.

{
  entitlements : [{
    product_id: `${publicationId}:basic`,
    subscription_token: 'abc1234',
    detail: 'This is our basic plan',
    expire_time: '2025-10-21T03:05:08.200564Z'
  }]
}

کتابخانه کلاینت (Node.js) 

async function updateReaderEntitlements(ppid) {
  const publicationId = process.env.PUBLICATION_ID;
  const requestBody = {
    entitlements : [{
      product_id: `${publicationId}:basic`,
      subscription_token: 'abc1234',
      detail: 'This is our basic plan',
      expire_time: '2025-10-21T03:05:08.200564Z'
    }]
  };
  return await client.publications.readers.updateEntitlements({
    name: `publications/${publicationId}/readers/${ppid}/entitlements`,
    requestBody
  });
}

پاسخ

پس از عملیات PATCH موفقیت‌آمیز، شیء entitlements ذخیره‌شده، با همان قالب GetReaderEntitlements بازگردانده می‌شود.

حذف کننده

DeleteReader به ناشر اجازه می‌دهد تا اشتراک لینک‌شده را به‌صورت دستی حذف کند. با استفاده از درخواست DELETE ، ناشر یک PPID برای شناسه انتشار ارسال می‌کند تا حذف شود.

قبل از فراخوانی DeleteReader ، یا باید ابتدا با استفاده UpdateReaderEntitlements با یک آرایه خالی ( { "entitlements": [] } ) مجوزهای دسترسی را حذف کنید، یا اگر نیاز به حذف یک خواننده دارای مجوز دارید، پارامتر اختیاری force را روی true تنظیم کنید. پارامتر force به طور پیش‌فرض روی false تنظیم شده است.

درخواست

REST API: درخواست DELETE 

https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/publicationId/readers/ppid?force={boolean}

کتابخانه کلاینت (Node.js) 

async function deleteReader(ppid, forceDelete = false) {
  const publicationId = process.env.PUBLICATION_ID;
  return await client.publications.readers.delete({
    name: `publications/${publicationId}/readers/${ppid}`,
    force: forceDelete
  });
}

پاسخ

یک حذف موفق، عدد ۲۰۰ را به همراه یک شیء JSON خالی {} برمی‌گرداند. 

{}