Management API – הרשאה

במדריך הזה מוסבר איך אפליקציה מאשרת בקשות ל-Management API.

אישור בקשות

כדי שהמשתמשים יוכלו לצפות בפרטי החשבון שלהם באתר Google Analytics, עליהם להתחבר תחילה לחשבונות Google שלהם. באופן דומה, בפעם הראשונה שמשתמשים ניגשים לאפליקציה, הם צריכים להעניק לאפליקציה הרשאת גישה לנתונים שלהם.

כל בקשה שהאפליקציה שולחת ל-Analytics API חייבת לכלול אסימון הרשאה. אסימון ההרשאה גם מזהה את האפליקציה שלכם ב-Google.

הסבר על פרוטוקולים של הרשאות

כדי לאשר בקשות, האפליקציה חייבת להשתמש בפרוטוקול OAuth 2.0. אין תמיכה בפרוטוקולים אחרים של הרשאות. אם האפליקציה שלכם משתמשת באפשרות כניסה באמצעות חשבון Google, היבטים מסוימים של ההרשאה יטופלו עבורכם.

הרשאת בקשות עם פרוטוקול OAuth 2.0

כל הבקשות לממשק ה-API של Analytics חייבות לקבל הרשאה ממשתמש מאומת.

הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:

  1. בעת יצירת האפליקציה, עליך לרשום אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
  2. מפעילים את Analytics API ב-Google API Console. (אם ה-API לא רשום במסוף ה-API, אפשר לדלג על השלב הזה.)
  3. כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
  4. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  5. אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
  6. האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  7. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

חלק מתהליכי העבודה כוללים שלבים נוספים, כמו שימוש באסימוני רענון כדי לקבל אסימוני גישה חדשים. למידע מפורט על תהליכי העבודה לסוגים שונים של אפליקציות, ניתן לעיין בתיעוד של OAuth 2.0 של Google.

אלה פרטי ההיקף של OAuth 2.0 ב-Analytics API:

היקף ההרשאות משמעות
https://www.googleapis.com/auth/analytics.readonly הרשאת קריאה בלבד ל-Analytics API.
https://www.googleapis.com/auth/analytics.edit עריכת יישויות ניהול של Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users הצגה וניהול של הרשאות משתמשים בחשבונות Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly הצגת הרשאות משתמש ב-Google Analytics.

כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).

טיפ: ספריות הלקוח של Google APIs יכולות לטפל בחלק מתהליך ההרשאה עבורכם. הן זמינות למגוון שפות תכנות. מידע נוסף זמין בדף עם ספריות ודוגמאות.

תהליכי OAuth 2.0 נפוצים

למטה מפורטות התרחישים הנפוצים עבור זרימות OAuth 2.0 ספציפיות:

שרת אינטרנט

התהליך הזה מתאים לגישה אוטומטית, לא מקוונת או מתוזמנת של נתוני Google Analytics של משתמש.

דוגמה:

  • עדכון אוטומטי של מרכזי הבקרה של המשתמש בנתונים העדכניים ביותר של Google Analytics.

בצד הלקוח

התהליך הזה אידיאלי לאפליקציות שבהן משתמשים יוצרים אינטראקציה ישירה עם האפליקציה כדי לגשת לנתונים שלהם ב-Google Analytics בתוך דפדפן. התכונה הזו מבטלת את הצורך ביכולות בצד השרת, אבל היא הופכת את הדיווח האוטומטי, האופליין או המתוזמן למועד לא מעשי.

דוגמה:

אפליקציות מותקנות

תהליך זה מיועד לאפליקציות המופצות כחבילה ומותקנו על ידי המשתמש. בתהליך הזה, לאפליקציה או למשתמש צריכה להיות גישה לדפדפן כדי להשלים את תהליך האימות.

דוגמאות:

  • ווידג'ט למחשב שולחני במחשב PC או Mac.
  • פלאגין של מערכת לניהול תוכן — היתרון של התהליך הזה בהשוואה לשרת אינטרנט או בצד הלקוח הוא שאפשר להשתמש בפרויקט אחד של מסוף API לאפליקציה שלך. כך מתאפשר דיווח מאוחד והתקנה פשוטה יותר למשתמשים.

חשבונות שירות

חשבונות שירות שימושיים לגישה אוטומטית אל הנתונים ב-Google Analytics, באופן לא מקוון או מתוזמן. לדוגמה, כדי ליצור מרכז שליטה פעיל של נתוני Google Analytics, ולשתף אותו עם משתמשים אחרים.

כדי להתחיל להשתמש ב-Analytics API, קודם כול צריך להשתמש בכלי ההגדרה, שכולל הנחיות ליצירת פרויקט ב-Google API Console, להפעלת ה-API וליצירת פרטי כניסה.

כך מגדירים חשבון שירות חדש:

  1. לוחצים על יצירת פרטי כניסה > מפתח חשבון שירות.
  2. צריך לבחור אם להוריד את המפתח הציבורי/פרטי של חשבון השירות כקובץ P12 רגיל, או כקובץ JSON שאפשר לטעון בו ספריית לקוח ב-Google API.

זוג המפתחות הציבורי/הפרטי החדש נוצר ומווריד למחשב שלך. הוא משמש כעותק היחיד של המפתח הזה. אתם אחראים לאחסון שלה באופן מאובטח.

פתרון בעיות

ההרשאה שלך תיכשל במצבים הבאים:

  • אם קוד ה-access_token שלך פג או אם השתמשת בהיקף שגוי של ה-API, יישלח אליך קוד סטטוס של 401.

  • אם למשתמש המורשה אין גישה לתצוגה המפורטת (פרופיל) יישלח אליך קוד סטטוס 403. ודאו שיש לכם הרשאה עם המשתמש הנכון ושיש להם את התצוגה (הפרופיל) שבחרתם.

מגרש משחקים ב-OAuth 2.0

הכלי הזה מאפשר לכם לעבור את כל תהליך ההרשאה דרך ממשק האינטרנט. הכלי מציג גם את כל הכותרות של בקשות ה-HTTP הדרושות לביצוע שאילתה מורשית. אם אין לכם אפשרות לקבל הרשאה לעבוד באפליקציה שלכם, תוכלו לנסות להפעיל אותה דרך מגרש המשחקים OAuth 2.0. לאחר מכן תוכלו להשוות בין כותרות ה-HTTP ולבקש ממגרש המשחקים למה שהאפליקציה שלכם שולחת ל-Google Analytics. הבדיקה הזו היא דרך פשוטה לוודא שהפורמט של הבקשות שלכם תקין.

מענק לא חוקי

אם תנסו להשתמש באסימון רענון, תופיע הודעת השגיאה הבאה: invalid_grant

אפליקציות יכולות לבקש מספר אסימוני רענון לגשת לחשבון Google Analytics יחיד.

לדוגמה, אם משתמש רוצה להתקין אפליקציה במספר מחשבים ולגשת לאותו חשבון Google Analytics, יידרש אסימון נפרד לכל מחשב. כשאסימוני הרענון חורגים מהמגבלה, אסימונים ישנים יותר לא יהיו תקפים. אם האפליקציה מנסה להשתמש באסימון רענון לא תקף, תוחזר תגובה שגיאה של invalid_grant.

המגבלה של כל צמד ייחודי של לקוח OAuth 2.0 וחשבון Google Analytics היא 25 אסימוני רענון. אם האפליקציה תמשיך לבקש אסימוני רענון עבור אותו צמד לקוח/חשבון, לאחר הנפקת האסימון ה-26, אסימון הרענון הראשון שהונפק בעבר לא יהיה תקף. אסימון ה-27 המבוקש ל הערכים תוקפו יגרום לביטול האסימון השני שהופק בעבר וכן הלאה.