เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ 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 API ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ขั้นตอนต่อไปนี้อธิบายวิธีสร้างข้อมูลเข้าสู่ระบบสำหรับโปรเจ็กต์ จากนั้นแอปพลิเคชันจะใช้ข้อมูลเข้าสู่ระบบเพื่อเข้าถึง API ที่คุณเปิดใช้สำหรับโปรเจ็กต์นั้นได้
- Go to the Credentials page.
- คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
- เลือกประเภทแอปพลิเคชันทีวีและอุปกรณ์อินพุตแบบจำกัด
- ตั้งชื่อไคลเอ็นต์ 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
แม้ว่าแอปพลิเคชันของคุณจะทำงานบนอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่จำกัด แต่ผู้ใช้ต้องมี การเข้าถึงแยกต่างหากสำหรับอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้นเพื่อดำเนินการขั้นตอนการให้สิทธิ์นี้ให้เสร็จสมบูรณ์ ขั้นตอนนี้มีขั้นตอนดังนี้
- แอปพลิเคชันจะส่งคำขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ระบุขอบเขตที่แอปพลิเคชันของคุณจะขอสิทธิ์ในการเข้าถึง
- เซิร์ฟเวอร์จะตอบกลับด้วยข้อมูลหลายรายการที่ใช้ในขั้นตอนถัดไป เช่น รหัสอุปกรณ์และรหัสผู้ใช้
- คุณแสดงข้อมูลที่ผู้ใช้ป้อนในอุปกรณ์อีกเครื่องหนึ่งเพื่อให้สิทธิ์แอปของคุณได้
- แอปพลิเคชันจะเริ่มสำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อดูว่าผู้ใช้ให้สิทธิ์แอปของคุณแล้วหรือยัง
- ผู้ใช้จะเปลี่ยนไปใช้อุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้น เปิดเว็บเบราว์เซอร์ ไปยัง URL ที่แสดงในขั้นตอนที่ 3 และป้อนรหัสที่แสดงในขั้นตอนที่ 3 ด้วย จากนั้นผู้ใช้จึงให้ (หรือปฏิเสธ) การเข้าถึงแอปพลิเคชันของคุณได้
- การตอบกลับครั้งถัดไปของคำขอในแบบสำรวจจะมีโทเค็นที่แอปของคุณต้องใช้เพื่อให้สิทธิ์คำขอในนามของผู้ใช้ (หากผู้ใช้ปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ การตอบกลับจะไม่มีโทเค็น)
รูปภาพด้านล่างแสดงกระบวนการนี้
ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้โดยละเอียด จากความสามารถและสภาพแวดล้อมรันไทม์ที่มีความหลากหลายซึ่งอุปกรณ์อาจมี ตัวอย่างที่แสดงในเอกสารนี้จึงใช้ยูทิลิตีบรรทัดคำสั่ง 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 ใช้ขอบเขตต่อไปนี้
เอกสารขอบเขต 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.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 ให้ผู้ใช้เห็น ทั้งสองค่าสามารถมีอักขระที่พิมพ์ได้จากชุดอักขระ US-ASCII เนื้อหาที่คุณแสดงต่อผู้ใช้ควรแนะนำให้ผู้ใช้ไปที่ verification_url
ในอุปกรณ์อื่นและป้อน user_code
ออกแบบอินเทอร์เฟซผู้ใช้ (UI) โดยคำนึงถึงกฎต่อไปนี้
user_code
user_code
ต้องแสดงในช่องที่รองรับอักขระ "W" ได้ 15 ตัว กล่าวคือ หากคุณแสดงโค้ดWWWWWWWWWWWWWWW
ได้อย่างถูกต้อง UI ก็ใช้งานได้ และเราขอแนะนำให้ใช้ค่าสตริงดังกล่าวเมื่อทดสอบวิธีที่user_code
แสดงใน UIuser_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 เช่น ข้อผิดพลาดนี้จะเกิดขึ้นหากค่าพารามิเตอร์ ประเภทไคลเอ็นต์ 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 APIs ได้ (เช่น เมื่อเรียกใช้ API สตรีมมิงแบบสดของ YouTube)
โปรดทราบว่า API สตรีมมิงแบบสดของ YouTube ไม่รองรับขั้นตอนของบัญชีบริการ เนื่องจากไม่สามารถลิงก์บัญชีบริการกับบัญชี YouTube ได้ การพยายามให้สิทธิ์คำขอด้วยขั้นตอนนี้จะทำให้เกิดข้อผิดพลาด NoLinkedYouTubeAccount
คุณลองใช้ Google API ทั้งหมดและดูขอบเขตของ 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