שיטות API

GetReader

GetReader מאפשר למוציא לאור לאמת אם אחד מהקוראים שלו עם מזהה PPID ידוע קישר את המינוי שלו ל-Google. באמצעות בקשה מסוג 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}`,
  });
};

תשובה

נקודת הקצה תחזיר קוד 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 ומזהה אתר.

בקשה

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`
  });
};

תשובה

אם הבקשה תתבצע בהצלחה, הפורמט של ההחזרה יהיה זהה לפורמט שבו משתמשים לאחסון ההרשאות בבקשה PATCH של UpdateReaderEntitlements.

{
  "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 לחיפוש ול-Discover, ברשימה 'מהמינויים שלך' יוצגו תוצאות רלוונטיות מכתבות ב-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

DeleteReader מאפשר לבעלי תוכן דיגיטלי למחוק באופן ידני מינוי מקושר. באמצעות בקשה מסוג DELETE, בעל התוכן הדיגיטלי שולח מזהה PPID של מזהה אתר חדשות שרוצים למחוק.

לפני שמפעילים את DeleteReader, צריך קודם למחוק את ההרשאות באמצעות UpdateReaderEntitlements עם מערך ריק ({ "entitlements": [] }), או להגדיר את הפרמטר האופציונלי force לערך true אם רוצים למחוק קורא שיש לו הרשאות. ברירת המחדל של הפרמטר force היא false.

בקשה

API ל-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 ריק {}.

{}