כל הקריאות ל-Google Ad Manager API חייבות להיות מאושרות באמצעות OAuth2, תקן פתוח שמאפשר למשתמשים להעניק הרשאות לאפליקציות של צד שלישי, כדי שהאפליקציה תוכל ליצור אינטראקציה עם שירותי אינטרנט בשם המשתמש. OAuth2 מאפשר לאפליקציית הלקוח של Ad Manager API לגשת לחשבון Ad Manager של משתמש בלי לטפל בשם המשתמש או בסיסמה של המשתמש או לאחסן אותם.
יצירת פרטי כניסה של OAuth2
כדי ליצור את פרטי הכניסה של OAuth2:
1. קביעת סוג האימות
בטבלה שבהמשך אפשר לראות איזה סוג אימות הכי מתאים לאפליקציית Ad Manager API שלכם:
| בחירת סוג האימות OAuth2 | |
|---|---|
| חשבון שירות |
בוחרים באפשרות הזו אם אתם צריכים גישה רק לנתונים שלכם ב-Ad Manager. מידע נוסף |
| אפליקציית אינטרנט |
בוחרים באפשרות הזו אם רוצים לבצע אימות בתור משתמש שהעניק לאפליקציה הרשאה לגשת לנתונים שלו ב-Ad Manager. מידע נוסף |
2. יצירת פרטי כניסה של OAuth2
אחרי שקובעים את סוג האימות, לוחצים על הכרטיסייה המתאימה למטה ופועלים לפי ההוראות ליצירת פרטי הכניסה של OAuth2:
- פותחים את דף האישורים ב-Google API Console.
- בתפריט הנפתח של הפרויקט, בוחרים באפשרות Create a new project, מזינים שם לפרויקט ועורכים את מזהה הפרויקט שמופיע (אם רוצים). לוחצים על יצירה.
- בדף Credentials (פרטי כניסה), בוחרים באפשרות Create credentials (יצירת פרטי כניסה) ואז באפשרות Service account key (מפתח של חשבון שירות).
- בוחרים באפשרות New service account (חשבון שירות חדש) ואז באפשרות JSON.
- לוחצים על Create כדי להוריד קובץ שמכיל מפתח פרטי.
- פותחים את דף האישורים ב-Google API Console.
- בתפריט הנפתח של הפרויקט, בוחרים באפשרות Create a new project, מזינים שם לפרויקט (ואפשר גם לערוך את מזהה הפרויקט שמופיע), ולוחצים על Create.
- בדף Credentials (פרטי כניסה), בוחרים באפשרות Create credentials (יצירת פרטי כניסה) ואז באפשרות OAuth client ID (מזהה לקוח OAuth).
- יכול להיות שתתבקשו להגדיר שם מוצר בדף Consent Screen (מסך הסכמה). אם כן, לוחצים על Configure consent screen (הגדרת מסך הסכמה), מספקים את המידע הנדרש ולוחצים על Save (שמירה) כדי לחזור לדף Credentials (פרטי כניסה).
- ב-Application Type בוחרים באפשרות Web Application. פועלים לפי ההוראות כדי להזין מקורות JavaScript, כתובות URI להפניה או את שניהם.
- לוחצים על יצירה.
- בדף שמופיע, מעתיקים את מזהה הלקוח ואת הסוד של הלקוח ללוח, כי תצטרכו אותם כשתגדירו את ספריית הלקוח.
3. הגדרת רשת Ad Manager
אם אתם מפתחים של צד שלישי, יכול להיות שתצטרכו לבקש מהלקוח שלכם לבצע את השלב הזה בשבילכם.
- עוברים אל רשת Ad Manager.
- לוחצים על הכרטיסייה אדמין.
- מוודאים שגישה ל-API מופעלת.
- לוחצים על הלחצן הוספת משתמש לחשבון שירות.
- ממלאים את הטופס באמצעות כתובת האימייל של חשבון השירות. למשתמש בחשבון השירות צריכות להיות הרשאות גישה לישויות, כאילו הוא ניגש לישויות בממשק המשתמש.
- לוחצים על הלחצן שמירה. אמורה להופיע הודעה שמאשרת את הוספת חשבון השירות.
- כדי לראות את המשתמשים הקיימים בחשבון השירות, עוברים לכרטיסייה Users (משתמשים) ולוחצים על המסנן Service Account (חשבון שירות).
- עוברים אל רשת Ad Manager.
- לוחצים על הכרטיסייה אדמין.
- מוודאים שגישה ל-API מופעלת.
4. הגדרה ושימוש בספריית לקוח
כדי להשתמש בפרטי הכניסה בספריית הלקוח, פועלים לפי המדריך המתאים שמופיע בהמשך:
Java
.NET
Python
PHP
Ruby
אם תבחרו לא להשתמש באחת מהספריות של הלקוח שלנו, תצטרכו להטמיע בעצמכם את תהליך העבודה של חשבון שירות או של אפליקציית אינטרנט ב-OAuth2.
מאחורי הקלעים
ספריות הלקוחות שלנו מטפלות באופן אוטומטי בפרטים שמפורטים בהמשך, לכן כדאי להמשיך לקרוא רק אם אתם רוצים לדעת מה קורה מאחורי הקלעים. הסעיף הזה מיועד למשתמשים מתקדמים שכבר מכירים את המפרט של OAuth2 ויודעים איך להשתמש ב-OAuth2 עם Google APIs.
כותרת של בקשת HTTP
כותרת ה-HTTP בכל בקשה ל-Ad Manager API חייבת לכלול אסימון גישה בפורמט הבא:
Authorization: Bearer ACCESS_TOKEN
לדוגמה:
POST … HTTP/1.1 Host: … Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg Content-Type: text/xml;charset=UTF-8 Content-Length: … <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"> … </soap:Envelope>
היקף
טוקן גישה אחד יכול להעניק רמות שונות של גישה למספר ממשקי API. פרמטר משתנה בשם scope שולט בסדרת המשאבים והפעולות שטוקן גישה מאפשר. במהלך בקשת הגישה לטוקן, האפליקציה שולחת ערך אחד או יותר בפרמטר scope.
ל-Ad Manager יש רק היקף אחד, שמוצג בהמשך. ההרשאה צריכה להתבצע ברמת המשתמש בתוך המוצר.
| היקף | הרשאות |
|---|---|
https://www.googleapis.com/auth/admanager |
אפשר להציג ולנהל את הקמפיינים ב-Ad Manager. |