מסמך זה מסביר איך להטמיע הרשאת OAuth 2.0 כדי לגשת ל-YouTube Data API דרך אפליקציות שפועלות במכשירים כמו טלוויזיות, קונסולות משחקים ומדפסות. באופן ספציפי יותר, התהליך הזה מיועד למכשירים שאין להם גישה לדפדפן או שיש להם יכולות קלט מוגבלות.
OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה, תוך שמירה על הפרטיות של שמות המשתמשים, הסיסמאות ומידע אחר שלהם. לדוגמה, אפליקציה לטלוויזיה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה לבחור קובץ המאוחסן ב-Google Drive.
מכיוון שהאפליקציות שמשתמשות בתהליך הזה מופצות למכשירים ספציפיים, ההנחה היא שהאפליקציות לא יכולות לשמור סודות. הם יכולים לגשת ל-Google APIs בזמן שהמשתמש נמצא באפליקציה או כשהאפליקציה פועלת ברקע.
חלופות
אם אתם כותבים אפליקציה לפלטפורמה כמו Android, iOS, macOS, Linux או Windows (כולל פלטפורמת Universal Windows), שיש לה גישה לדפדפן וליכולות קלט מלאות, תוכלו להשתמש בתהליך של OAuth 2.0 לאפליקציות לנייד ולמחשב. (צריך להשתמש בתהליך מהסוג הזה גם אם האפליקציה היא כלי שורת פקודה ללא ממשק גרפי).
אם אתם רק רוצים להיכנס למשתמשים באמצעות חשבונות Google שלהם ולהשתמש באסימון המזהה JWT כדי לקבל מידע בסיסי על פרופיל המשתמש, כדאי לעיין במאמר כניסה בטלוויזיות ובמכשירי קלט מוגבלים.
דרישות מוקדמות
הפעלת ממשקי API לפרויקט
כל אפליקציה ששולחת קריאה ל-Google APIs צריכה להפעיל את ממשקי ה-API האלה ב- API Console.
כדי להפעיל API לפרויקט:
- Open the API Library ב Google API Console.
- If prompted, select a project, or create a new one.
- בדף ספרייה אפשר למצוא את ממשק YouTube Data API ולהפעיל אותו. צריך לחפש ממשקי API אחרים שהאפליקציה תשתמש בהם ולהפעיל גם אותם.
יצירת פרטי כניסה להרשאה
כל אפליקציה שמשתמשת ב-OAuth 2.0 כדי לגשת ל-Google APIs צריכה להיות עם פרטי כניסה להרשאה שמזהים את האפליקציה לשרת OAuth 2.0 של Google. בשלבים הבאים מוסבר איך ליצור את פרטי הכניסה לפרויקט. לאחר מכן האפליקציות יכולות להשתמש בפרטי הכניסה כדי לגשת לממשקי ה-API שהפעלתם בפרויקט הזה.
- Go to the Credentials page.
- לוחצים על Create credentials > מזהה לקוח OAuth.
- בוחרים בסוג האפליקציה טלוויזיות ומכשירי קלט מוגבלים.
- נותנים שם ללקוח OAuth 2.0 ולוחצים על יצירה.
זיהוי של היקפי גישה
היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. לכן, יכול להיות קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבל הסכמה מהמשתמשים.
לפני שמתחילים להטמיע הרשאה מסוג OAuth 2.0, מומלץ לזהות את היקפי ההרשאות שהאפליקציה צריכה הרשאה כדי לגשת אליהן.
ממשק YouTube Data API v3 משתמש בהיקפים הבאים:
| טווחים | |
|---|---|
| https://www.googleapis.com/auth/youtube | ניהול חשבון YouTube שלך |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | הצגת רשימה מעודכנת של החברים הפעילים במועדון החברים של הערוץ, הרמה הנוכחית שלהם והתאריך שבו הם הצטרפו למועדון |
| https://www.googleapis.com/auth/youtube.force-ssl | הצגה, עריכה ומחיקה לצמיתות של סרטונים, דירוגים, תגובות וכתוביות ב-YouTube |
| https://www.googleapis.com/auth/youtube.readonly | הצגת חשבון YouTube שלך |
| https://www.googleapis.com/auth/youtube.upload | ניהול הסרטונים שלך ב-YouTube |
| https://www.googleapis.com/auth/youtubepartner | הצגה וניהול של הנכסים והתכנים הקשורים שלך ב-YouTube |
| https://www.googleapis.com/auth/youtubepartner-channel-audit | הצגת מידע פרטי של ערוץ YouTube שלך הרלוונטי בתהליך הביקורת של שותף YouTube. |
לרשימת היקפי ההרשאות המותרים של אפליקציות או מכשירים מותקנים.
קבלת אסימוני גישה מסוג OAuth 2.0
האפליקציה פועלת במכשיר עם יכולות קלט מוגבלות, אבל כדי להשלים את תהליך ההרשאה נדרשת גישה נפרדת למכשיר עם יכולות קלט עשירות יותר. התהליך כולל את השלבים הבאים:
- האפליקציה שולחת בקשה לשרת ההרשאות של Google שמזהה את היקפי ההרשאות שהאפליקציה תבקש הרשאת גישה אליהם.
- השרת מגיב עם כמה פרטים שמשמשים בשלבים הבאים, כמו קוד המכשיר וקוד המשתמש.
- מוצג מידע שהמשתמש יכול להזין במכשיר נפרד כדי לתת הרשאה לאפליקציה.
- האפליקציה מתחילה לדגום את שרת ההרשאות של Google כדי לקבוע אם המשתמש אישר את האפליקציה.
- המשתמש עובר למכשיר שיש בו יכולות קלט עשירות יותר, מפעיל דפדפן אינטרנט, מנווט לכתובת ה-URL המוצגת בשלב 3 ומזין קוד שמוצג גם הוא בשלב 3. לאחר מכן המשתמש יכול להעניק (או לדחות) גישה לאפליקציה.
- התשובה הבאה לבקשת הסקר תכלול את האסימונים שהאפליקציה צריכה כדי לאשר בקשות בשם המשתמש. (אם המשתמש סירב לגישה לאפליקציה שלך, התגובה לא תכיל אסימונים).
התמונה הבאה ממחישה את התהליך הזה:
השלבים האלה מוסברים בפירוט בקטעים הבאים. בגלל מגוון היכולות וסביבות זמן הריצה שיש במכשירים, הדוגמאות שמוצגות במסמך עושות שימוש בכלי שורת הפקודה curl. את הדוגמאות האלה צריך לאפשר לנייד בקלות לשפות שונות ולסביבות זמן ריצה שונות.
שלב 1: מבקשים קודים של מכשירים ומשתמשים
בשלב הזה, המכשיר שולח בקשת HTTP POST לשרת ההרשאות של Google, ב-https://oauth2.googleapis.com/device/code, שמזהה את האפליקציה שלכם וכן את היקפי הגישה שהאפליקציה רוצה לגשת אליהם בשם המשתמש.
צריך לאחזר את כתובת ה-URL הזו
ממסמך Discovery באמצעות
ערך המטא-נתונים device_authorization_endpoint. צריך לכלול את הפרמטרים הבאים של בקשת HTTP:
| פרמטרים | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
חובה
מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה ב- API Console Credentials page. |
||||||||||||||||
scope |
חובה
רשימה מופרדת ברווחים של היקפים שמזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משפיעים על מסך ההסכמה ש-Google מציגה למשתמש. לרשימת היקפי ההרשאות המותרים של אפליקציות או מכשירים מותקנים היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. לכן, יש קשר הפוך בין מספר היקפי ההרשאות שנדרשים לבין הסבירות לקבלת הסכמה מהמשתמשים. ממשק YouTube Data API v3 משתמש בהיקפים הבאים:
המסמך היקפי API של OAuth 2.0 כולל רשימה מלאה של היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs. |
||||||||||||||||
דוגמאות
קטע הקוד הבא מציג בקשה לדוגמה:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly
בדוגמה הזו מוצגת פקודת curl לשליחת אותה בקשה:
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
https://oauth2.googleapis.com/device/code
שלב 2: טיפול בתגובה של שרת ההרשאות
שרת ההרשאות יחזיר אחת מהתגובות הבאות:
תגובה מוצלחת
אם הבקשה תקינה, התגובה תהיה אובייקט JSON שמכיל את המאפיינים הבאים:
| תכונות | |
|---|---|
device_code |
ערך ש-Google מקצה באופן ייחודי כדי לזהות את המכשיר שמפעיל את האפליקציה שמבקשת
הרשאה. המשתמש יאשר את ההרשאה במכשיר אחר עם יכולות קלט עשירות יותר. לדוגמה, משתמש עשוי להשתמש במחשב נייד או בטלפון נייד כדי לתת הרשאה
לאפליקציה שפועלת בטלוויזיה. במקרה הזה, device_code מזהה את הטלוויזיה.
הקוד הזה מאפשר למכשיר שמפעיל את האפליקציה באופן מאובטח אם המשתמש העניק או דחה גישה. |
expires_in |
משך הזמן בשניות שה-device_code וה-user_code תקפים. אם המשתמש לא ישלים את
תהליך ההרשאה והמכשיר לא מבצע סקר כדי לאחזר מידע על
ההחלטה של המשתמש, ייתכן שיהיה עליך להתחיל מחדש את התהליך משלב 1. |
interval |
משך הזמן (בשניות) שהמכשיר צריך להמתין בין הבקשות לסקרים. לדוגמה, אם הערך הוא 5, המכשיר צריך לשלוח בקשת סקרים לשרת האימות של Google כל 5 שניות. לפרטים נוספים, ראו
שלב 3. |
user_code |
ערך תלוי אותיות רישיות שמזהה ל-Google את היקפי ההרשאות שהאפליקציה מבקשת גישה אליהם. ממשק המשתמש ינחה את המשתמש להזין את הערך הזה במכשיר נפרד עם יכולות קלט עשירות יותר. לאחר מכן, Google משתמשת בערך כדי להציג את הקבוצה הנכונה של היקפים כשמבקשים מהמשתמש להעניק גישה לאפליקציה. |
verification_url |
כתובת URL שהמשתמש צריך לעבור אליה, במכשיר נפרד, כדי להיכנס
אל user_code ולהעניק גישה לאפליקציה או לדחות אותה. הערך הזה יוצג גם בממשק המשתמש. |
בקטע הקוד הבא מוצגת תגובה לדוגמה:
{
"device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code": "GQVQ-JKEC",
"verification_url": "https://www.google.com/device",
"expires_in": 1800,
"interval": 5
}
תגובה לחריגה מהמכסה
אם הבקשות לקוד מכשיר יחרגו מהמכסה שמשויכת למזהה הלקוח שלכם, תקבלו תגובת 403 עם השגיאה הבאה:
{
"error_code": "rate_limit_exceeded"
}
במקרה כזה, כדאי להשתמש באסטרטגיית השהיה לפני ניסיון חוזר כדי להפחית את שיעור הבקשות.
שלב 3: הצגת קוד המשתמש
מציגים למשתמש את ה-verification_url וה-user_code שהתקבלו בשלב 2. שני הערכים יכולים להכיל כל תו שניתן להדפסה מתוך מערכת התווים US-ASCII. התוכן
שמוצג למשתמש צריך להנחות אותו לנווט אל
verification_url במכשיר נפרד ולהזין את user_code.
חשוב להביא בחשבון את הכללים הבאים כשמתכננים את ממשק המשתמש:
user_code- חובה להציג את השדה
user_codeבשדה שיכול להכיל עד 15 תווים בגודל 'W'. כלומר, אם אפשר להציג את הקודWWWWWWWWWWWWWWWבצורה נכונה, ממשק המשתמש תקין ואנחנו ממליצים להשתמש בערך המחרוזת הזה כדי לבדוק את האופן שבוuser_codeמוצג בממשק המשתמש. - השדה
user_codeהוא תלוי אותיות רישיות ולא צריך לשנות אותו בשום צורה, כמו שינוי אותיות רישיות או הוספת תווים אחרים בפורמט.
- חובה להציג את השדה
verification_url- הרווח שבו מציגים את השדה
verification_urlחייב להיות רחב מספיק כדי לטפל במחרוזת של כתובת URL באורך של 40 תווים. - אין לשנות את
verification_urlבכל דרך שהיא, מלבד הסרה של סכימת התצוגה. אם בכוונתך להסיר את הסכמה (למשלhttps://) מכתובת ה-URL מטעמי תצוגה, חשוב לוודא שהאפליקציה שלך יכולה לטפל גם בווריאנטים שלhttpוגם בוריאנטים שלhttps.
- הרווח שבו מציגים את השדה
שלב 4: סקרו את שרת ההרשאות של Google
המשתמש ישתמש במכשיר נפרד כדי לעבור אל verification_url
וכדי להעניק גישה (או לדחות אותה), לכן לא תישלח התראה אוטומטית למכשיר ששלח את הבקשה כשהמשתמש
מגיב לבקשת הגישה. לכן, המכשיר ששולח את הבקשה צריך לבצע דגימה של שרת ההרשאות של Google
כדי לקבוע מתי המשתמש הגיב לבקשה.
המכשיר ששולח את הבקשה אמור להמשיך לשלוח בקשות לסקרים עד לקבלת תשובה,
שמציינת שהמשתמש הגיב לבקשת הגישה או עד שיפוג התוקף של device_code ו-user_code שהתקבלו ב
שלב 2. הערך של interval שמוחזר בשלב 2 מציין את
משך הזמן בשניות שצריך להמתין בין הבקשות.
כתובת ה-URL של נקודת הקצה של הסקר היא https://oauth2.googleapis.com/token. בקשת הסקר
כוללת את הפרמטרים הבאים:
| פרמטרים | |
|---|---|
client_id |
מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה ב- API Console Credentials page. |
client_secret |
סוד הלקוח של client_id שסיפקתם. אפשר למצוא את הערך הזה ב- API Console
Credentials page. |
device_code |
השדה device_code שהוחזר על ידי שרת ההרשאות
בשלב 2. |
grant_type |
צריך להגדיר את הערך הזה כ-urn:ietf:params:oauth:grant-type:device_code. |
דוגמאות
קטע הקוד הבא מציג בקשה לדוגמה:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
בדוגמה הזו מוצגת פקודת curl לשליחת אותה בקשה:
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/token
שלב 5: המשתמש מגיב לבקשת גישה
בתמונה הבאה מוצג דף שדומה לדף שהמשתמשים רואים כשהם עוברים אל
verification_url שהוצג בשלב 3:
אחרי הזנת הקוד user_code, והתחברות ל-Google, אם המשתמש לא מחובר כבר לחשבון,
המשתמש יראה מסך הסכמה כמו זה שמוצג כאן:
שלב 6: טיפול בתשובות לבקשות לסקרים
שרת ההרשאות של Google מגיב לכל בקשת סקרים באחת מהתגובות הבאות:
קיבלת גישה
אם המשתמש העניק גישה למכשיר (בלחיצה על Allow במסך ההסכמה),
התגובה תכיל אסימון גישה ואסימון רענון. האסימונים מאפשרים למכשיר
לגשת ל-Google APIs בשם המשתמש. (המאפיין scope בתגובה קובע לאילו ממשקי API המכשיר יוכל לגשת).
במקרה כזה, תגובת ה-API תכיל את השדות הבאים:
| שדות | |
|---|---|
access_token |
האסימון שהאפליקציה שלכם שולחת כדי לאשר בקשת Google API. |
expires_in |
משך החיים שנותר לאסימון הגישה, בשניות. |
refresh_token |
אסימון שאפשר להשתמש בו כדי לקבל אסימון גישה חדש. אסימוני הרענון תקפים עד שהמשתמש מבטל את הגישה. חשוב לזכור שאסימוני רענון תמיד מוחזרים למכשירים. |
scope |
היקפי הגישה שהוענקו על ידי access_token, מוצגים כרשימה של מחרוזות תלויות-רישיות שמופרדות ברווחים. |
token_type |
סוג האסימון המוחזר. בשלב הזה, הערך בשדה הזה תמיד מוגדר כ-Bearer. |
בקטע הקוד הבא מוצגת תגובה לדוגמה:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
"token_type": "Bearer",
"refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
לאסימוני גישה יש משך חיים מוגבל. אם האפליקציה צריכה גישה ל-API לאורך זמן רב, היא יכולה להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש. אם האפליקציה צריכה גישה מהסוג הזה, היא צריכה לאחסן את אסימון הרענון לשימוש מאוחר יותר.
הגישה נדחתה
אם המשתמש מסרב להעניק גישה למכשיר, לתגובת השרת יהיה קוד סטטוס תגובת HTTP 403 (Forbidden). התגובה תכיל את השגיאה הבאה:
{
"error": "access_denied",
"error_description": "Forbidden"
}
בהמתנה להרשאה
אם המשתמש עדיין לא השלים את תהליך ההרשאה, השרת מחזיר קוד הסטטוס 428 של תשובת HTTP (Precondition Required). התגובה תכיל את השגיאה הבאה:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
עריכת סקרים בתדירות גבוהה מדי
אם המכשיר שולח בקשות דגימה בתדירות גבוהה מדי, השרת יחזיר 403
קוד סטטוס של תשובת HTTP (Forbidden). התשובה תכיל את השגיאה הבאה:
{
"error": "slow_down",
"error_description": "Forbidden"
}
שגיאות אחרות
שרת ההרשאות מחזיר שגיאות גם אם בבקשת הדגימה חסרים פרמטרים כלשהם או אם היא מכילה ערך פרמטר שגוי. בדרך כלל, הבקשות האלה מכילות קוד סטטוס של תגובת HTTP 400 (Bad Request) או 401 (Unauthorized). דוגמאות לשגיאות כאלה:
| שגיאה | קוד מצב HTTP | תיאור |
|---|---|---|
admin_policy_enforced |
400 |
בהתאם למדיניות של האדמין ב-Google Workspace, אין אפשרות לתת הרשאה להיקף הרשאות אחד או יותר בחשבון Google. במאמר העזרה לאדמינים ב-Google Workspace מוסבר איך לקבוע לאילו אפליקציות של צד שלישי ואפליקציות פנימיות תהיה גישה לנתונים של Google Workspace, כדי להבין איך האדמין יכול להגביל את הגישה להיקפים עד שתוענק גישה מפורשת למזהה הלקוח שלכם ב-OAuth. |
invalid_client |
401 |
לקוח OAuth לא נמצא. לדוגמה, השגיאה הזו מתקבלת אם
ערך הפרמטר הסוג של לקוח OAuth שגוי. חשוב לוודא שסוג האפליקציה עבור מזהה הלקוח מוגדר לטלוויזיות ומכשירי קלט מוגבלים. |
invalid_grant |
400 |
ערך הפרמטר code לא תקין, כבר נתבעה עליו בעלות או שאי אפשר לנתח אותו. |
unsupported_grant_type |
400 |
ערך הפרמטר grant_type לא תקין. |
org_internal |
403 |
מזהה הלקוח ב-OAuth שצוין בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google ב ארגון ספציפי ב-Google Cloud. בודקים את ההגדרה של סוג המשתמש באפליקציית OAuth. |
קריאה ל-Google APIs
אחרי שהאפליקציה מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם
חשבון משתמש נתון, אם הוענקו היקפי הגישה שנדרשים על ידי ה-API. כדי לעשות את זה צריך לכלול את אסימון הגישה בבקשה ל-API, על ידי הכללת פרמטר של שאילתה access_token או ערך Bearer של כותרת ה-HTTP של Authorization. כשזה אפשרי, עדיף להשתמש בכותרת ה-HTTP כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (למשל, כששולחים קריאה ל-YouTube Data API).
שימו לב ש-YouTube Data API תומך בחשבונות שירות רק לבעלי תוכן ב-YouTube, שבבעלותם ובניהולם של מספר ערוצי YouTube, כמו לייבלים ואולפני סרטים.
תוכלו לנסות את כל ממשקי ה-API של Google ולצפות בהיקפים שלהם ב-OAuth 2.0 Playground.
דוגמאות ל-HTTP GET
קריאה לנקודת הקצה (
youtube.channels) (YouTube Data API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך. שימו לב שתצטרכו לציין אסימון גישה משלכם:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
זוהי קריאה לאותו API בשביל המשתמש המאומת באמצעות הפרמטר access_token של מחרוזת השאילתה:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
curl דוגמאות
אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה שמשתמשת באפשרות של כותרת ה-HTTP (האפשרות המועדפת):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
רענון של אסימון גישה
התוקף של אסימוני הגישה פג מדי פעם והם הופכים לפרטי כניסה לא חוקיים לבקשת API קשורה. אם ביקשת גישה אופליין להיקפי ההרשאות שמשויכים לאסימון, אפשר לרענן אסימון גישה בלי לבקש הרשאה מהמשתמש (גם כשהמשתמש לא נמצא).
כדי לרענן אסימון גישה, האפליקציה שולחת בקשת POST מסוג HTTPS לשרת ההרשאות של Google (https://oauth2.googleapis.com/token) שכוללת את הפרמטרים הבאים:
| שדות | |
|---|---|
client_id |
מזהה הלקוח שהתקבל מ- API Console. |
client_secret |
סוד הלקוח שהתקבל מ- API Console. |
grant_type |
כפי שמוגדר במפרט של OAuth 2.0, הערך בשדה הזה צריך להיות refresh_token. |
refresh_token |
אסימון הרענון שהוחזר מהמרת קוד ההרשאה. |
קטע הקוד הבא מציג בקשה לדוגמה:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
כל עוד המשתמש לא ביטל את הגישה שהוענקה לאפליקציה, שרת האסימונים מחזיר אובייקט JSON שמכיל אסימון גישה חדש. בקטע הקוד הבא מוצגת תגובה לדוגמה:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"token_type": "Bearer"
}
חשוב לשים לב שיש הגבלות על מספר אסימוני הרענון שיונפקו – מגבלה אחת לכל שילוב של לקוח/משתמש ומגבלה נוספת לכל משתמש בכל הלקוחות. צריך לשמור אסימוני רענון באחסון לטווח ארוך ולהמשיך להשתמש בהם כל עוד הם בתוקף. אם האפליקציה מבקשת יותר מדי אסימוני רענון, היא עלולה להגיע למגבלות האלה, ובמקרה כזה אסימוני רענון ישנים יותר יפסיקו לפעול.
ביטול אסימון
במקרים מסוימים משתמש עשוי לבטל את הגישה שניתנה לאפליקציה. המשתמש יכול לבטל את הגישה דרך הגדרות החשבון. למידע נוסף, אפשר לעיין בקטע התמיכה לגבי הסרת הגישה של אתר או אפליקציה מאתרים ואפליקציות של צד שלישי שיש להם גישה לחשבון.
אפשר גם שאפליקציה יכולה לבטל באופן פרוגרמטי את הגישה שהוענקה לה. ביטול פרוגרמטי חשוב במקרים שבהם משתמש מבטל את ההרשמה או מסיר אפליקציה, או שחל שינוי משמעותי במשאבי ה-API שנדרשים על ידי האפליקציה. כלומר, חלק מתהליך ההסרה יכול לכלול בקשת API, כדי להבטיח שההרשאות שניתנו בעבר לאפליקציה יוסרו.
כדי לבטל אסימון באופן פרוגרמטי, האפליקציה שולחת בקשה ל-https://oauth2.googleapis.com/revoke וכוללת את האסימון כפרמטר:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון רענון תואם, גם אסימון הרענון יבוטל.
אם הביטול יעובד, קוד סטטוס ה-HTTP של התשובה הוא 200. במקרים של שגיאות, מוחזר קוד הסטטוס 400 של HTTP יחד עם קוד השגיאה.
היקפי הרשאות מותרים
תהליך OAuth 2.0 למכשירים נתמך רק בהיקפים הבאים:
OpenID Connect, כניסה באמצעות Google
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
ממשק API של YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly