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

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

סגנון שיחה

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

המונח REST הוא קיצור של Representational State Transfer. בהקשר של ממשקי ה-API של Google,‏ 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, כפי שמתואר בקטע פעולות ב-AdSense Management API.

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

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

כאשר resourceID הוא המזהה של לקוח מודעה, יחידת מודעות, ערוץ של כתובות URL, ערוץ מותאם אישית או אוסף הדוחות, ו-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.

הנה כמה דוגמאות שממחישות איך זה עובד ב-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

או ליצור חשבון בדף פרטי הכניסה.

הפרטים או ה"זרימה" של תהליך ההרשאה עם 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. למידע ספציפי, עיינו במסמכי התיעוד.