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

หมายเหตุ หมายเหตุ

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

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

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

ทางเลือก

หากคุณกำลังเขียนแอปสำหรับแพลตฟอร์มอย่าง Android, iOS, macOS, Linux หรือ Windows (รวมถึงแพลตฟอร์ม Universal Windows) ที่มีสิทธิ์เข้าถึงเบราว์เซอร์และความสามารถในการป้อนข้อมูลเต็มรูปแบบ ให้ใช้ขั้นตอน 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. API Library แสดงรายการ API ทั้งหมดที่ใช้ได้โดยจัดกลุ่มตามตระกูลผลิตภัณฑ์และความนิยม หาก API ที่ต้องการเปิดใช้ไม่ปรากฏในรายการ ให้ใช้การค้นหาเพื่อหา 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 API ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันกับเซิร์ฟเวอร์ 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 นี้จากเอกสาร Discovery โดยใช้ค่าข้อมูลเมตา 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"
}

ในกรณีดังกล่าว ให้ใช้กลยุทธ์ Backoff เพื่อลดอัตราคําขอ

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

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

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

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