เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง API ข้อมูลของ YouTube ผ่านแอปพลิเคชันที่ทำงานบนอุปกรณ์อย่างทีวี คอนโซลเกม และ เครื่องพิมพ์ กล่าวอย่างเจาะจงก็คือ ขั้นตอนนี้ออกแบบมาสำหรับอุปกรณ์ที่ไม่มีสิทธิ์เข้าถึง เบราว์เซอร์หรือมีความสามารถในการป้อนข้อมูลที่จำกัด
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 สำหรับโปรเจ็กต์
- Open the API Library ใน Google API Console
- If prompted, select a project, or create a new one.
- ใช้หน้าคลังเพื่อค้นหาและเปิดใช้ YouTube Data 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 ด้วย จากนั้นผู้ใช้สามารถให้ (หรือปฏิเสธ) สิทธิ์การเข้าถึงแอปพลิเคชันของคุณได้
- การตอบกลับถัดไปสำหรับคำขอแบบสำรวจจะมีโทเค็นที่แอปของคุณต้องให้สิทธิ์ ในนามของผู้ใช้ (หากผู้ใช้ปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ การตอบกลับ ไม่มีโทเค็น)
รูปภาพด้านล่างแสดงขั้นตอนนี้
![ผู้ใช้เข้าสู่ระบบในอุปกรณ์อีกเครื่องหนึ่งที่มีเบราว์เซอร์](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/flow.png?authuser=0000&hl=th)
ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้โดยละเอียด เมื่อพิจารณาถึงความสามารถและรันไทม์ที่หลากหลาย
สภาพแวดล้อมที่อุปกรณ์อาจมี ตัวอย่างที่แสดงในเอกสารนี้ใช้ curl
บรรทัดคำสั่ง ตัวอย่างเหล่านี้ควรง่ายต่อการย้ายไปยังภาษาและรันไทม์ต่างๆ
ขั้นตอนที่ 1: ขอรหัสอุปกรณ์และผู้ใช้
ในขั้นตอนนี้ อุปกรณ์ของคุณจะส่งคำขอ HTTP POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่
https://oauth2.googleapis.com/device/code
ที่ระบุแอปพลิเคชันของคุณ
รวมทั้งขอบเขตการเข้าถึงที่แอปพลิเคชันของคุณต้องการเข้าถึงในนามของผู้ใช้
คุณควรดึงข้อมูล URL นี้จาก
เอกสารการค้นพบโดยใช้พารามิเตอร์
ค่าข้อมูลเมตา device_authorization_endpoint
รวมคำขอ HTTP ต่อไปนี้
ได้แก่
พารามิเตอร์ | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
จำเป็น
รหัสไคลเอ็นต์สำหรับแอปพลิเคชันของคุณ คุณสามารถค้นหาค่านี้ใน API Console Credentials page |
||||||||||||||||
scope |
จำเป็น
ต คั่นด้วยช่องว่าง รายการขอบเขตที่ระบุทรัพยากรที่แอปพลิเคชันของคุณสามารถเข้าถึงได้ ในนามของผู้ใช้ ค่าเหล่านี้จะบอกหน้าจอความยินยอมที่ Google จะแสดงต่อ ผู้ใช้ โปรดดู รายการขอบเขตที่อนุญาตสำหรับแอปหรืออุปกรณ์ที่ติดตั้งไว้ ขอบเขตช่วยให้แอปพลิเคชันขอเข้าถึงเฉพาะทรัพยากรที่จำเป็นต้องใช้เท่านั้น ขณะเดียวกันก็ช่วยให้ผู้ใช้สามารถควบคุมปริมาณการเข้าถึงที่จะจำกัด แอปพลิเคชัน ดังนั้นจึงจะมีความสัมพันธ์แบบผกผันระหว่างจำนวนขอบเขตที่ขอ และแนวโน้มที่จะได้รับความยินยอมจากผู้ใช้ YouTube Data API v3 ใช้ขอบเขตต่อไปนี้
เอกสารขอบเขต API ของ OAuth 2.0 จะให้ข้อมูล รายการขอบเขตทั้งหมดที่คุณอาจใช้เพื่อเข้าถึง Google APIs |
ตัวอย่าง
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอ
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.readonly
ตัวอย่างนี้แสดงคำสั่ง curl
เพื่อส่งคำขอเดียวกัน
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \ 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
ต้องแสดงในช่องที่รับ 15 "W" ได้ ขนาด อักขระ กล่าวคือ หากคุณแสดงรหัสWWWWWWWWWWWWWWW
ได้ UI ของคุณใช้งานได้ และเราขอแนะนำให้ใช้ค่าสตริงนั้นเมื่อทดสอบวิธีการuser_code
จะแสดงใน UI ของคุณuser_code
จะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ และไม่ควรแก้ไขไม่ว่าในลักษณะใดก็ตาม เช่น เช่น การเปลี่ยนตัวพิมพ์เล็กใหญ่ หรือการแทรกอักขระการจัดรูปแบบอื่นๆ
verification_url
- พื้นที่ที่คุณแสดง
verification_url
ต้องกว้างพอที่จะ จัดการสตริง URL ที่มีความยาว 40 อักขระ - คุณไม่ควรแก้ไข
verification_url
ไม่ว่าด้วยวิธีใด เว้นแต่จะเลือกได้ นำรูปแบบในการแสดงออก หากคุณวางแผนที่จะยกเลิกแผนการ (เช่นhttps://
) จาก URL ด้วยเหตุผลในการแสดง โปรดตรวจสอบว่าแอปของคุณสามารถจัดการได้ ทั้งตัวแปรhttp
และhttps
- พื้นที่ที่คุณแสดง
ขั้นตอนที่ 4: สำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google
เนื่องจากผู้ใช้จะใช้อุปกรณ์อีกเครื่องในการไปยัง verification_url
และให้สิทธิ์ (หรือปฏิเสธ) อุปกรณ์ที่ขอสิทธิ์เข้าถึงจะไม่ได้รับการแจ้งเตือนโดยอัตโนมัติเมื่อผู้ใช้
ตอบกลับคำขอสิทธิ์เข้าถึง ด้วยเหตุนี้ อุปกรณ์ที่ส่งคำขอจึงต้องตรวจสอบข้อมูล
เซิร์ฟเวอร์การให้สิทธิ์เพื่อระบุว่าผู้ใช้ตอบกลับคำขอเมื่อใด
อุปกรณ์ที่ส่งคำขอควรส่งคำขอแบบสำรวจต่อไปจนกว่าจะได้รับการตอบกลับ
ระบุว่าผู้ใช้ได้ตอบกลับคำขอสิทธิ์เข้าถึงหรือจนถึง 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:
![เชื่อมต่ออุปกรณ์ด้วยการป้อนรหัส](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/user-code.png?authuser=0000&hl=th)
หลังจากป้อน user_code
และหากยังไม่ได้เข้าสู่ระบบ ให้เข้าสู่ระบบ Google
ผู้ใช้เห็นหน้าจอขอความยินยอมดังที่แสดงด้านล่าง
![ตัวอย่างหน้าจอขอความยินยอมสำหรับไคลเอ็นต์อุปกรณ์](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/approval.png?authuser=0000&hl=th)
ขั้นตอนที่ 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" }
ทำแบบสำรวจบ่อยเกินไป
หากอุปกรณ์ส่งคำขอแบบสำรวจบ่อยเกินไป เซิร์ฟเวอร์จะแสดงผล 403
รหัสสถานะการตอบกลับ HTTP (Forbidden
) คำตอบจะมีข้อมูลต่อไปนี้
ข้อผิดพลาด:
{ "error": "slow_down", "error_description": "Forbidden" }
ข้อผิดพลาดอื่นๆ
เซิร์ฟเวอร์การให้สิทธิ์จะแสดงข้อผิดพลาดด้วย หากคำขอในการหยั่งสัญญาณขาดหายไป
หรือมีค่าพารามิเตอร์ไม่ถูกต้อง ตามปกติคำขอเหล่านี้จะมี 400
(Bad Request
) หรือสถานะการตอบกลับ HTTP ของ 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 Organization ยืนยัน ประเภทผู้ใช้ สำหรับแอปพลิเคชัน OAuth |
การเรียกใช้ Google APIs
หลังจากแอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึงแล้ว คุณจะสามารถใช้โทเค็นดังกล่าวเพื่อเรียกไปยัง
API ในนามของ
บัญชีผู้ใช้ หากได้มีการให้สิทธิ์สำหรับขอบเขตการเข้าถึงที่ API กำหนด วิธีการคือ
โทเค็นเพื่อการเข้าถึงในคำขอที่ส่งไปยัง API โดยรวมคำค้นหา access_token
หรือค่า Bearer
ของส่วนหัว HTTP Authorization
เมื่อทำได้
ส่วนหัว HTTP ดีกว่า เนื่องจากสตริงการค้นหามักจะมองเห็นได้ในบันทึกของเซิร์ฟเวอร์ ส่วนใหญ่
คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียก Google APIs (เช่น เมื่อ
การเรียกใช้ YouTube Data API)
โปรดทราบว่า API ข้อมูลของ YouTube รองรับเฉพาะบัญชีบริการสำหรับ YouTube เท่านั้น เจ้าของเนื้อหาที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่อง เช่น บันทึก และสตูดิโอภาพยนตร์
คุณสามารถทดลองใช้ Google API ทั้งหมดและดูขอบเขตของ API เหล่านี้ได้ที่ OAuth 2.0 Playground
ตัวอย่าง HTTP GET
การเรียกไปยัง
youtube.channels
ปลายทาง (YouTube Data API) ที่ใช้ Authorization: Bearer
HTTP
ส่วนหัวอาจมีลักษณะดังต่อไปนี้ โปรดทราบว่าคุณต้องระบุโทเค็นเพื่อการเข้าถึงของคุณเอง
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
นี่คือการเรียก API เดียวกันสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้วโดยใช้ access_token
พารามิเตอร์สตริงการค้นหา:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
ตัวอย่างของ curl
ทดสอบคำสั่งเหล่านี้ได้ด้วยแอปพลิเคชันบรรทัดคำสั่ง curl
นี่คือ
ตัวอย่างที่ใช้ตัวเลือกส่วนหัว HTTP (แนะนำ)
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
หรือใช้ตัวเลือกพารามิเตอร์สตริงคำค้นหาดังนี้
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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 ขีดจำกัดต่อ ชุดค่าผสมของลูกค้า/ผู้ใช้ และอีกชุดหนึ่งต่อผู้ใช้สำหรับลูกค้าทั้งหมด คุณควรบันทึกโทเค็นการรีเฟรช ในพื้นที่เก็บข้อมูลระยะยาวและใช้งานต่อไปตราบเท่าที่ยังใช้ได้ หากแอปพลิเคชันของคุณ ส่งคำขอโทเค็นการรีเฟรชมากเกินไป โทเค็นอาจเกินขีดจำกัดเหล่านี้ ซึ่งในกรณีนี้โทเค็นการรีเฟรชเก่า จะหยุดทำงาน
การเพิกถอนโทเค็น
ในบางกรณี ผู้ใช้อาจต้องการเพิกถอนสิทธิ์เข้าถึงแอปพลิเคชัน ผู้ใช้สามารถเพิกถอนสิทธิ์เข้าถึงได้ โดยไปที่ การตั้งค่าบัญชี โปรดดู ลบ ส่วนการเข้าถึงเว็บไซต์หรือแอปของเว็บไซต์บุคคลที่สามและ แอปที่มีสิทธิ์เข้าถึงบัญชีของคุณ สำหรับข้อมูลเพิ่มเติมได้
นอกจากนี้ แอปพลิเคชันยังอาจเพิกถอนสิทธิ์เข้าถึงที่ให้ไว้ทางโปรแกรมได้อีกด้วย การเพิกถอนแบบเป็นโปรแกรมมีความสำคัญในกรณีที่ผู้ใช้ยกเลิกการสมัคร นำ หรือทรัพยากร 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
การใช้การป้องกันแบบครอบคลุมหลายบริการ
ขั้นตอนเพิ่มเติมที่คุณควรทำเพื่อปกป้องผู้ใช้ของคุณ บัญชีกำลังใช้ข้ามบัญชี ป้องกันโดยใช้บริการการป้องกันแบบครอบคลุมหลายบริการของ 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
โปรดดู ปกป้องบัญชีผู้ใช้ด้วยหน้าการป้องกันแบบครอบคลุมหลายบริการ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้การป้องกันแบบครอบคลุมหลายบริการและรายการเหตุการณ์ทั้งหมดที่มี