כל הקריאות ל-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:
- פותחים את הדף Credentials ב-Google API Console.
- בתפריט הנפתח של הפרויקט, בוחרים באפשרות Create a new project, נותנים שם לפרויקט ואם רוצים, עורכים את מזהה הפרויקט שסופק. לוחצים על Create.
- בדף Credentials, לוחצים על Create credentials ואז על Service account key.
- בוחרים באפשרות New service account, ואז באפשרות JSON.
- לוחצים על Create כדי להוריד קובץ שמכיל מפתח פרטי.
- פותחים את הדף Credentials ב-Google API Console.
- בתפריט הנפתח של הפרויקט, בוחרים באפשרות Create a new project, נותנים שם לפרויקט (ואם רוצים, עורכים את מזהה הפרויקט שסופק) ולוחצים על Create.
- בדף Credentials, לוחצים על Create credentials ואז על OAuth client ID.
- יכול להיות שתתבקשו להגדיר שם מוצר בדף מסך הסכמה. אם כן, לחצו על Configure consent screen, הזינו את המידע הנדרש ולחצו על Save כדי לחזור לדף Credentials.
- בקטע Application Type, בוחרים באפשרות אפליקציית אינטרנט. פועלים לפי ההוראות כדי להזין מקורות 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. |