'פעולות שיחה' יוצאו משימוש ב-13 ביוני 2023. מידע נוסף זמין במאמר שקיעה בקריאות לפעולה.

קישור חשבונות באמצעות OAuth

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

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

בתהליך קוד ההרשאה צריכות להיות שתי נקודות קצה:

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

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

הטמעה של קישור לחשבון OAuth

הגדרת הפרויקט

כדי להגדיר את הפרויקט לשימוש בקישור OAuth, מבצעים את הפעולות הבאות:

  1. פותחים את Actions Console ובוחרים את הפרויקט שבו רוצים להשתמש.
  2. לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות קישור חשבונות.
  3. מפעילים את המתג שלצד האפשרות קישור חשבון.
  4. בקטע יצירת חשבון, בוחרים באפשרות לא, אני רוצה לאפשר את יצירת החשבון רק באתר שלי.

  5. בקטעים סוג קישור, בוחרים באפשרות OAuth ומרומז.

  6. בקטע פרטי הלקוח:

    • מקצים ערך ל-Client ID שמונפק על ידי Google Actions כדי לזהות בקשות מ-Google.
    • יש להזין את כתובות ה-URL של נקודות הקצה של Authorization ו- Token Exchange.
  1. לוחצים על שמירה.

הטמעה של שרת ה-OAuth

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

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

זהו תהליך גמיש משתמע של OAuth 2.0 ש-Google מפעילה, בתהליך הזה:

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

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

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

פרמטרים של נקודות קצה להרשאה
client_id מספר הלקוח שהקצית ל-Google.
redirect_uri כתובת ה-URL שאליה נשלחת התגובה לבקשה הזו.
state ערך של הנהלת דומיין שמועבר חזרה ל-Google ללא שינוי ב-URI של ההפניה האוטומטית.
response_type סוג הערך שיש להחזיר בתגובה. בתהליך המשתמע של OAuth 2.0, סוג התגובה הוא תמיד token.

לדוגמה, אם נקודת הקצה להרשאה זמינה ב-https://myservice.example.com/auth, הבקשה עשויה להיראות כך:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

כדי שנקודת הקצה להרשאה תטפל בבקשות לכניסה, יש לבצע את השלבים הבאים:

  1. מאמתים את הערכים client_id ו-redirect_uri כדי למנוע הענקת גישה לאפליקציות של לקוחות שלא הוגדרו או שיש להן הגדרה שגויה:

    • ודאו שהמספר client_id תואם למספר הלקוח שהוקצה ל-Google.
    • מוודאים שכתובת ה-URL שצוינה בפרמטר redirect_uri כוללת את הטופס הבא:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID הוא המזהה שנמצא בדף הגדרות הפרויקט ב-Actions Console.
  2. בודקים אם המשתמש מחובר לשירות שלכם. אם המשתמש לא מחובר לחשבון, עליך להשלים את תהליך הכניסה או ההרשמה לשירות.

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

  4. יש לשלוח תגובת HTTP שמפנה את דפדפן המשתמש לכתובת ה-URL שצוינה בפרמטר redirect_uri. בכל קטע URL יש לכלול את כל הפרמטרים הבאים:

    • access_token: אסימון הגישה שיצרת עכשיו
    • token_type: המחרוזת bearer
    • state: ערך המצב שלא השתנה מהבקשה המקורית הדוגמה בדוגמה לכתובת URL שהתקבלה:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

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

תכנון ממשק המשתמש של הקול לתהליך האימות

בודקים אם המשתמש מאומת ומתחילים בתהליך קישור החשבונות

  1. פותחים את פרויקט Actions Builder בקונסולה ל-Actions.
  2. יוצרים סצנה חדשה כדי להתחיל בקישור החשבונות בפעולה:
    1. לוחצים על תרחישים.
    2. לוחצים על סמל ההוספה (+) כדי להוסיף סצנה חדשה.
  3. בסצנה החדשה שנוצרה, לחצו על סמל ההוספה עבור תנאים.
  4. הוסיפו תנאי שיבדוק אם המשתמש שמשויך לשיחה הוא משתמש מאומת. אם הבדיקה נכשלה, לא ניתן לבצע את קישור החשבון במהלך השיחה, ויש לחזור אליה כדי לקבל גישה לפעולות שלא דורשות קישור לחשבון.
    1. בשדה Enter new expression בקטע תנאי, מזינים את הלוגיקה הבאה: user.verificationStatus != "VERIFIED"
    2. בקטע מעבר, בוחרים סצנה שלא מצריכה קישור לחשבון או סצינה שהיא נקודת הכניסה לפונקציונליות של אורחים בלבד.

  1. לוחצים על סמל ההוספה לצד תנאים.
  2. הוסיפו תנאי להפעלת תהליך קישור חשבונות, אם אין למשתמש זהות משויכת.
    1. בשדה Enter new expression בקטע תנאי, מזינים את הלוגיקה הבאה: user.verificationStatus == "VERIFIED"
    2. בקטע מעבר, בוחרים בסצינת המערכת קישור חשבונות.
    3. לוחצים על שמירה.

בסיום השמירה, תתווסף לפרויקט שלכם סצינת מערכת חדשה לקישור חשבונות בשם <SceneName>_AccountLinking.

התאמה אישית של סצנת קישור החשבונות

  1. בקטע תרחישים, בוחרים בסצינת המערכת לקישור חשבונות.
  2. לוחצים על שליחת בקשה ומוסיפים משפט קצר כדי לתאר למשתמש למה הפעולה צריכה לגשת לזהות שלו (לדוגמה, כדי "לשמור את ההעדפות שלכם").
  3. לוחצים על שמירה.

  1. בקטע תנאים, לוחצים על אם המשתמש ישלים בהצלחה את קישור החשבון.
  2. צריך להגדיר את המשך התהליך אם המשתמש מסכים לקשר את החשבון שלו. לדוגמה, אפשר לקרוא ל-webhook כדי לעבד את הלוגיקה העסקית המותאמת אישית ולחזור לסביבת המקור.
  3. לוחצים על שמירה.

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

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

טיפול בבקשות גישה לנתונים

אם הבקשה ל-Assistant מכילה אסימון גישה, קודם צריך לבדוק שאסימון הגישה תקין (ולא פג תוקף) ואז לאחזר את חשבון המשתמש המשויך ממסד הנתונים שלכם.