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

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

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. ใช้หน้าคลังเพื่อค้นหาและเปิดใช้ YouTube Data API ค้นหา API อื่นๆ ที่แอปพลิเคชันจะใช้และเปิดใช้ API เหล่านั้นด้วย

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

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

  1. Go to the Credentials page.
  2. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
  3. เลือกประเภทแอปพลิเคชันทีวีและอุปกรณ์อินพุตแบบจำกัด
  4. ตั้งชื่อไคลเอ็นต์ 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

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

  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 จำเป็น

รหัสไคลเอ็นต์สำหรับแอปพลิเคชันของคุณ คุณดูค่านี้ได้ใน Credentials pageใน API Console
scope จำเป็น

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

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

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

เอกสารขอบเขต 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.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"
}

ในกรณีดังกล่าว ให้ใช้กลยุทธ์ Backoff เพื่อลดอัตราคำขอ

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

แสดง verification_url และ user_code ที่ได้รับในขั้นตอนที่ 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 ได้

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

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

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

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

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

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

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

โปรดทราบว่า YouTube Data API รองรับบัญชีบริการสำหรับเจ้าของเนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่องเท่านั้น เช่น ค่ายเพลงและสตูดิโอภาพยนตร์

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

หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันจะส่งคำขอ 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&
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

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