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

ספריית JavaScript לאימות על ידי צד שלישי של Google לאתרים – הפניית API

במסמך העזרה הזה מוסבר על Google 3P Authorization JavaScript Library API, שבעזרתו אפשר לטעון קודי הרשאה או אסימוני גישה מ-Google.

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

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

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

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

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

מאפיינים
`client_id`	חובה. מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה במסוף ה-API.
`scope`	חובה. רשימה של היקפי הרשאות שמפרידה אותם באמצעות רווחים, ומזהה את המשאבים שהאפליקציה יכולה לגשת אליהם מטעם המשתמש. הערכים האלה מופיעים במסך ההסכמה ש-Google מציגה למשתמש.
`include_granted_scopes`	אופציונלי, ברירת המחדל היא `true`. מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפי גישה נוספים בהקשר. אם מגדירים את הערך של הפרמטר הזה כ-`false` ובקשת ההרשאה מאושרת, אסימון הגישה החדש יכסה רק את ההיקפים שבהם `scope` ביקש ב-`CodeClientConfig` הזה.
`redirect_uri`	חובה לממשק המשתמש של ההפניה האוטומטית. קובע לאן שרת ה-API מפנה את המשתמש אחרי שהמשתמש משלים את תהליך ההרשאה. הערך חייב להתאים בדיוק לאחד מ-URI של ההפניה האוטומטית המורשים של לקוח OAuth 2.0, שהגדרתם במסוף ה-API, ועליו לעמוד בכללי האימות של 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 for other errors.

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

לכיתה יש רק שיטה ציבורית אחת, requestCode, שמפעילה את תהליך ה-UX של קוד 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.
`callback`	חובה. פונקציית JavaScript שמטפלת בתשובה עם האסימון המוחזר.
`scope`	חובה. רשימה של היקפי הרשאות שמפרידה אותם באמצעות רווחים, ומזהה את המשאבים שהאפליקציה יכולה לגשת אליהם מטעם המשתמש. הערכים האלה מופיעים במסך ההסכמה ש-Google מציגה למשתמש.
`include_granted_scopes`	אופציונלי, ברירת המחדל היא `true`. מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפי גישה נוספים בהקשר. אם מגדירים את הערך של הפרמטר הזה כ-`false` ובקשת ההרשאה מאושרת, אסימון הגישה החדש יכסה רק את ההיקפים שבהם `scope` ביקש ב-`TokenClientConfig` הזה.
`prompt`	אופציונלי, ברירת המחדל היא 'select_account'. רשימה של הנחיות להצגה למשתמש, מופרדות באמצעות רווחים ורגישות לשימוש באותיות רישיות. הערכים האפשריים הם: מחרוזת ריקה המשתמש יקבל הודעה רק בפעם הראשונה שהאפליקציה תבקש גישה. לא ניתן לציין ערכים אחרים. '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 for other errors.

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

לכיתה יש רק שיטה ציבורית אחת, requestAccessToken, שמפעילה את תהליך ה-UX של אסימון 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

ה-method‏ revoke מבטל את כל ההיקפים שהמשתמש העניק לאפליקציה. כדי לבטל את ההרשאה נדרש טוקן גישה תקף.

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

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

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

אובייקט JavaScript מסוג RevocationResponse יועבר לשיטת הקריאה החוזרת.

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים 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` – אי אפשר לבטל את הטוקן.