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

להטמעה מומלץ להשתמש בספריות ובדוגמאות של הלקוח. עם זאת, אם לשילוב עם ה-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, כפי שמתואר בפעולות של ממשק API לניהול AdSense.

הפורמט הספציפי למזהי 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 מסוכמת במאמר חומר העזר בנושא API לניהול של AdSense.

הנה כמה דוגמאות לאופן שבו זה עובד ב-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. מידע ספציפי מופיע במאמרי העזרה.