เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง Google 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.
- API Library จะแสดง API ที่พร้อมใช้งานทั้งหมด โดยจัดกลุ่มตามครอบครัวและความนิยมของผลิตภัณฑ์ หาก API ที่ต้องการเปิดใช้ไม่แสดงในรายการ ให้ใช้การค้นหาเพื่อหาดังกล่าว หรือคลิกดูทั้งหมดในกลุ่มผลิตภัณฑ์ที่มี
- เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
สร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์
แอปพลิเคชันที่ใช้ OAuth 2.0 เพื่อเข้าถึง Google API ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ขั้นตอนต่อไปนี้อธิบายวิธีสร้างข้อมูลเข้าสู่ระบบสําหรับโปรเจ็กต์ จากนั้นแอปพลิเคชันจะใช้ข้อมูลเข้าสู่ระบบเพื่อเข้าถึง API ที่คุณเปิดใช้สําหรับโปรเจ็กต์นั้น
- Go to the Credentials page.
- คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
- เลือกประเภทแอปพลิเคชันเป็นทีวีและอุปกรณ์อินพุตที่จํากัด
- ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิก Create (สร้าง)
ระบุขอบเขตการเข้าถึง
ขอบเขตจะช่วยให้แอปพลิเคชันขอเข้าถึงเฉพาะทรัพยากรที่จําเป็นต้องใช้เท่านั้น ขณะเดียวกันก็ทําให้ผู้ใช้ควบคุมสิทธิ์เข้าถึงที่ให้กับแอปพลิเคชันของคุณได้ ด้วยเหตุนี้ จึงอาจมีความสัมพันธ์แบบผกผันระหว่างจํานวนขอบเขตที่ขอกับแนวโน้มการขอความยินยอมจากผู้ใช้
ก่อนที่จะเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนําให้คุณระบุขอบเขตที่แอปจะต้องมีสิทธิ์เข้าถึง
ดูรายการขอบเขตที่อนุญาตสําหรับแอปหรืออุปกรณ์ที่ติดตั้ง
การรับโทเค็นเพื่อการเข้าถึง OAuth 2.0
แม้ว่าแอปพลิเคชันของคุณจะทํางานบนอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่จํากัด แต่ผู้ใช้ต้องมีสิทธิ์เข้าถึงอุปกรณ์แยกต่างหาก ซึ่งมีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้นจึงจะดําเนินการให้สิทธิ์นี้ให้เสร็จสมบูรณ์ได้ ขั้นตอนมีขั้นตอนต่อไปนี้
- แอปพลิเคชันของคุณส่งคําขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ซึ่งระบุขอบเขตที่แอปพลิเคชันจะขอสิทธิ์เข้าถึง
- เซิร์ฟเวอร์จะตอบกลับด้วยข้อมูลหลายชิ้นที่ใช้ในขั้นตอนต่อๆ ไป เช่น รหัสอุปกรณ์และรหัสผู้ใช้
- คุณแสดงข้อมูลที่ผู้ใช้ป้อนในอุปกรณ์เครื่องอื่นได้เพื่อให้สิทธิ์แอป
- แอปพลิเคชันของคุณจะเริ่มการสํารวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อดูว่าผู้ใช้ให้สิทธิ์แอปของคุณหรือไม่
- ผู้ใช้จะเปลี่ยนไปใช้อุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้น เปิดใช้เว็บเบราว์เซอร์ ไปยัง URL ที่แสดงในขั้นตอนที่ 3 และป้อนรหัสซึ่งแสดงในขั้นตอนที่ 3 ด้วย จากนั้นผู้ใช้ก็จะให้สิทธิ์ (หรือปฏิเสธ) สิทธิ์เข้าถึงแอปพลิเคชันของคุณได้
- การตอบกลับคําขอแบบสํารวจถัดไปจะมีโทเค็นที่แอปของคุณต้องให้สิทธิ์ในนามของผู้ใช้ (หากผู้ใช้ปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ การตอบกลับจะไม่มีโทเค็น)
รูปภาพด้านล่างแสดงกระบวนการนี้

ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้อย่างละเอียด เนื่องจากช่วงความสามารถและสภาพแวดล้อมรันไทม์ที่อุปกรณ์อาจมี ตัวอย่างที่แสดงในเอกสารนี้จะใช้ยูทิลิตีบรรทัดคําสั่ง curl
ตัวอย่างเหล่านี้ควรที่จะถ่ายโอนไปยังภาษาและรันไทม์ต่างๆ ได้
ขั้นตอนที่ 1: ขอรหัสอุปกรณ์และรหัสผู้ใช้
ในขั้นตอนนี้ อุปกรณ์ของคุณจะส่งคําขอ HTTP POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่
https://oauth2.googleapis.com/device/code
ซึ่งระบุแอปพลิเคชันของคุณ รวมถึงขอบเขตการเข้าถึงที่แอปพลิเคชันต้องการเข้าถึงในนามของผู้ใช้
คุณควรเรียกข้อมูล URL นี้จากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา device_authorization_endpoint
ใส่พารามิเตอร์คําขอ HTTP ต่อไปนี้
พารามิเตอร์ | |
---|---|
client_id |
จำเป็น
รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API Console Credentials page |
scope |
จำเป็น
รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกให้หน้าจอขอความยินยอมที่ Google แสดงต่อผู้ใช้ ดูรายการขอบเขตที่อนุญาตสําหรับแอปหรืออุปกรณ์ที่ติดตั้ง ขอบเขตจะช่วยให้แอปพลิเคชันขอเข้าถึงเฉพาะทรัพยากรที่จําเป็นต้องใช้เท่านั้น และในขณะเดียวกันก็ทําให้ผู้ใช้ควบคุมสิทธิ์เข้าถึงที่ตนเองมีให้กับแอปพลิเคชันได้ด้วย ดังนั้นจึงมีความสัมพันธ์แบบผกผันระหว่างจํานวนขอบเขตที่ขอกับแนวโน้มการขอความยินยอมจากผู้ใช้ |
ตัวอย่าง
ข้อมูลโค้ดต่อไปนี้จะแสดงคําขอตัวอย่าง
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=email%20profile
ตัวอย่างนี้แสดงคําสั่ง curl
ในการส่งคําขอเดียวกัน
curl -d "client_id=client_id&scope=email%20profile" \ 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
แสดงใน 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 |
รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน 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" \ /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" }
รอการให้สิทธิ์
หากผู้ใช้ยังดําเนินกระบวนการให้สิทธิ์ไม่เสร็จสมบูรณ์ เซิร์ฟเวอร์จะแสดงรหัสสถานะการตอบกลับ 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 เช่น ข้อผิดพลาดนี้จะเกิดขึ้นหากค่าพารามิเตอร์ ประเภทไคลเอ็นต์ OAuth ไม่ถูกต้อง ตรวจสอบว่าได้ตั้งค่าประเภทแอปพลิเคชันสําหรับรหัสไคลเอ็นต์เป็นทีวีและอุปกรณ์อินพุตที่จํากัด |
invalid_grant |
400 |
ค่าพารามิเตอร์ code ไม่ถูกต้อง มีการอ้างสิทธิ์แล้ว หรือแยกวิเคราะห์ไม่ได้ |
unsupported_grant_type |
400 |
ค่าพารามิเตอร์ grant_type ไม่ถูกต้อง |
org_internal |
403 |
รหัสไคลเอ็นต์ OAuth ในคําขอเป็นส่วนหนึ่งของโปรเจ็กต์ที่จํากัดการเข้าถึงบัญชี Google ใน องค์กร Google Cloud ที่เฉพาะเจาะจง ยืนยันการกําหนดค่าประเภทผู้ใช้สําหรับแอปพลิเคชัน OAuth |
การเรียกใช้ Google API
หลังจากที่แอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึง คุณจะใช้โทเค็นเพื่อเรียก API ของ Google ในนามของบัญชีผู้ใช้ดังกล่าวได้ หากขอบเขตการเข้าถึงที่ API กําหนดไว้นั้นได้รับอนุญาต โดยใส่โทเค็นเพื่อการเข้าถึงในคําขอลงใน API ด้วยการใส่พารามิเตอร์การค้นหา access_token
หรือค่า Authorization
ของส่วนหัว HTTP เป็น Bearer
หากเป็นไปได้ ส่วนหัว HTTP เป็นตัวเลือกที่ดีกว่า เนื่องจากสตริงการค้นหามีแนวโน้มที่จะแสดงในบันทึกของเซิร์ฟเวอร์ ในกรณีส่วนใหญ่ คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียกไปยัง Google API (เช่น เมื่อเรียก Drive Files API)
คุณจะลองใช้ Google API ทั้งหมดและดูขอบเขตได้ที่ OAuth 2.0 Playground
ตัวอย่าง HTTP GET
การเรียกปลายทาง
drive.files
(Drive Files API) โดยใช้ส่วนหัว HTTP ของ Authorization: Bearer
อาจมีลักษณะดังต่อไปนี้ โปรดทราบว่าคุณต้องระบุโทเค็นเพื่อการเข้าถึงของคุณเอง ดังนี้
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
นี่คือการเรียกไปยัง API เดียวกันสําหรับผู้ใช้ที่ตรวจสอบสิทธิ์โดยใช้พารามิเตอร์สตริงการค้นหา access_token
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
ตัวอย่างของ curl
คุณทดสอบคําสั่งเหล่านี้ได้โดยใช้แอปพลิเคชันบรรทัดคําสั่ง curl
ตัวอย่างที่ใช้ตัวเลือกส่วนหัวของ HTTP (แนะนํา) มีดังนี้
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
หรือเลือกตัวเลือกพารามิเตอร์สตริงการค้นหา ดังนี้
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
การรีเฟรชโทเค็นเพื่อการเข้าถึง
โทเค็นเพื่อการเข้าถึงจะหมดอายุเป็นระยะๆ และกลายเป็นข้อมูลเข้าสู่ระบบที่ไม่ถูกต้องสําหรับคําขอ API ที่เกี่ยวข้อง คุณจะรีเฟรชโทเค็นเพื่อการเข้าถึงได้โดยไม่ต้องแจ้งผู้ใช้ว่ามีสิทธิ์ (รวมถึงเมื่อผู้ใช้ไม่ได้มีอยู่) หากคุณขอสิทธิ์เข้าถึงแบบออฟไลน์ในขอบเขตที่เชื่อมโยงกับโทเค็น
หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันจะส่งคําขอ POST
แบบ HTTPS ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ 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
Drive 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