שליחת בקשות ישירות

מומלץ להשתמש בספריות הלקוח ובדוגמאות להטמעה. עם זאת, אם לשילוב שלכם עם ה-API יש צרכים מיוחדים, כמו שימוש בשפה שלא נתמכת, אתם יכולים לשלוח בקשות ישירות כמו שמתואר בהמשך.

סגנון השיחה

‫REST הוא סגנון של ארכיטקטורת תוכנה שמציע תפיסה נוחה ועקבית לבקשת נתונים ולשינוי שלהם.

המונח REST הוא קיצור של Representational State Transfer. בהקשר של Google APIs,‏ REST מתייחס לשימוש בפעלים של HTTP כדי לאחזר ולשנות ייצוגים של נתונים ש-Google מאחסנת.

במערכת RESTful, המשאבים מאוחסנים במאגר נתונים. לקוח שולח בקשה לשרת לבצע פעולה מסוימת (כמו יצירה, אחזור, עדכון או מחיקה של משאב), והשרת מבצע את הפעולה ושולח תגובה – לרוב בצורת ייצוג של המשאב שצוין.

בממשקי RESTful API של Google, הלקוח מציין פעולה באמצעות פועל של HTTP כמו POST,‏ GET,‏ PUT או DELETE. הוא מציין משאב לפי URI ייחודי גלובלי, באופן הבא:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

בגלל שלכל משאבי ה-API יש מזהה URI ייחודי שניתן לגשת אליו באמצעות HTTP,‏ ב-REST אפשר לשמור נתונים במטמון והוא מותאם לעבודה עם התשתית המבוזרת של האינטרנט.

תוכלו להיעזר בהגדרות השיטה במסמכי התיעוד של תקני HTTP 1.1 – הן כוללות מפרטים של GET,‏ POST,‏ PUT ו-DELETE.

‫REST ב-AdSense Management API

הפעולות הנתמכות ממופות ישירות לפעלים מסוג REST HTTP.

אלה הם הפורמטים שספציפיים למזהי URI של AdSense Management API:

https://adsense.googleapis.com/v2/resourceID?parameters

כאשר resourceID הוא המזהה של לקוח AdSense, יחידת מודעות, ערוץ של כתובת אתר, ערוץ מותאם אישית או אוסף הדוחות, ו-parameters הם פרמטרים שרוצים להחיל על השאילתה.

הפורמט של resourceIDתוספי הנתיב מאפשר לזהות את המשאב שבו אתם פועלים כרגע, למשל:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

הקבוצה המלאה של מזהי URI שמשמשים לכל פעולה נתמכת ב-API מסוכמת במסמך AdSense Management API Reference.

הנה כמה דוגמאות שממחישות איך זה עובד ב-AdSense Management API.

רשימת לקוחות של מודעות:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

רשימת יחידות המודעות בלקוח המודעות ca-pub-1234567890123456:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

פורמט נתונים

‫JSON‏ (JavaScript Object Notation) הוא פורמט נתונים נפוץ בלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף היכנסו לאתר של json.org.

אישור בקשות

שימו לב ש-AdSense לא תומך בחשבונות שירות, ולכן אתם צריכים להשתמש בתהליך של אפליקציה מותקנת.

כל בקשה שהאפליקציה שולחת ל-AdSense Management API חייבת לכלול אסימון הרשאה. אסימון ההרשאה גם מזהה את האפליקציה שלכם ב-Google.

הסבר על פרוטוקולים של הרשאות

כדי לאשר בקשות, האפליקציה חייבת להשתמש בפרוטוקול OAuth 2.0. אין תמיכה בפרוטוקולים אחרים של הרשאות. אם האפליקציה משתמשת בכניסה באמצעות חשבון Google, היבטים מסוימים של ההרשאות מטופלים באופן אוטומטי.

הרשאת בקשות עם פרוטוקול OAuth 2.0

כל הבקשות ל-AdSense Management API חייבות להיות מאושרות על ידי משתמש מאומת.

התהליך הזה מתבצע באמצעות מזהה לקוח OAuth.

איך מקבלים מזהה לקוח ב-OAuth

אפשר גם ליצור מפתח בדף Credentials.

הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:

  1. כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
  2. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  3. אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
  4. האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  5. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

חלק מתהליכי העבודה כוללים שלבים נוספים, כמו שימוש באסימוני רענון כדי לקבל אסימוני גישה חדשים. למידע מפורט על תהליכי העבודה לסוגים שונים של אפליקציות, ניתן לעיין בתיעוד של OAuth 2.0 של Google.

הפרטים לגבי היקפי OAuth 2.0 ב-AdSense Management API:

היקף משמעות
https://www.googleapis.com/auth/adsense גישת קריאה/כתיבה לנתוני AdSense.
https://www.googleapis.com/auth/adsense.readonly הרשאת קריאה בלבד לנתוני AdSense.

כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).

טיפ: ספריות הלקוח של Google APIs יכולות לטפל בחלק מתהליך ההרשאה בשבילכם. הן זמינות במגוון שפות תכנות. פרטים נוספים זמינים בדף עם הספריות והדוגמאות.

שליחת בקשה

השלב האחרון הוא שליחת בקשת ה-API. מידע ספציפי מופיע במאמרי העזרה.