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

<br> " " ระดับ <br> <br> <แย่ < > จะต้อง พยายาม พยายามทำให้ได้ใน <br>

เอกสารนี้จะอธิบายวิธีใช้การให้สิทธิ์ 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.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 ทุก 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 Live Streaming API)

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

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

ตัวอย่าง HTTP GET

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

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&
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