طرق واجهة برمجة التطبيقات

GetReader

تسمح طريقة GetReader للناشر بالتحقّق مما إذا كان أحد قرّائه الذين لديهم معرّف PPID معروف قد ربط اشتراكه بخدمات Google. باستخدام طلب GET، يستعلم الناشر عن معرّف PPID تابع لمعرّف منشور معيّن.

طلب

واجهة برمجة تطبيقات 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}`,
  });
};

الردّ

ستعرض نقطة النهاية إما الرمز 200 مع نص 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 ومعرّف منشور.

طلب

واجهة برمجة تطبيقات 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 أذونات وصول إلى ثلاثة أرقام تعريف منتجات لصحيفة The Daily Bugle، وهي dailybugle.com:basic وdailybugle.com:premium وdailybugle.com:deluxe. عندما يستخدم القارئ 6789 لاحقًا واجهات Google للبحث و"اقتراحات"، ستعرض قائمة "من اشتراكاتك" أي نتائج ذات صلة من مقالات dailybugle.com التي تم وضع علامة عليها بأي من أرقام تعريف المنتجات هذه.

**ملاحظة:** تُستخدَم هذه الطريقة لإنشاء أذونات الوصول الأولية لقارئ وتعديلها.

طلب

واجهة برمجة تطبيقات 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

تسمح طريقة DeleteReader للناشر بحذف اشتراك مرتبط يدويًا. باستخدام طلب DELETE، يرسل الناشر المعرّف المقدَّم من الناشر (PPID) لمعرّف جهة النشر ليتم حذفه.

قبل استدعاء DeleteReader، عليك إما حذف أذونات الوصول أولاً باستخدام UpdateReaderEntitlements مع مصفوفة فارغة ({ "entitlements": [] })، أو ضبط المعلمة الاختيارية force على true إذا كنت بحاجة إلى حذف قارئ لديه أذونات وصول. القيمة التلقائية للمعلمة force هي false.

طلب

واجهة برمجة تطبيقات REST: طلب 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
  });
}

الردّ

عند نجاح عملية الحذف، يتم عرض الرمز 200 مع كائن JSON فارغ {}.

{}