במאמר הזה מוסבר איך אפליקציה יכולה לקבל הרשאה לשלוח בקשות ל-Tag Manager API.
הרשאה לבקשות
כדי שהמשתמשים יוכלו לראות את פרטי החשבון שלהם באתר Google כלשהו, הם צריכים קודם להיכנס באמצעות חשבון Google. באופן דומה, כשמשתמשים ניגשים לאפליקציה שלכם בפעם הראשונה, הם צריכים לאשר לאפליקציה לגשת לנתונים שלהם.
כל הבקשות שהאפליקציה שולחת ל-Tag Manager API חייבות לכלול אסימון הרשאה. אסימון ההרשאה גם מזהה את האפליקציה שלכם ב-Google.
הסבר על פרוטוקולים של הרשאות
כדי לאשר בקשות, האפליקציה חייבת להשתמש בפרוטוקול OAuth 2.0. אין תמיכה בפרוטוקולים אחרים של הרשאות. אם האפליקציה משתמשת בכניסה באמצעות חשבון Google, היבטים מסוימים של ההרשאות מטופלים באופן אוטומטי.
הרשאת בקשות עם פרוטוקול OAuth 2.0
כל הבקשות ל-Tag Manager API חייבות להיות מאושרות על ידי משתמש מאומת.
הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:
- כשאתם מפתחים את האפליקציה, צריך לרשום אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
- מפעילים את Tag Manager API ב-Google API Console. (אם ה-API לא מופיע ב-API Console, אפשר לדלג על השלב הזה).
- כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
- Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
- אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
- האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
- אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.
חלק מתהליכי העבודה כוללים שלבים נוספים, כמו שימוש באסימוני רענון כדי לקבל אסימוני גישה חדשים. למידע מפורט על תהליכי העבודה לסוגים שונים של אפליקציות, ניתן לעיין בתיעוד של OAuth 2.0 של Google.
הפרטים לגבי היקפי OAuth 2.0 ב-Tag Manager API:
| היקף | משמעות |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
הצגה של הפריטים המכילים שלכם ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containers |
ניהול הפריטים המכילים שלכם ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.delete.containers |
מחיקה של הפריטים המכילים שלכם ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
ניהול של גרסאות הגורמים המכילים ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.publish |
מפרסמים את הפריטים המכילים ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.manage.users |
ניהול של הרשאות משתמש בנתונים שלכם ב-Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
ניהול החשבונות שלכם ב-Google Tag Manager. |
כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).
תחילת העבודה
כדי להתחיל להשתמש ב-Tag Manager API, קודם צריך להשתמש בכלי ההגדרה, שמדריך אתכם בתהליך של יצירת פרויקט ב-Google API Console והפעלת ה-API.
כדי להגדיר חשבון שירות חדש:
- לוחצים על Create credentials > Service account key (יצירת אמצעי אימות > מפתח לחשבון שירות).
- בוחרים אם להוריד את המפתח הציבורי או הפרטי של חשבון השירות כקובץ P12 רגיל, או כקובץ JSON שאפשר לטעון באמצעות ספריית לקוח של Google API.
זוג המפתחות הציבורי/הפרטי החדש נוצר ומורד למחשב שלכם. זהו העותק היחיד של המפתח הזה. באחריותכם לאחסן אותו בצורה מאובטחת.
תהליכי OAuth 2.0 נפוצים
בהנחיות הבאות מפורטים תרחישים לדוגמה נפוצים לשימוש בתהליכי OAuth 2.0 ספציפיים:
שרת אינטרנט
התהליך הזה מתאים לגישה אוטומטית, לא מקוונת או מתוזמנת לחשבון Google Tag Manager של משתמש.
- עדכון אוטומטי של נתוני Tag Manager משרת.
צד הלקוח
האפשרות הזו מתאימה למקרים שבהם המשתמשים מקיימים אינטראקציה ישירה עם האפליקציה כדי לגשת לחשבון Google Tag Manager שלהם בדפדפן. התהליך הזה מבטל את הצורך ביכולות בצד השרת, אבל הוא גם לא מתאים ליצירת דוחות אוטומטיים, אופליין או מתוזמנים.
- כלי הגדרה מותאם אישית שמבוסס על דפדפן.
אפליקציות מותקנות
לאפליקציות שמופצות כחבילה ומוגדרות על ידי המשתמש. כדי להשלים את תהליך האימות, האפליקציה או המשתמש צריכים לקבל גישה לדפדפן.
- ווידג'ט לשולחן העבודה במחשב PC או Mac.
- תוסף למערכת ניהול תוכן. היתרון של התהליך הזה בהשוואה לשרת אינטרנט או לצד הלקוח הוא שאפשר להשתמש בפרויקט יחיד של קונסולת ה-API עבור האפליקציה. כך ההתקנה פשוטה יותר למשתמשים.
חשבונות שירות
השיטה הזו שימושית לגישה אוטומטית, לא מקוונת או מתוזמנת לחשבון Google Tag Manager שלכם. לדוגמה, כדי ליצור כלי בהתאמה אישית למעקב אחרי חשבון Google Tag Manager שלכם ולשתף אותו עם משתמשים אחרים.
פתרון בעיות
אם תוקף ה-access_token פג או שמשתמשים בהיקף הלא נכון עבור קריאה מסוימת ל-API, מקבלים קוד סטטוס 401 בתגובה.
אם למשתמש המורשה אין גישה לחשבון או למאגר התגים של Google Tag Manager, תקבלו קוד סטטוס 403 בתגובה. חשוב לוודא שאתם מורשים להיכנס לחשבון או למאגר התגים של Tag Manager עם המשתמש הנכון, ושיש לכם הרשאות גישה.
OAuth 2.0 Playground
OAuth 2.0 Playground מאפשר לכם לעבור את כל תהליך ההרשאה דרך ממשק אינטרנט. בנוסף, הכלי מציג את כל כותרות בקשות ה-HTTP שנדרשות כדי לבצע שאילתה מורשית. אם אתם לא מצליחים להגדיר הרשאה באפליקציה שלכם, כדאי לנסות להגדיר אותה באמצעות OAuth 2.0 Playground. אחר כך תוכלו להשוות בין כותרות ה-HTTP והבקשה מ-Playground לבין מה שהאפליקציה שלכם שולחת. הבדיקה הזו היא דרך פשוטה לוודא שהבקשות שלכם מפורמטות בצורה נכונה.
מענק לא חוקי
אם אתם מקבלים תגובת שגיאה invalid_grant כשאתם מנסים להשתמש בטוקן לרענון, יכול להיות שהשגיאה נגרמת מאחת מהסיבות הבאות או משתיהן:
- השעון של השרת לא מסונכרן עם NTP.
- חרגתם מהמגבלה של טוקן הרענון.
אפליקציות יכולות לבקש כמה טוקנים לרענון כדי לגשת לחשבון Google Tag Manager אחד. לדוגמה, זה שימושי במצבים שבהם משתמש רוצה להתקין אפליקציה בכמה מכונות ולגשת לאותו חשבון Google Tag Manager. במקרה כזה, נדרשים שני אסימוני רענון, אחד לכל התקנה. כאשר מספר טוקני הרענון חורג מהמגבלה, טוקנים ישנים יותר הופכים ללא תקפים. אם האפליקציה מנסה להשתמש בטוקן רענון לא תקף, מוחזרת תגובת שגיאהinvalid_grant. לכל שילוב ייחודי של מזהה לקוח/חשבון יכולים להיות עד 25 טוקנים לרענון. (שימו לב שהמגבלה הזו עשויה להשתנות). אם האפליקציה ממשיכה לבקש טוקנים לרענון עבור אותו שילוב של מזהה לקוח/חשבון, אחרי הנפקת הטוקן ה-26, הטוקן הראשון לרענון שהונפק הופך ללא תקף. בקשת הרענון ה-27 מבטלת את הטוקן השני שהונפק, וכן הלאה.