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

เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง Google 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 API จะต้องเปิดใช้ API ดังกล่าวใน API Console

วิธีเปิดใช้ API สําหรับโปรเจ็กต์ของคุณ

1. Open the API Library ใน Google API Console
2. If prompted, select a project, or create a new one.
3. API Library จะแสดง API ที่พร้อมใช้งานทั้งหมด โดยจัดกลุ่มตามครอบครัวและความนิยมของผลิตภัณฑ์ หาก API ที่ต้องการเปิดใช้ไม่แสดงในรายการ ให้ใช้การค้นหาเพื่อหาดังกล่าว หรือคลิกดูทั้งหมดในกลุ่มผลิตภัณฑ์ที่มี
4. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Credentials page.
2. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
3. เลือกประเภทแอปพลิเคชันเป็นทีวีและอุปกรณ์อินพุตที่จํากัด
4. ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิก Create (สร้าง)

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

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

ก่อนที่จะเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนําให้คุณระบุขอบเขตที่แอปจะต้องมีสิทธิ์เข้าถึง

หมายเหตุ: แอปหรืออุปกรณ์ที่ติดตั้งไม่รองรับการให้สิทธิ์ที่เพิ่มขึ้น

ดูรายการขอบเขตที่อนุญาตสําหรับแอปหรืออุปกรณ์ที่ติดตั้ง

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

การรับโทเค็นเพื่อการเข้าถึง 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 นี้จากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา device_authorization_endpoint ใส่พารามิเตอร์คําขอ HTTP ต่อไปนี้

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

ตัวอย่าง

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

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

ตัวอย่างนี้แสดงคําสั่ง curl ในการส่งคําขอเดียวกัน

curl -d "client_id=client_id&scope=email%20profile" \
     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 ให้กับผู้ใช้ ทั้ง 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 ได้

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

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

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

หากผู้ใช้ไม่ให้สิทธิ์เข้าถึงอุปกรณ์ การตอบสนองของเซิร์ฟเวอร์จะมีรหัสสถานะการตอบสนอง HTTP 403 (Forbidden) การตอบกลับจะมีข้อผิดพลาดต่อไปนี้

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

รอการให้สิทธิ์

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

หลังจากที่แอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึง คุณจะใช้โทเค็นเพื่อเรียก API ของ Google ในนามของบัญชีผู้ใช้ดังกล่าวได้ หากขอบเขตการเข้าถึงที่ API กําหนดไว้นั้นได้รับอนุญาต โดยใส่โทเค็นเพื่อการเข้าถึงในคําขอลงใน API ด้วยการใส่พารามิเตอร์การค้นหา access_token หรือค่า Authorization ของส่วนหัว HTTP เป็น Bearer หากเป็นไปได้ ส่วนหัว HTTP เป็นตัวเลือกที่ดีกว่า เนื่องจากสตริงการค้นหามีแนวโน้มที่จะแสดงในบันทึกของเซิร์ฟเวอร์ ในกรณีส่วนใหญ่ คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียกไปยัง Google API (เช่น เมื่อเรียก Drive Files API)

คุณจะลองใช้ Google API ทั้งหมดและดูขอบเขตได้ที่ OAuth 2.0 Playground

ตัวอย่าง HTTP GET

การเรียกปลายทาง drive.files (Drive Files API) โดยใช้ส่วนหัว HTTP ของ Authorization: Bearer อาจมีลักษณะดังต่อไปนี้ โปรดทราบว่าคุณต้องระบุโทเค็นเพื่อการเข้าถึงของคุณเอง ดังนี้

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

นี่คือการเรียกไปยัง API เดียวกันสําหรับผู้ใช้ที่ตรวจสอบสิทธิ์โดยใช้พารามิเตอร์สตริงการค้นหา access_token

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

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

คุณทดสอบคําสั่งเหล่านี้ได้โดยใช้แอปพลิเคชันบรรทัดคําสั่ง curl ตัวอย่างที่ใช้ตัวเลือกส่วนหัวของ HTTP (แนะนํา) มีดังนี้

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

หรือเลือกตัวเลือกพารามิเตอร์สตริงการค้นหา ดังนี้

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

โทเค็นเพื่อการเข้าถึงจะหมดอายุเป็นระยะๆ และกลายเป็นข้อมูลเข้าสู่ระบบที่ไม่ถูกต้องสําหรับคําขอ 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"
}

โปรดทราบว่าระบบจะจํากัดจํานวนโทเค็นการรีเฟรชที่ออกให้ โดยขีดจํากัด 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 สําหรับอุปกรณ์ได้รับการสนับสนุนในขอบเขตต่อไปนี้เท่านั้น

OpenID Connect, Google Sign-In

• email
• openid
• profile

Drive API

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

API ของ YouTube

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