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 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 นี้จากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา 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 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"
}

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

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

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

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

  • user_code
    • user_code ต้องแสดงในช่องที่รองรับอักขระขนาด 15 'W' ได้ กล่าวคือ หากคุณแสดงโค้ด 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 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"
}

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

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

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

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

คุณลองใช้ Google 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