OAuth 2.0 לאפליקציות במכשירי טלוויזיה ומכשירים עם קלט מוגבל

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

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

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

חלופות

אם אתם כותבים אפליקציה לפלטפורמה כמו Android,‏ iOS,‏ macOS,‏ Linux או Windows (כולל Universal Windows Platform), שיש לה גישה לדפדפן וליכולות קלט מלאות, השתמשו בתהליך OAuth 2.0 לאפליקציות לנייד ולמחשב. (צריך להשתמש בתהליך הזה גם אם האפליקציה היא כלי בשורת הפקודה ללא ממשק גרפי).

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

דרישות מוקדמות

הפעלת ממשקי API בפרויקט

כל אפליקציה שמבצעת קריאה ל-Google APIs צריכה להפעיל את ממשקי ה-API האלה ב- .

כדי להפעיל ממשק API בפרויקט:

  1. ב .
  2. בדף Library (ספרייה) אפשר למצוא את YouTube Data API ולהפעיל אותו. מוצאים ממשקי API אחרים שבהם האפליקציה תשתמש ומפעילים אותם גם כן.

יצירת פרטי כניסה להרשאה

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

  1. לוחצים על Create credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  2. בוחרים את סוג האפליקציה טלוויזיות והתקני קלט עם הגבלות.
  3. נותנים שם ללקוח OAuth 2.0 ולוחצים על Create.

זיהוי היקפי הגישה

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

לפני שמתחילים להטמיע הרשאה מסוג OAuth 2.0, מומלץ לזהות את היקפי ההרשאות שאליהם האפליקציה תצטרך גישה.

ב-YouTube Data API גרסה 3 נעשה שימוש בהיקפי הגישה הבאים:

טווחים
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

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

  1. האפליקציה שולחת בקשה לשרת ההרשאות של Google, שמזהה את ההיקפים של הגישה שהאפליקציה תבקש.
  2. השרת משיב עם כמה פריטים של מידע שיהיו בשימוש בשלבים הבאים, כמו קוד מכשיר וקוד משתמש.
  3. אתם מציגים מידע שהמשתמש יכול להזין במכשיר נפרד כדי לאשר את האפליקציה.
  4. האפליקציה מתחילה לבצע סקרים לשרת ההרשאות של Google כדי לקבוע אם המשתמש העניק לאפליקציה הרשאה.
  5. המשתמש עובר למכשיר עם יכולות קלט מתקדמות יותר, מפעיל דפדפן אינטרנט, עובר לכתובת ה-URL שמוצגת בשלב 3 ומזין קוד שמוצג גם בשלב 3. לאחר מכן, המשתמש יוכל להעניק (או לדחות) גישה לאפליקציה.
  6. התשובה הבאה לבקשת הסקרים מכילה את האסימונים שהאפליקציה צריכה כדי לאשר בקשות בשם המשתמש. (אם המשתמש דחה את הגישה לאפליקציה, התגובה לא מכילה אסימונים).

התמונה הבאה ממחישה את התהליך:

המשתמש נכנס לחשבון במכשיר נפרד שיש בו דפדפן

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

שלב 1: מבקשים קודי מכשיר ומשתמש

בשלב הזה, המכשיר שולח בקשת HTTP POST לשרת ההרשאות של Google, בכתובת https://oauth2.googleapis.com/device/code, שמזהה את האפליקציה ואת היקפי הגישה שהאפליקציה רוצה לגשת אליהם בשם המשתמש. צריך לאחזר את כתובת ה-URL הזו ממסמך Discovery באמצעות ערך המטא-נתונים device_authorization_endpoint. צריך לכלול את הפרמטרים הבאים של בקשת ה-HTTP:

פרמטרים
client_id חובה

מזהה הלקוח של האפליקציה. הערך הזה מופיע ב- .

scope חובה

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

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

ב-YouTube Data API גרסה 3 נעשה שימוש בהיקפי הגישה הבאים:

טווחים
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.

במסמך היקפי 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.force-ssl

בדוגמה הזו מוצגת פקודה curl לשליחת אותה בקשה:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

שלב 2: טיפול בתגובה של שרת ההרשאות

שרת ההרשאות יחזיר אחת מהתגובות הבאות:

תגובת הצלחה

אם הבקשה תקינה, התגובה תהיה אובייקט JSON שכולל את המאפיינים הבאים:

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

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

expires_in משך הזמן, בשניות, שבו device_code ו-user_code תקפים. אם במהלך פרק הזמן הזה המשתמש לא משלים את תהליך ההרשאה והמכשיר לא מבצע גם סקירה כדי לאחזר מידע על ההחלטה של המשתמש, יכול להיות שתצטרכו להתחיל מחדש את התהליך הזה משלב 1.
interval משך הזמן, בשניות, שהמכשיר צריך להמתין בין בקשות הסקרים. לדוגמה, אם הערך הוא 5, המכשיר צריך לשלוח בקשת סקרים לשרת ההרשאות של Google כל חמש שניות. פרטים נוספים זמינים בשלב 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.

כשאתם מעצבים את ממשק המשתמש (UI), חשוב לזכור את הכללים הבאים:

  • 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 מזהה הלקוח של האפליקציה. הערך הזה מופיע ב- .
client_secret סוד הלקוח של client_id שצוין. הערך הזה מופיע ב- .
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 API מטעם המשתמש. (הנכס 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 למשך זמן רב, תוכלו להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש. אם לאפליקציה שלכם נדרשת גישה מהסוג הזה, עליכם לאחסן את אסימון הרענון לשימוש מאוחר יותר.

הגישה נדחתה

אם המשתמש מסרב להעניק גישה למכשיר, תגובה מהשרת תכלול את קוד סטטוס התגובה 403 של HTTP (Forbidden). התגובה תכלול את השגיאה הבאה:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

ההרשאה בהמתנה

אם המשתמש עדיין לא השלים את תהליך ההרשאה, השרת מחזיר קוד סטטוס תגובה של HTTP‏ 428 (Precondition Required). התגובה מכילה את השגיאה הבאה:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

ביצוע סקרים בתדירות גבוהה מדי

אם המכשיר שולח בקשות סקרים בתדירות גבוהה מדי, השרת מחזיר קוד סטטוס תגובה של HTTP‏ 403 (Forbidden). התגובה מכילה את השגיאה הבאה:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

שגיאות אחרות

שרת ההרשאה גם מחזיר שגיאות אם בבקשת הסקרים חסרים פרמטרים נדרשים או אם ערך הפרמטר שגוי. בדרך כלל, לבקשות האלה יש קוד מצב תגובה של HTTP‏ 400 (Bad Request) או 401 (Unauthorized). השגיאות האלה כוללות:

שגיאה קוד מצב HTTP תיאור
admin_policy_enforced 400 חשבון Google לא יכול להעניק הרשאה להיקף אחד או יותר שנדרשו בגלל המדיניות של האדמין ב-Google Workspace. במאמר העזרה לאדמינים ב-Google Workspace שליטה בגישה של אפליקציות של צד שלישי ואפליקציות פנימיות לנתונים ב-Google Workspace מוסבר איך אדמין יכול להגביל את הגישה להיקפי הרשאות עד שהגישה תוענק במפורש למזהה הלקוח של OAuth.
invalid_client 401

לקוח OAuth לא נמצא. לדוגמה, השגיאה הזו מתרחשת אם ערך הפרמטר client_id לא תקין.

סוג הלקוח ב-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 בכותרת Authorization של HTTP. כשהדבר אפשרי, עדיף להשתמש בכותרת ה-HTTP, כי מחרוזות השאילתות נוטים להיות גלויות ביומנים של השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות לממשקי Google API (לדוגמה, כשקוראים ל-YouTube Live Streaming API).

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

אפשר לנסות את כל ממשקי Google APIs ולראות את היקפי ההרשאות שלהם ב-OAuth 2.0 Playground.

דוגמאות לבקשות HTTP GET

קריאה לנקודת הקצה liveBroadcasts.list (YouTube Live Streaming API) באמצעות הכותרת Authorization: Bearer של HTTP עשויה להיראות כך: חשוב לשים לב שצריך לציין את טוקן הגישה שלכם:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

זוהי קריאה לאותו ממשק API עבור המשתמש המאומת באמצעות הפרמטר access_token של מחרוזת השאילתה:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl דוגמאות

אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה שמשתמשת באפשרות של כותרת ה-HTTP (האפשרות המועדפת):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

לחלופין, אפשר לבחור באפשרות 'פרמטר של מחרוזת שאילתה':

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

רענון של אסימון גישה

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

כדי לרענן אסימון גישה, האפליקציה שולחת בקשת POST ב-HTTPS לשרת ההרשאות של Google‏ (https://oauth2.googleapis.com/token) שכוללת את הפרמטרים הבאים:

שדות
client_id מזהה הלקוח שהתקבל מ- .
client_secret סוד הלקוח שהתקבל מ- .
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 https://www.googleapis.com/auth/calendar.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. בתנאים של שגיאה, קוד הסטטוס HTTP 400 מוחזר יחד עם קוד שגיאה.

היקפים מותרים

התהליך של OAuth 2.0 למכשירים נתמך רק בהיקפים הבאים:

OpenID Connect,‏ כניסה באמצעות חשבון Google

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

הטמעת ההגנה על כל החשבונות

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

דוגמאות לסוגי האירועים שנשלחים לאפליקציה שלכם על ידי שירות ההגנה על חשבונות שונים של Google:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

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