OAuth 2.0 สำหรับแอปพลิเคชันทีวีและอุปกรณ์อินพุตที่จำกัด

เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง YouTube Data API ผ่านแอปพลิเคชันที่ทำงานบนอุปกรณ์ต่างๆ เช่น ทีวี คอนโซลเกม และ เครื่องพิมพ์ กล่าวโดยละเอียดคือโฟลว์นี้ออกแบบมาสำหรับอุปกรณ์ที่ไม่มีสิทธิ์เข้าถึงเบราว์เซอร์หรือมีความสามารถในการป้อนข้อมูลแบบจำกัด

OAuth 2.0 อนุญาตให้ผู้ใช้แชร์ข้อมูลบางอย่างกับแอปพลิเคชันโดยที่ยังเก็บชื่อผู้ใช้ รหัสผ่าน และข้อมูลอื่นๆ ไว้เป็นส่วนตัว เช่น แอปพลิเคชันทีวีอาจใช้ OAuth 2.0 เพื่อขอรับสิทธิ์ในการ เลือกไฟล์ที่จัดเก็บไว้ใน Google ไดรฟ์

เนื่องจากแอปพลิเคชันที่ใช้โฟลว์นี้จะกระจายไปยังอุปกรณ์แต่ละเครื่อง จึงถือว่าแอปไม่สามารถเก็บข้อมูลลับได้ โดยจะเข้าถึง Google API ได้ในขณะที่ผู้ใช้ อยู่ในแอปหรือเมื่อแอปทำงานอยู่เบื้องหลัง

ทางเลือก

หากคุณกำลังเขียนแอปสำหรับแพลตฟอร์ม เช่น Android, iOS, macOS, Linux หรือ Windows (รวมถึง Universal Windows Platform) ซึ่งมีสิทธิ์เข้าถึงเบราว์เซอร์และความสามารถในการป้อนข้อมูลทั้งหมด ให้ใช้ขั้นตอน 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 อื่นๆ ที่แอปพลิเคชันของคุณจะใช้และเปิดใช้ API เหล่านั้นด้วย

สร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์

แอปพลิเคชันที่ใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ขั้นตอนต่อไปนี้จะอธิบายวิธี สร้างข้อมูลเข้าสู่ระบบสำหรับโปรเจ็กต์ จากนั้นแอปพลิเคชันจะใช้ข้อมูลเข้าสู่ระบบเพื่อเข้าถึง API ที่คุณเปิดใช้สำหรับโปรเจ็กต์นั้นได้

Go to the Clients page.
คลิกสร้างไคลเอ็นต์
เลือกประเภทแอปพลิเคชันเป็น TV และอุปกรณ์อินพุตที่จำกัด
ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิกสร้าง

ระบุขอบเขตการเข้าถึง

ขอบเขตช่วยให้แอปพลิเคชันขอสิทธิ์เข้าถึงเฉพาะทรัพยากรที่จำเป็นเท่านั้น ในขณะเดียวกันก็ ช่วยให้ผู้ใช้ควบคุมระดับการเข้าถึงที่อนุญาตให้แอปพลิเคชันของคุณได้ด้วย ดังนั้น จำนวนขอบเขตที่ขออาจมีความสัมพันธ์แบบผกผันกับความเป็นไปได้ที่จะได้รับความยินยอมจากผู้ใช้

ก่อนที่จะเริ่มใช้การให้สิทธิ์ 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

แม้ว่าแอปพลิเคชันจะทำงานบนอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่จำกัด แต่ผู้ใช้ต้องมี สิทธิ์เข้าถึงอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่หลากหลายกว่าแยกต่างหากเพื่อดำเนินการขั้นตอนการให้สิทธิ์นี้ให้เสร็จสมบูรณ์ ขั้นตอนของโฟลว์มีดังนี้

แอปพลิเคชันของคุณจะส่งคำขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ซึ่งระบุขอบเขต ที่แอปพลิเคชันจะขอสิทธิ์เข้าถึง
เซิร์ฟเวอร์จะตอบกลับด้วยข้อมูลหลายอย่างที่ใช้ในขั้นตอนต่อๆ ไป เช่น รหัสอุปกรณ์และรหัสผู้ใช้
คุณแสดงข้อมูลที่ผู้ใช้ป้อนในอุปกรณ์อื่นเพื่อให้สิทธิ์แอป ของคุณ
แอปพลิเคชันจะเริ่มสำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อพิจารณาว่าผู้ใช้ ได้ให้สิทธิ์แอปของคุณหรือไม่
ผู้ใช้เปลี่ยนไปใช้อุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่หลากหลายมากขึ้น เปิดเว็บเบราว์เซอร์ ไปที่ URL ที่แสดงในขั้นตอนที่ 3 และป้อนรหัสที่แสดงในขั้นตอนที่ 3 ด้วย จากนั้นผู้ใช้จะให้สิทธิ์ (หรือปฏิเสธ) การเข้าถึงแอปพลิเคชันของคุณได้
การตอบกลับครั้งถัดไปสำหรับคำขอการสำรวจจะมีโทเค็นที่แอปของคุณต้องใช้เพื่อให้สิทธิ์ คำขอในนามของผู้ใช้ (หากผู้ใช้ปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ การตอบกลับ จะไม่มีโทเค็น)

รูปภาพด้านล่างแสดงกระบวนการนี้

ผู้ใช้เข้าสู่ระบบในอุปกรณ์อื่นที่มีเบราว์เซอร์

ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้โดยละเอียด เนื่องจากอุปกรณ์อาจมีความสามารถและสภาพแวดล้อมรันไทม์ที่หลากหลาย ตัวอย่างที่แสดงในเอกสารนี้จึงใช้curl ยูทิลิตีบรรทัดคำสั่ง ตัวอย่างเหล่านี้ควรพอร์ตไปยังภาษาและรันไทม์ต่างๆ ได้ง่าย

ขั้นตอนที่ 1: ขอรหัสอุปกรณ์และรหัสผู้ใช้

ในขั้นตอนนี้ อุปกรณ์จะส่งคำขอ HTTP POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ https://oauth2.googleapis.com/device/code ซึ่งระบุแอปพลิเคชันของคุณ รวมถึงขอบเขตการเข้าถึงที่แอปพลิเคชันต้องการเข้าถึงในนามของผู้ใช้ คุณควรดึงข้อมูล URL นี้จากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา device_authorization_endpoint ระบุพารามิเตอร์คำขอ HTTP ต่อไปนี้

พารามิเตอร์

client_id

จำเป็น

รหัสไคลเอ็นต์สำหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน Cloud Console Clients page

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 API

ตัวอย่าง

ข้อมูลโค้ดต่อไปนี้แสดงคำขอตัวอย่าง

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 ต่อผู้ใช้ ทั้ง 2 ค่าสามารถมีอักขระที่พิมพ์ได้จากชุดอักขระ US-ASCII เนื้อหา ที่คุณแสดงต่อผู้ใช้ควรแนะนำให้ผู้ใช้ไปที่ verification_url ในอุปกรณ์อื่นและป้อน user_code

ออกแบบอินเทอร์เฟซผู้ใช้ (UI) โดยคำนึงถึงกฎต่อไปนี้

user_code
- user_code ต้องแสดงในช่องที่รองรับอักขระขนาด "W" 15 ตัว กล่าวคือ หากคุณแสดงโค้ด WWWWWWWWWWWWWWW ได้อย่างถูกต้อง แสดงว่า UI ของคุณใช้ได้ และเราขอแนะนำให้ใช้ค่าสตริงดังกล่าวเมื่อทดสอบวิธีที่ user_code แสดงใน UI
- user_code คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ และไม่ควรแก้ไขไม่ว่าในลักษณะใดก็ตาม เช่น การเปลี่ยนตัวพิมพ์เล็ก/ตัวพิมพ์ใหญ่หรือการแทรกอักขระการจัดรูปแบบอื่นๆ
verification_url
- พื้นที่ที่คุณแสดง verification_url ต้องกว้างพอที่จะ รองรับสตริง URL ที่มีความยาว 40 อักขระ
- คุณไม่ควรแก้ไข verification_url ไม่ว่าในทางใดก็ตาม ยกเว้นในกรณีที่ต้องการ นำรูปแบบออกเพื่อแสดง หากคุณวางแผนที่จะนำรูปแบบ (เช่น https://) ออกจาก URL เพื่อเหตุผลในการแสดงผล โปรดตรวจสอบว่าแอปของคุณรองรับทั้งรูปแบบ http และ https

คำเตือน: ค่าทั้ง 2 นี้อาจมีการเปลี่ยนแปลง และคุณไม่ควร ฮาร์ดโค้ดค่าใดค่าหนึ่งในโค้ด ในทำนองเดียวกัน คุณไม่ควรแก้ไขค่าในลักษณะใดๆ นอกเหนือจากการนำสคีมาออกจาก verification_url

(ไม่บังคับ)

ขั้นตอนที่ 4: ตรวจสอบเซิร์ฟเวอร์การให้สิทธิ์ของ Google

เนื่องจากผู้ใช้จะใช้อุปกรณ์อื่นเพื่อไปยัง verification_url และให้ (หรือปฏิเสธ) สิทธิ์เข้าถึง ระบบจึงไม่แจ้งเตือนอุปกรณ์ที่ขอโดยอัตโนมัติเมื่อผู้ใช้ ตอบกลับคำขอเข้าถึง ด้วยเหตุนี้ อุปกรณ์ที่ส่งคำขอจึงต้องสำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อดูว่าเมื่อใดที่ผู้ใช้ตอบกลับคำขอ

อุปกรณ์ที่ขอควรส่งคำขอการสำรวจต่อไปจนกว่าจะได้รับการตอบกลับ ซึ่งระบุว่าผู้ใช้ได้ตอบกลับคำขอเข้าถึงแล้ว หรือจนกว่า device_code และ user_code ที่ได้รับใน ขั้นตอนที่ 2 จะหมดอายุ ค่า interval ที่แสดงในขั้นตอนที่ 2 จะระบุระยะเวลาเป็นวินาทีที่ต้องรอระหว่างคำขอ

URL ของปลายทางที่จะสำรวจคือ https://oauth2.googleapis.com/token คำขอการสำรวจ มีพารามิเตอร์ต่อไปนี้

พารามิเตอร์
`client_id`	รหัสไคลเอ็นต์สำหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน Cloud Console Clients page
`client_secret`	รหัสลับไคลเอ็นต์สำหรับ `client_id` ที่ระบุ คุณดูค่านี้ได้ใน Cloud Console Clients 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 API ในนามของผู้ใช้ได้ (พร็อพเพอร์ตี้ scope ในการตอบกลับจะกำหนด API ที่อุปกรณ์ เข้าถึงได้)

ในกรณีนี้ การตอบกลับจาก API จะมีช่องต่อไปนี้

ช่อง
`access_token`	โทเค็นที่แอปพลิเคชันส่งเพื่อให้สิทธิ์คำขอ Google API
`expires_in`	อายุการใช้งานที่เหลือของโทเค็นเพื่อการเข้าถึงเป็นวินาที
`refresh_token`	โทเค็นที่คุณใช้เพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ได้ โทเค็นการรีเฟรชจะใช้ได้จนกว่า ผู้ใช้จะเพิกถอนสิทธิ์เข้าถึงหรือโทเค็นการรีเฟรชจะหมดอายุ โปรดทราบว่าระบบจะแสดงโทเค็นการรีเฟรชสำหรับอุปกรณ์เสมอ
`refresh_token_expires_in`	อายุการใช้งานที่เหลือของโทเค็นการรีเฟรชเป็นวินาที ค่านี้จะตั้งค่าก็ต่อเมื่อผู้ใช้ให้สิทธิ์เข้าถึงตามเวลาเท่านั้น
`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"
}

รอการอนุมัติ

หากผู้ใช้ยังไม่ดำเนินการตามขั้นตอนการอนุญาตให้เสร็จสมบูรณ์ เซิร์ฟเวอร์จะส่งคืนรหัสสถานะการตอบกลับ 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 ไม่ถูกต้อง ตรวจสอบว่าได้ตั้งค่า ประเภทแอปพลิเคชัน สำหรับรหัสไคลเอ็นต์เป็น TV และอุปกรณ์อินพุตที่จำกัด
`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การค้นหาหรือค่าส่วนหัว HTTP Authorization Bearer หากเป็นไปได้ เราขอแนะนำให้ใช้ส่วนหัว HTTP เนื่องจากสตริงการค้นหามักจะปรากฏในบันทึกของเซิร์ฟเวอร์ ในกรณีส่วนใหญ่ คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียกไปยัง Google API ได้ (เช่น เมื่อเรียกใช้ YouTube Live Streaming API)

โปรดทราบว่า YouTube Live Streaming API ไม่รองรับโฟลว์บัญชีบริการ เนื่องจากไม่มีวิธีลิงก์บัญชีบริการกับบัญชี YouTube การพยายามให้สิทธิ์คำขอด้วยขั้นตอนการทำงานนี้จะทำให้เกิดข้อผิดพลาด NoLinkedYouTubeAccount

คุณลองใช้ Google APIs ทั้งหมดและดูขอบเขตของ API ได้ที่ 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 ที่เกี่ยวข้อง คุณ สามารถรีเฟรชโทเค็นเพื่อการเข้าถึงได้โดยไม่ต้องแจ้งให้ผู้ใช้ขอสิทธิ์ (รวมถึงเมื่อผู้ใช้ไม่ได้ อยู่) หากคุณขอสิทธิ์เข้าถึงแบบออฟไลน์ไปยังขอบเขตที่เชื่อมโยงกับโทเค็น

หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันของคุณจะส่งคำขอ HTTPS POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ 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&
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"
}

โปรดทราบว่ามีการจำกัดจำนวนโทเค็นการรีเฟรชที่จะออกให้ โดยมีการจำกัด 1 รายการต่อชุดค่าผสมไคลเอ็นต์/ผู้ใช้ และอีก 1 รายการต่อผู้ใช้ในไคลเอ็นต์ทั้งหมด คุณควรบันทึกโทเค็นการรีเฟรช ไว้ในที่เก็บข้อมูลระยะยาวและใช้ต่อไปตราบใดที่โทเค็นยังคงใช้งานได้ หากแอปพลิเคชันของคุณ ขอโทเค็นการรีเฟรชมากเกินไป อาจทำให้เกินขีดจำกัดเหล่านี้ ในกรณีนี้ โทเค็นการรีเฟรชที่เก่ากว่า จะหยุดทำงาน

การเพิกถอนโทเค็น

ในบางกรณี ผู้ใช้อาจต้องการเพิกถอนสิทธิ์เข้าถึงที่ให้แก่แอปพลิเคชัน ผู้ใช้สามารถเพิกถอนสิทธิ์เข้าถึง ได้โดยไปที่ การตั้งค่าบัญชี ดูข้อมูลเพิ่มเติมได้ที่ส่วนนำสิทธิ์เข้าถึงเว็บไซต์หรือแอปออกในเอกสารสนับสนุนเกี่ยวกับเว็บไซต์และแอปของบุคคลที่สามซึ่งมีสิทธิ์เข้าถึงบัญชีของคุณ

นอกจากนี้ แอปพลิเคชันยังเพิกถอนสิทธิ์เข้าถึงที่ได้รับโดยใช้โปรแกรมได้ด้วย การเพิกถอนแบบเป็นโปรแกรมมีความสำคัญในกรณีที่ผู้ใช้ยกเลิกการสมัครรับข้อมูล นำแอปพลิเคชันออก หรือทรัพยากร 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 สำหรับอุปกรณ์เฉพาะขอบเขตต่อไปนี้

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 ในระหว่างขั้นตอนความยินยอม เพื่อให้ผู้ใช้มีตัวเลือกในการให้สิทธิ์เข้าถึงในช่วงระยะเวลาที่จำกัด ตัวอย่างเช่น Data Portability API ซึ่งช่วยให้โอนข้อมูลได้แบบครั้งเดียว

เมื่อผู้ใช้ให้สิทธิ์เข้าถึงแอปพลิเคชันของคุณตามเวลา โทเค็นการรีเฟรชจะหมดอายุหลังจาก ระยะเวลาที่ระบุ โปรดทราบว่าโทเค็นการรีเฟรชอาจถูกทำให้ใช้ไม่ได้ก่อนหน้านี้ในบางกรณี โปรดดูรายละเอียดในกรณีเหล่านี้ ฟิลด์ refresh_token_expires_in ที่แสดงในการตอบกลับรหัสการให้สิทธิ์ แลกเปลี่ยนจะแสดงเวลาที่เหลือจนกว่าโทเค็นการรีเฟรชจะหมดอายุในกรณีดังกล่าว

การติดตั้งใช้งานการป้องกันแบบครอบคลุมหลายบริการ

อีกขั้นตอนหนึ่งที่คุณควรทำเพื่อปกป้องบัญชีของผู้ใช้คือการใช้การปกป้องข้ามบัญชีโดยใช้บริการการปกป้องข้ามบัญชีของ 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

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้การป้องกันแบบครอบคลุมหลายบริการและรายการเหตุการณ์ทั้งหมดที่พร้อมใช้งานได้ที่หน้า ปกป้องบัญชีผู้ใช้ด้วยการป้องกันแบบครอบคลุมหลายบริการ

ข้อกำหนดเบื้องต้น

เปิดใช้ API สำหรับโปรเจ็กต์

สร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์

ระบุขอบเขตการเข้าถึง

การขอโทเค็นเพื่อการเข้าถึง OAuth 2.0

ขั้นตอนที่ 1: ขอรหัสอุปกรณ์และรหัสผู้ใช้

ตัวอย่าง

ขั้นตอนที่ 2: จัดการการตอบสนองจากเซิร์ฟเวอร์การอนุญาต

การตอบรับความสำเร็จ

จำนวนการตอบกลับเกินโควต้า

ขั้นตอนที่ 3: แสดงรหัสผู้ใช้

ขั้นตอนที่ 4: ตรวจสอบเซิร์ฟเวอร์การให้สิทธิ์ของ Google

ตัวอย่าง

ขั้นตอนที่ 5: ผู้ใช้ตอบกลับคำขอสิทธิ์เข้าถึง

ขั้นตอนที่ 6: จัดการการตอบกลับคำขอการสำรวจ

ให้สิทธิ์เข้าถึงแล้ว

การเข้าถึงถูกปฏิเสธ

รอการอนุมัติ

การสำรวจความคิดเห็นบ่อยเกินไป

ข้อผิดพลาดอื่นๆ

การเรียก Google APIs

ตัวอย่าง HTTP GET

ตัวอย่างของ curl

การรีเฟรชโทเค็นเพื่อการเข้าถึง

การเพิกถอนโทเค็น

ขอบเขตที่อนุญาต

OpenID Connect การลงชื่อเข้าใช้ด้วย Google

Drive API

YouTube API

การเข้าถึงตามเวลา

การติดตั้งใช้งานการป้องกันแบบครอบคลุมหลายบริการ

ตัวอย่างของ `curl`