ממשק API של מחיקת משתמש – הרשאה

במדריך הזה מוסבר איך אפליקציה מאשרת בקשות ל-User Deletion 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. (אם ה-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.user.deletion מחיקת נתונים באמצעות User Deletion API.

כדי לבקש גישה באמצעות פרוטוקול 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 > מפתח חשבון שירות.
  2. בוחרים אם להוריד את המפתח הציבורי/פרטי של חשבון השירות כקובץ P12 רגיל, או כקובץ JSON שספריית לקוח של Google API יכולה לטעון.

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

פתרון בעיות

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

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

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

מגרש משחקים של OAuth 2.0

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

הרשאה לא חוקית

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

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

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

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