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

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

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

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

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