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

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/gtech-demo.appspot.com/readers/81112",  
  "create_time": "2022-04-19T04:53:40+00:00"
}

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"
      }
  ]
}

بالنسبة إلى المستخدمين الذين ليس لديهم أذونات، ولكن لديهم معرّف مستخدم مرتبط (على سبيل المثال، إذن انتهت صلاحيته وتم حذفه)، سيؤدي طلب الأذونات إلى عرض صفيف أذونات فارغ كجزء من عنصر الأذونات العادي.

{
  "name": "publications/dailybugle.com/readers/6789/entitlements",
  "createTime": "2023-02-07T17:38:57.425577Z"
}

UpdateReaderEntitlements

يُستخدَم UpdateReaderEntitlements لإنشاء أذونات للقارئ وتعديلها استنادًا إلى معرّف PPID.

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

قبل استدعاء 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 فارغ {}.

{}