หน้านี้ได้รับการแปลโดย Cloud Translation API

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 สําหรับโปรเจ็กต์

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

พารามิเตอร์

client_id

จำเป็น

รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ในส่วน API Console Credentials 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

เอกสารขอบเขต OAuth 2.0 API มีรายการขอบเขตทั้งหมดที่คุณอาจใช้เพื่อเข้าถึง 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 ทุก 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

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

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

หากผู้ใช้ปฏิเสธการให้สิทธิ์เข้าถึงอุปกรณ์ การตอบกลับของเซิร์ฟเวอร์จะมี403รหัสสถานะการตอบกลับ HTTP (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

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

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

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

ตัวอย่าง HTTP GET

การเรียกใช้ปลายทาง (YouTube Live Streaming API) liveBroadcasts.list โดยใช้ส่วนหัว 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`	คุณต้องตั้งค่าช่องนี้เป็น `refresh_token` ตามที่ระบุไว้ในข้อกำหนดเฉพาะของ OAuth 2.0
`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 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 บริการนี้ช่วยให้คุณสมัครรับการแจ้งเตือนเหตุการณ์ด้านความปลอดภัยซึ่งจะส่งข้อมูลเกี่ยวกับการเปลี่ยนแปลงที่สำคัญในบัญชีผู้ใช้ไปยังแอปพลิเคชัน จากนั้น คุณสามารถใช้ข้อมูลดังกล่าวเพื่อดําเนินการโดยขึ้นอยู่กับวิธีตอบสนองต่อเหตุการณ์

ตัวอย่างประเภทเหตุการณ์ที่บริการการปกป้องบัญชีข้ามของ 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

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

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

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

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

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

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

การรับโทเค็นการเข้าถึง OAuth 2.0

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

ตัวอย่าง

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

การตอบกลับที่สำเร็จ

การตอบกลับที่เกินโควต้า

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

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

ตัวอย่าง

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

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

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

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

กำลังรอให้สิทธิ์

ทำการสำรวจบ่อยเกินไป

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

การเรียกใช้ Google API

ตัวอย่าง HTTP GET

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

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

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

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

OpenID Connect Google Sign-In

Drive API

YouTube API

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

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