דף זה תורגם על ידי Cloud Translation API.

מסמך עזרה בנושא Google Account Authorization JavaScript API

במסמך הזה מוסבר על Google Account Authorization JavaScript API, שמשמש לקבלת קודי הרשאה או אסימוני גישה מ-Google.

שיטה: google.accounts.oauth2.initCodeClient

השיטה initCodeClient מאתחלת ומחזירה לקוח קוד, עם ההגדרות בפרמטר.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

סוג הנתונים: CodeClientConfig

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים CodeClientConfig.

מאפיינים
`client_id`	חובה. מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה ב-API Console.
`scope`	חובה. רשימה של היקפי הרשאות שמופרדים באמצעות רווחים ומזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משמשים להצגת מסך ההסכמה ש-Google מציגה למשתמש.
`include_granted_scopes`	אופציונלי, ברירת המחדל היא `true`. מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפי הרשאות נוספים בהקשר. אם מגדירים את הערך של הפרמטר הזה כ-`false` ובקשת ההרשאה מאושרת, אז אסימון הגישה החדש יכלול רק את ההיקפים ש`scope` ביקש ב-`CodeClientConfig`.
`redirect_uri`	נדרש לחוויית המשתמש של ההפניה לכתובת אחרת. ההגדרה קובעת לאן שרת ה-API מפנה את המשתמש אחרי שהוא מסיים את תהליך ההרשאה. הערך צריך להיות זהה לאחד מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם ב-API Console, והוא צריך לעמוד בדרישות כללי האימות של כתובות ה-URI להפניה אוטומטית. המערכת תתעלם מהמאפיין בממשק המשתמש של החלון הקופץ.
`callback`	נדרש לחוויית משתמש של חלונות קופצים. פונקציית JavaScript שמטפלת בתגובת הקוד שהוחזרה. חוויית המשתמש של ההפניה תתעלם מהנכס.
`state`	אופציונלי. מומלץ לשיפור חוויית המשתמש בהפניה אוטומטית. מציין ערך מחרוזת שהאפליקציה משתמשת בו כדי לשמור על מצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאה.
`enable_granular_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`enable_serial_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`login_hint`	אופציונלי. אם האפליקציה יודעת איזה משתמש צריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. אם הפעולה מצליחה, המערכת מדלגת על בחירת החשבון. כתובת האימייל או הערך של השדה sub באסימון המזהה של משתמש היעד. מידע נוסף מופיע בשדה `login_hint` במסמכי העזרה בנושא OpenID Connect.
`hd`	אופציונלי. אם האפליקציה יודעת לאיזה דומיין ב-Workspace המשתמש שייך, אפשר להשתמש במידע הזה כדי לספק רמז ל-Google. אם הפעולה מצליחה, חשבונות המשתמשים מוגבלים לדומיין שצוין או נבחרים מראש עבורו. מידע נוסף מופיע בשדה `hd` במסמכי העזרה בנושא OpenID Connect.
`ux_mode`	אופציונלי. מצב חוויית המשתמש שבו צריך להשתמש בתהליך ההרשאה. כברירת מחדל, חלון קופץ ייפתח עם תהליך קבלת ההסכמה. הערכים החוקיים הם `popup` ו-`redirect`.
`select_account`	אופציונלי, ברירת המחדל היא 'false'. ערך בוליאני שגורם להצגת בקשה למשתמש לבחור חשבון.
`error_callback`	אופציונלי. פונקציית JavaScript שמטפלת בחלק מהשגיאות שאינן קשורות ל-OAuth, כמו חלון קופץ שלא נפתח או נסגר לפני שהתקבלה תגובת OAuth. הסיבה המפורטת מופיעה בשדה `type` של פרמטר הקלט. ‫popup_failed_to_open אי אפשר לפתוח את החלון הקופץ. ‫popup_closed החלון הקופץ נסגר לפני שהתשובה של OAuth מוחזרת. ‫unknown (לא ידוע) – placeholder לשגיאות אחרות.

סוג הנתונים: CodeClient

בכיתה יש רק שיטה ציבורית אחת, requestCode, שמתחילה את תהליך חוויית המשתמש של קוד OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

סוג הנתונים: CodeResponse

אובייקט JavaScript‏ CodeResponse יועבר לשיטה callback בחלון הקופץ של ממשק המשתמש. בממשק המשתמש של ההפניה האוטומטית, הערך CodeResponse יועבר כפרמטרים של כתובת URL.

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים CodeResponse.

מאפיינים
`code`	קוד ההרשאה של תשובת טוקן מוצלחת.
`scope`	רשימה של היקפי הרשאות שאושרו על ידי המשתמש, מופרדים ברווחים.
`state`	ערך המחרוזת שהאפליקציה שלכם משתמשת בו כדי לשמור על מצב בין בקשת ההרשאה לתגובה.
`error`	קוד שגיאה יחיד ב-ASCII.
`error_description`	טקסט ASCII שניתן לקריאה על ידי בני אדם, שמספק מידע נוסף, ומשמש כדי לעזור למפתח הלקוח להבין את השגיאה שהתרחשה.
`error_uri`	‫URI שמזהה דף אינטרנט שניתן לקריאה על ידי בני אדם עם מידע על השגיאה, שמשמש כדי לספק למפתח הלקוח מידע נוסף על השגיאה.

שיטה: google.accounts.oauth2.initTokenClient

השיטה initTokenClient מאתחלת ומחזירה לקוח אסימונים, עם ההגדרות בפרמטר.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

סוג הנתונים: TokenClientConfig

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים TokenClientConfig.

מאפיינים
`client_id`	חובה. מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה ב-API Console.
`callback`	חובה. פונקציית JavaScript שמטפלת בתשובה של אסימון שהוחזר.
`scope`	חובה. רשימה של היקפי הרשאות שמופרדים באמצעות רווחים ומזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משמשים להצגת מסך ההסכמה ש-Google מציגה למשתמש.
`include_granted_scopes`	אופציונלי, ברירת המחדל היא `true`. מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפי הרשאות נוספים בהקשר. אם מגדירים את הערך של הפרמטר הזה כ-`false` ובקשת ההרשאה מאושרת, אז אסימון הגישה החדש יכלול רק את ההיקפים ש`scope` ביקש ב-`TokenClientConfig`.
`prompt`	אופציונלי, ברירת המחדל היא 'select_account'. רשימה של הנחיות שמוצגות למשתמש, מופרדות ברווחים ורגישות לאותיות רישיות. הערכים האפשריים הם: empty string המשתמש יתבקש לאשר גישה רק בפעם הראשונה שהאפליקציה תבקש גישה. אי אפשר לציין ערכים אחרים. none: לא מוצגים מסכי אימות או הסכמה. אסור לציין אותו עם ערכים אחרים. 'consent': הצגת בקשת הסכמה למשתמש. select_account: הצגת בקשה למשתמש לבחור חשבון.
`enable_granular_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`enable_serial_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`login_hint`	אופציונלי. אם האפליקציה יודעת איזה משתמש צריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. אם הפעולה מצליחה, המערכת מדלגת על בחירת החשבון. כתובת האימייל או הערך של השדה sub באסימון המזהה של משתמש היעד. מידע נוסף מופיע בשדה `login_hint` במסמכי העזרה בנושא OpenID Connect.
`hd`	אופציונלי. אם האפליקציה יודעת לאיזה דומיין ב-Workspace המשתמש שייך, אפשר להשתמש במידע הזה כדי לספק רמז ל-Google. אם הפעולה מצליחה, חשבונות המשתמשים מוגבלים לדומיין שצוין או נבחרים מראש עבורו. מידע נוסף מופיע בשדה `hd` במסמכי העזרה בנושא OpenID Connect.
`state`	אופציונלי. לא מומלץ. מציין ערך מחרוזת שהאפליקציה משתמשת בו כדי לשמור על מצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאה.
`error_callback`	אופציונלי. פונקציית JavaScript שמטפלת בחלק מהשגיאות שאינן קשורות ל-OAuth, כמו חלון קופץ שלא נפתח או נסגר לפני שהתקבלה תגובת OAuth. הסיבה המפורטת מופיעה בשדה `type` של פרמטר הקלט. ‫popup_failed_to_open אי אפשר לפתוח את החלון הקופץ. ‫popup_closed החלון הקופץ נסגר לפני שהתשובה של OAuth מוחזרת. ‫unknown (לא ידוע) – placeholder לשגיאות אחרות.

סוג הנתונים: TokenClient

למחלקת requestAccessToken יש רק שיטה ציבורית אחת, שמתחילה את תהליך חוויית המשתמש של אסימון OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}

ארגומנטים
`overrideConfig`	OverridableTokenClientConfig	אופציונלי. ההגדרות שרוצים לשנות בשיטה הזו.

סוג הנתונים: OverridableTokenClientConfig

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים OverridableTokenClientConfig.

מאפיינים
`scope`	אופציונלי. רשימה של היקפי הרשאות שמופרדים ברווחים ומזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה מועברים למסך ההסכמה שמוצג למשתמש ב-Google.
`include_granted_scopes`	אופציונלי, ברירת המחדל היא `true`. מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפי הרשאות נוספים בהקשר. אם מגדירים את הערך של הפרמטר הזה כ-`false` ובקשת ההרשאה מאושרת, אז אסימון הגישה החדש יכלול רק את ההיקפים ש`scope` ביקש ב-`OverridableTokenClientConfig`.
`prompt`	אופציונלי. רשימה של הנחיות שמוצגות למשתמש, מופרדות ברווחים ורגישות לאותיות רישיות.
`enable_granular_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`enable_serial_consent`	ההגדרה הזו הוצאה משימוש, ולא משפיעה אם היא מוגדרת. פרטים על התנהגות ההסכמה מפורטים במאמר בנושא הרשאות גרנולריות.
`login_hint`	אופציונלי. אם האפליקציה יודעת איזה משתמש צריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. אם הפעולה מצליחה, המערכת מדלגת על בחירת החשבון. כתובת האימייל או הערך של השדה sub באסימון המזהה של משתמש היעד. מידע נוסף מופיע בשדה `login_hint` במסמכי העזרה בנושא OpenID Connect.
`state`	אופציונלי. לא מומלץ. מציין ערך מחרוזת שהאפליקציה משתמשת בו כדי לשמור על מצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאה.

סוג הנתונים: TokenResponse

אובייקט JavaScript‏ TokenResponse יועבר לפונקציית הקריאה החוזרת (callback) בממשק המשתמש של החלון הקופץ.

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים TokenResponse.

מאפיינים
`access_token`	אסימון הגישה של תגובה מוצלחת של אסימון.
`expires_in`	משך החיים של אסימון הגישה בשניות.
`hd`	הדומיין המארח שהמשתמש המחובר שייך לו.
`prompt`	ערך ההנחיה שנעשה בו שימוש מתוך רשימת הערכים האפשריים שצוינו על ידי TokenClientConfig או OverridableTokenClientConfig.
`token_type`	סוג הטוקן שהונפק.
`scope`	רשימה של היקפי הרשאות שאושרו על ידי המשתמש, מופרדים ברווחים.
`state`	ערך המחרוזת שהאפליקציה שלכם משתמשת בו כדי לשמור על מצב בין בקשת ההרשאה לתגובה.
`error`	קוד שגיאה יחיד ב-ASCII.
`error_description`	טקסט ASCII שניתן לקריאה על ידי בני אדם, שמספק מידע נוסף, ומשמש כדי לעזור למפתח הלקוח להבין את השגיאה שהתרחשה.
`error_uri`	‫URI שמזהה דף אינטרנט שניתן לקריאה על ידי בני אדם עם מידע על השגיאה, שמשמש כדי לספק למפתח הלקוח מידע נוסף על השגיאה.

שיטה: google.accounts.oauth2.hasGrantedAllScopes

בודקת אם המשתמש העניק את כל ההיקפים שצוינו.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;

ארגומנטים
`tokenResponse`	`TokenResponse`	חובה. אובייקט `TokenResponse`.
`firstScope`	מחרוזת	חובה. ההיקף לבדיקה.
`restScopes`	string[]	אופציונלי. היקפים אחרים לבדיקה.

החזרות
בוליאני	הערך True אם כל ההיקפים אושרו.

שיטה: google.accounts.oauth2.hasGrantedAnyScope

הפונקציה בודקת אם המשתמש העניק הרשאה להיקף או להיקפים שצוינו.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;

ארגומנטים
`tokenResponse`	`TokenResponse`	חובה. אובייקט `TokenResponse`.
`firstScope`	מחרוזת	חובה. ההיקף לבדיקה.
`restScopes`	string[]	אופציונלי. היקפים אחרים לבדיקה.

החזרות
בוליאני	הערך True אם אחת מההרשאות ניתנה.

שיטה: google.accounts.oauth2.revoke

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

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;

ארגומנטים
`accessToken`	מחרוזת	חובה. טוקן גישה תקין.
`callback`	פונקציה	אופציונלי. ‫RevocationResponse handler.

סוג הנתונים: RevocationResponse

אובייקט JavaScript‏ RevocationResponse יועבר לשיטת הקריאה החוזרת (callback).

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים RevocationResponse.

מאפיינים
`successful`	בוליאני. `true` הצלחות, `false` כישלונות.
`error`	מחרוזת. לא מוגדר אם הפעולה הצליחה. קוד שגיאה יחיד ב-ASCII. האיסור הזה כולל, בין היתר, את קודי השגיאה הרגילים של OAuth 2.0. שגיאות נפוצות בשיטה `revoke`: ‫`invalid_token` – תוקף הטוקן כבר פג או שהוא בוטל לפני הקריאה לשיטה `revoke`. ברוב המקרים, אפשר להניח שההרשאה שמשויכת ל-`accessToken` בוטלה. ‫`invalid_request` – אי אפשר לבטל את הטוקן. צריך לוודא ש-`accessToken` הם פרטי כניסה תקינים של Google OAuth 2.0.
`error_description`	מחרוזת. לא מוגדר אם הפעולה הצליחה. טקסט ASCII שאנשים יכולים לקרוא מספק מידע נוסף על המאפיין `error`. המפתחים יכולים להשתמש במידע הזה כדי להבין טוב יותר את השגיאה שהתרחשה. המחרוזת `error_description` היא באנגלית בלבד. לשגיאות הנפוצות שמפורטות ב`error` `error_description` המתאים: ‫`invalid_token` – תוקף הטוקן פג או שהטוקן בוטל. ‫`invalid_request` – אי אפשר לבטל את הטוקן.

מסמך עזרה בנושא Google Account Authorization JavaScript API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.