ממשק ה-API הראשי לדיווח – הרשאה

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

הרשאת בקשות

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

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

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

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

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

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

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

  1. כשאתם יוצרים את האפליקציה, עליכם לרשום אותה באמצעות מסוף Google API. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
  2. להפעיל את Analytics API ב-Google API Console. (אם ממשק ה-API לא מופיע ב-API Console, דלגו על השלב הזה).
  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 הרשאת קריאה בלבד ל-API של 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, הפעלת ה-API ויצירת פרטי כניסה.

כדי להגדיר חשבון שירות חדש:

  1. לוחצים על Create credentials > Service account key.
  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 יבטל את האסימון השני שהונפק בעבר, וכן הלאה.