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

-

เอกสารนี้จะอธิบายวิธีใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง Google API ผ่านแอปพลิเคชันที่ทํางานในอุปกรณ์ เช่น ทีวี คอนโซลเกม และเครื่องพิมพ์ กล่าวอย่างเจาะจงคือ การดําเนินการนี้ออกแบบมาสําหรับอุปกรณ์ที่ไม่มีสิทธิ์เข้าถึงเบราว์เซอร์หรือมีวิธีการป้อนข้อมูลแบบจํากัด

OAuth 2.0 ช่วยให้ผู้ใช้แชร์ข้อมูลที่เจาะจงกับแอปพลิเคชันได้ ขณะที่เก็บชื่อผู้ใช้ รหัสผ่าน และข้อมูลอื่นๆ ไว้เป็นส่วนตัว ตัวอย่างเช่น แอปพลิเคชันทีวีอาจใช้ OAuth 2.0 เพื่อรับสิทธิ์ในการเลือกไฟล์ที่จัดเก็บไว้ใน Google ไดรฟ์

เนื่องจากแอปพลิเคชันที่ใช้ขั้นตอนนี้มีการกระจายไปยังอุปกรณ์แต่ละเครื่อง จึงจะถือว่าแอปไม่สามารถเก็บข้อมูลลับได้ ผู้ใช้จะเข้าถึง Google APIs ได้ขณะที่ผู้ใช้แสดงในแอปหรือเมื่อแอปทํางานอยู่เบื้องหลัง

ทางเลือก

หากเขียนแอปสําหรับแพลตฟอร์มอย่าง Android, iOS, macOS, Linux หรือ Windows (รวมถึง Universal Windows Platform) ที่มีสิทธิ์เข้าถึงเบราว์เซอร์และการป้อนข้อมูลอย่างเต็มรูปแบบ ให้ใช้ขั้นตอน OAuth 2.0 สําหรับแอปพลิเคชันในอุปกรณ์เคลื่อนที่และเดสก์ท็อป (คุณควรใช้ขั้นตอนดังกล่าวแม้ว่าแอปจะเป็นเครื่องมือบรรทัดคําสั่งที่ไม่มีอินเทอร์เฟซแบบกราฟิก)

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

สิ่งที่ต้องมีก่อน

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

แอปพลิเคชันใดก็ตามที่เรียกใช้ Google APIs จะต้องเปิดใช้ API เหล่านั้นใน API Console

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

1. Open the API Library ใน Google API Console
2. If prompted, select a project, or create a new one.
3. API Library จะแสดงรายการ API ที่ใช้ได้ทั้งหมดซึ่งจัดกลุ่มตามตระกูลผลิตภัณฑ์และความนิยม หาก API ที่ต้องการเปิดใช้ไม่แสดงในรายการ ให้ใช้การค้นหาเพื่อค้นหาหรือคลิก ดูทั้งหมด ในตระกูลผลิตภัณฑ์ที่เป็นเจ้าของ
4. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

แอปพลิเคชันที่ใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ขั้นตอนต่อไปนี้อธิบายวิธีสร้างข้อมูลเข้าสู่ระบบสําหรับโปรเจ็กต์ของคุณ จากนั้นแอปพลิเคชันจะใช้ข้อมูลเข้าสู่ระบบเพื่อเข้าถึง API ที่คุณเปิดใช้สําหรับโปรเจ็กต์นั้นได้

1. Go to the Credentials page.
2. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
3. เลือกประเภทแอปพลิเคชันเป็นทีวีและอุปกรณ์อินพุตที่จํากัด
4. ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิกสร้าง

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

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

ก่อนที่จะเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนําให้คุณระบุขอบเขตที่แอปจําเป็นต้องมีสิทธิ์เข้าถึง

หมายเหตุ: แอปหรืออุปกรณ์ที่ติดตั้งไว้ไม่รองรับการให้สิทธิ์แบบเพิ่ม

ดูรายการอุปกรณ์ที่อนุญาตสําหรับแอปหรืออุปกรณ์ที่ติดตั้งไว้

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

การรับโทเค็นเพื่อการเข้าถึง 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	จำเป็น รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials 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=

ตัวอย่างนี้แสดงคําสั่ง curl ในการส่งคําขอเดียวกัน

curl -d "client_id=client_id&scope=" \
     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

คําเตือน: ค่าทั้ง 2 รายการนี้อาจมีการเปลี่ยนแปลง และไม่ควรฮาร์ดโค้ดค่าใดค่าหนึ่งในโค้ด ในทํานองเดียวกัน คุณไม่ควรแก้ไขค่าด้วยวิธีอื่นที่ไม่ใช่การนํารูปแบบออกจาก verification_url

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

เนื่องจากผู้ใช้จะใช้อุปกรณ์แยกต่างหากเพื่อไปที่ verification_url และให้สิทธิ์เข้าถึง (หรือปฏิเสธ) อุปกรณ์ที่ขอจะไม่ได้รับการแจ้งเตือนโดยอัตโนมัติเมื่อผู้ใช้ตอบกลับคําขอสิทธิ์เข้าถึง ด้วยเหตุนี้ อุปกรณ์ที่ขอจึงต้องส่งแบบสํารวจของเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อระบุว่าผู้ใช้ตอบกลับคําขอเมื่อใด

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

URL ปลายทางไปยังแบบสํารวจคือ https://oauth2.googleapis.com/token คําขอแบบสํารวจมีพารามิเตอร์ต่อไปนี้

พารามิเตอร์
client_id	รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials page
client_secret	รหัสลับไคลเอ็นต์สําหรับ client_id ที่ระบุ คุณดูค่านี้ได้ใน API ConsoleCredentials 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 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"
}

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

หากผู้ใช้ยังไม่ได้ดําเนินการตามขั้นตอนการให้สิทธิ์ เซิร์ฟเวอร์จะส่งคืนรหัสสถานะการตอบสนอง 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	คำอธิบาย
invalid_client	401	ไม่พบไคลเอ็นต์ OAuth เช่น ข้อผิดพลาดนี้จะเกิดขึ้นหากค่าพารามิเตอร์ client_id ไม่ถูกต้อง
invalid_grant	400	ค่าพารามิเตอร์ code ไม่ถูกต้อง
unsupported_grant_type	400	ค่าพารามิเตอร์ grant_type ไม่ถูกต้อง

การเรียก Google APIs

หลังจากที่แอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึงแล้ว คุณจะใช้โทเค็นเพื่อเรียก 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 ที่เกี่ยวข้อง คุณรีเฟรชโทเค็นเพื่อการเข้าถึงได้โดยไม่ต้องแจ้งผู้ใช้เพื่อขอรับสิทธิ์ (รวมถึงเมื่อผู้ใช้ไม่แสดง) หากคุณขอสิทธิ์เข้าถึงแบบออฟไลน์ซึ่งเชื่อมโยงกับขอบเขตที่เกี่ยวข้องกับโทเค็น

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

กําลังเพิกถอนโทเค็น

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

นอกจากนี้ แอปพลิเคชันอาจเพิกถอนการเข้าถึงแบบเป็นโปรแกรมด้วยโปรแกรมได้ การเพิกถอนแบบเป็นโปรแกรมมีความสําคัญในกรณีที่ผู้ใช้ยกเลิกการสมัคร นําแอปพลิเคชันออก หรือทรัพยากร 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