ไลบรารี JavaScript การให้สิทธิ์ของ Google 3P สําหรับเว็บไซต์ - การอ้างอิง API

การอ้างอิงนี้อธิบายถึง API ไลบรารี JavaScript การให้สิทธิ์ของ Google แบบ 3P ซึ่งคุณสามารถใช้ในการโหลดรหัสการให้สิทธิ์หรือโทเค็นเพื่อการเข้าถึงจาก Google

เมธอด: google.accounts.oauth2.initCodeClient

เมธอด initCodeClient จะเริ่มต้นและส่งคืนไคลเอ็นต์โค้ดพร้อมด้วยการกําหนดค่าในพารามิเตอร์

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

ประเภทข้อมูล: CodeClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล CodeClientConfig

พร็อพเพอร์ตี้
client_id	ต้องระบุ รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณสามารถพบค่านี้ได้ในคอนโซล API
scope	ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณสามารถเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกถึงหน้าจอคํายินยอมที่ Google แสดงต่อผู้ใช้
include_granted_scopes	ไม่บังคับ ค่าเริ่มต้นคือ true อนุญาตให้แอปพลิเคชันใช้การให้สิทธิ์เพิ่มเติมเพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมในบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้อนุมัติคําขอการให้สิทธิ์แล้ว โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ขอใน CodeClientConfig นี้เท่านั้น
redirect_uri	ต้องระบุสําหรับการเปลี่ยนเส้นทาง UX กําหนดเซิร์ฟเวอร์ API ที่จะเปลี่ยนเส้นทางผู้ใช้หลังจากที่ผู้ใช้ทําตามขั้นตอนการให้สิทธิ์แล้ว ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าไว้ในคอนโซล API และต้องสอดคล้องกับกฎการตรวจสอบ URI การเปลี่ยนเส้นทางของเรา พร็อพเพอร์ตี้จะละเว้นโดยป๊อปอัป UX
callback	ต้องระบุสําหรับ UX แบบป๊อปอัป ฟังก์ชัน JavaScript ที่จัดการการตอบกลับของโค้ดที่ส่งคืน พร็อพเพอร์ตี้จะละเว้นโดย UX การเปลี่ยนเส้นทาง
state	ไม่บังคับ แนะนําสําหรับ UX การเปลี่ยนเส้นทาง ระบุค่าสตริงที่แอปพลิเคชันจะใช้เพื่อคงสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์
enable_serial_consent	ไม่บังคับ ค่าเริ่มต้นคือ true หากตั้งค่าเป็น false ระบบจะปิดใช้สิทธิ์บัญชี Google ที่ละเอียดยิ่งขึ้นสําหรับรหัสไคลเอ็นต์ OAuth ที่สร้างขึ้นก่อนปี 2019 ไม่มีผลสําหรับรหัสไคลเอ็นต์ OAuth ใหม่ เนื่องจากสิทธิ์ที่ละเอียดยิ่งขึ้นจะเปิดใช้เสมอ
hint	ไม่บังคับ หากแอปพลิเคชันของคุณทราบว่าผู้ใช้รายใดควรให้สิทธิ์ แอปพลิเคชันสามารถใช้พร็อพเพอร์ตี้นี้เพื่อให้คําแนะนําแก่ Google ที่อยู่อีเมลของผู้ใช้เป้าหมาย สําหรับข้อมูลเพิ่มเติม โปรดดูช่อง login_hint ในเอกสาร OpenID Connect
hd	ไม่บังคับ หากแอปพลิเคชันของคุณทราบโดเมน Workspace ที่ผู้ใช้อยู่ ให้ใช้แอตทริบิวต์นี้เพื่อให้คําแนะนําแก่ Google สําหรับข้อมูลเพิ่มเติม โปรดดูช่อง hd ในเอกสาร OpenID Connect
ux_mode	ไม่บังคับ โหมด UX ที่ใช้สําหรับขั้นตอนการให้สิทธิ์ โดยค่าเริ่มต้น ระบบจะเปิดกระบวนการขอคํายินยอมในป๊อปอัป ค่าที่ถูกต้องคือ popup และ redirect
select_account	ไม่บังคับ ค่าเริ่มต้นคือ 'false' ค่าบูลีนที่แจ้งให้ผู้ใช้เลือกบัญชี
error_callback	ไม่บังคับ ฟังก์ชัน JavaScript ที่จัดการข้อผิดพลาดที่ไม่ใช่ OAuth บางอย่าง เช่น หน้าต่างป๊อปอัปเปิดไม่สําเร็จ หรือปิดก่อนที่จะส่งคืนการตอบกลับ OAuth ช่อง "ประเภท" ของพารามิเตอร์อินพุตจะให้เหตุผลโดยละเอียด popup_failed_to_open ไม่สามารถเปิดหน้าต่างป๊อปอัปได้ popup_closed หน้าต่างป๊อปอัปจะปิดลงก่อนการตอบสนองด้วย OAuth กลับมา unknown สําหรับข้อผิดพลาดอื่นๆ

ประเภทข้อมูล: CodeClient

คลาสนี้มี requestCode ของเมธอดสาธารณะเพียงแบบเดียว ซึ่งจะเริ่มโฟลว์ UX ของรหัส OAuth 2.0

interface CodeClient {
  requestCode(): void;
}

ประเภทข้อมูล: CodeResponse

ระบบจะส่งออบเจ็กต์ JavaScript CodeResponse ไปยังเมธอด callback ใน UX แบบป๊อปอัป ใน UX การเปลี่ยนเส้นทาง ระบบจะส่ง CodeResponse เป็นพารามิเตอร์ URL

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล CodeResponse

พร็อพเพอร์ตี้
code	รหัสการให้สิทธิ์ของการตอบกลับโทเค็นที่สําเร็จ
scope	รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งผู้ใช้อนุมัติแล้ว
state	ค่าสตริงที่แอปพลิเคชันใช้เพื่อคงสถานะไว้ระหว่างคําขอการให้สิทธิ์กับการตอบกลับ
error	รหัสข้อผิดพลาด ASCII เดียว
error_description	ข้อความ ASCII ที่มนุษย์อ่านได้จะให้ข้อมูลเพิ่มเติม ซึ่งใช้เพื่อช่วยให้นักพัฒนาซอฟต์แวร์ไคลเอ็นต์เข้าใจข้อผิดพลาดที่เกิดขึ้น
error_uri	URI ที่ระบุหน้าเว็บที่มนุษย์อ่านได้ซึ่งมีข้อมูลเกี่ยวกับข้อผิดพลาด ใช้สําหรับให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดนี้แก่นักพัฒนาซอฟต์แวร์ของไคลเอ็นต์

เมธอด: google.accounts.oauth2.initTokenClient

เมธอด initTokenClient จะเริ่มต้นและส่งคืนไคลเอ็นต์โทเค็น พร้อมการกําหนดค่าในพารามิเตอร์

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

ประเภทข้อมูล: TokenClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล TokenClientConfig

พร็อพเพอร์ตี้
client_id	ต้องระบุ รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณสามารถพบค่านี้ได้ในคอนโซล API
callback	ต้องระบุ ฟังก์ชัน JavaScript ที่จัดการการตอบกลับโทเค็นที่แสดงผล
scope	ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณสามารถเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกถึงหน้าจอคํายินยอมที่ Google แสดงต่อผู้ใช้
include_granted_scopes	ไม่บังคับ ค่าเริ่มต้นคือ true อนุญาตให้แอปพลิเคชันใช้การให้สิทธิ์เพิ่มเติมเพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมในบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้อนุมัติคําขอการให้สิทธิ์แล้ว โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ขอใน TokenClientConfig นี้เท่านั้น
prompt	ไม่บังคับ ค่าเริ่มต้นคือ 'select_account' รายการข้อความแจ้งซึ่งคั่นด้วยช่องว่างและคํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เพื่อนําเสนอผู้ใช้ ค่าที่เป็นไปได้มีดังนี้ สตริงว่างเปล่า ผู้ใช้จะได้รับการแจ้งเตือนเฉพาะในครั้งแรกที่แอปของคุณขอสิทธิ์เข้าถึง ไม่สามารถระบุเป็นค่าอื่น 'none' ไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือความยินยอม ต้องระบุด้วยค่าอื่น 'consent' แจ้งให้ผู้ใช้ขอคํายินยอม 'select_account' แจ้งให้ผู้ใช้เลือกบัญชี
enable_serial_consent	ไม่บังคับ ค่าเริ่มต้นคือ true หากตั้งค่าเป็น false ระบบจะปิดใช้สิทธิ์บัญชี Google ที่ละเอียดยิ่งขึ้นสําหรับรหัสไคลเอ็นต์ OAuth ที่สร้างขึ้นก่อนปี 2019 ไม่มีผลสําหรับรหัสไคลเอ็นต์ OAuth ใหม่ เนื่องจากสิทธิ์ที่ละเอียดยิ่งขึ้นจะเปิดใช้เสมอ
hint	ไม่บังคับ หากแอปพลิเคชันของคุณทราบว่าผู้ใช้รายใดควรให้สิทธิ์ แอปพลิเคชันสามารถใช้พร็อพเพอร์ตี้นี้เพื่อให้คําแนะนําแก่ Google ที่อยู่อีเมลของผู้ใช้เป้าหมาย สําหรับข้อมูลเพิ่มเติม โปรดดูช่อง login_hint ในเอกสาร OpenID Connect
hd	ไม่บังคับ หากแอปพลิเคชันของคุณทราบโดเมน Workspace ที่ผู้ใช้อยู่ ให้ใช้แอตทริบิวต์นี้เพื่อให้คําแนะนําแก่ Google สําหรับข้อมูลเพิ่มเติม โปรดดูช่อง hd ในเอกสาร OpenID Connect
state	ไม่บังคับ ไม่แนะนำ ระบุค่าสตริงที่แอปพลิเคชันจะใช้เพื่อคงสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์
error_callback	ไม่บังคับ ฟังก์ชัน JavaScript ที่จัดการข้อผิดพลาดที่ไม่ใช่ OAuth บางอย่าง เช่น หน้าต่างป๊อปอัปเปิดไม่สําเร็จ หรือปิดก่อนที่จะส่งคืนการตอบกลับ OAuth ช่อง "ประเภท" ของพารามิเตอร์อินพุตจะให้เหตุผลโดยละเอียด popup_failed_to_open ไม่สามารถเปิดหน้าต่างป๊อปอัปได้ popup_closed หน้าต่างป๊อปอัปจะปิดลงก่อนการตอบสนองด้วย OAuth กลับมา unknown สําหรับข้อผิดพลาดอื่นๆ

ประเภทข้อมูล: TokenClient

คลาสมีเมธอดสาธารณะเพียงวิธีเดียว นั่นคือ requestAccessToken ซึ่งจะเริ่มโฟลว์ UX ของโทเค็น OAuth 2.0

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}

อาร์กิวเมนต์
overrideConfig	OverConfigableTokenClientConfig	ไม่บังคับ การกําหนดค่าที่จะถูกลบล้างในวิธีนี้

ประเภทข้อมูล: OverridableTokenClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล OverridableTokenClientConfig

พร็อพเพอร์ตี้
scope	ไม่บังคับ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกถึงหน้าจอคํายินยอมที่ Google แสดงต่อผู้ใช้
include_granted_scopes	ไม่บังคับ ค่าเริ่มต้นคือ true อนุญาตให้แอปพลิเคชันใช้การให้สิทธิ์เพิ่มเติมเพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมในบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้อนุมัติคําขอการให้สิทธิ์แล้ว โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ขอใน OverridableTokenClientConfig นี้เท่านั้น
prompt	ไม่บังคับ รายการข้อความแจ้งที่พิจารณาตัวพิมพ์เล็กและตัวพิมพ์ใหญ่เพื่อนําเสนอผู้ใช้
enable_serial_consent	ไม่บังคับ ค่าเริ่มต้นคือ true หากตั้งค่าเป็น false ระบบจะปิดใช้สิทธิ์บัญชี Google ที่ละเอียดยิ่งขึ้นสําหรับรหัสไคลเอ็นต์ OAuth ที่สร้างขึ้นก่อนปี 2019 ไม่มีผลสําหรับรหัสไคลเอ็นต์ OAuth ใหม่ เนื่องจากสิทธิ์ที่ละเอียดยิ่งขึ้นจะเปิดใช้เสมอ
hint	ไม่บังคับ หากแอปพลิเคชันของคุณทราบว่าผู้ใช้รายใดควรให้สิทธิ์ แอปพลิเคชันสามารถใช้พร็อพเพอร์ตี้นี้เพื่อให้คําแนะนําแก่ Google ที่อยู่อีเมลของผู้ใช้เป้าหมาย สําหรับข้อมูลเพิ่มเติม โปรดดูช่อง login_hint ในเอกสาร OpenID Connect
state	ไม่บังคับ ไม่แนะนำ ระบุค่าสตริงที่แอปพลิเคชันจะใช้เพื่อคงสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์

ประเภทข้อมูล: TokenResponse

ระบบจะส่งออบเจ็กต์ JavaScript ของ TokenResponse ไปยังเมธอดเรียกกลับใน UX แบบป๊อปอัป

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล TokenResponse

พร็อพเพอร์ตี้
access_token	โทเค็นเพื่อการเข้าถึงของการตอบกลับโทเค็นที่สําเร็จ
expires_in	อายุการใช้งานเป็นไม่กี่วินาทีของโทเค็นเพื่อการเข้าถึง
hd	โดเมนที่ฝากบริการที่ผู้ใช้ลงชื่อเข้าใช้อยู่
prompt	พรอมต์ที่ใช้จากรายการค่าที่เป็นไปได้ซึ่ง TokenClientConfig หรือ OverridableTokenClientConfig ระบุ
token_type	ประเภทของโทเค็นที่ออก
scope	รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งผู้ใช้อนุมัติแล้ว
state	ค่าสตริงที่แอปพลิเคชันใช้เพื่อคงสถานะไว้ระหว่างคําขอการให้สิทธิ์กับการตอบกลับ
error	รหัสข้อผิดพลาด ASCII เดียว
error_description	ข้อความ ASCII ที่มนุษย์อ่านได้จะให้ข้อมูลเพิ่มเติม ซึ่งใช้เพื่อช่วยให้นักพัฒนาซอฟต์แวร์ของไคลเอ็นต์เข้าใจข้อผิดพลาดที่เกิดขึ้น
error_uri	URI ที่ระบุหน้าเว็บที่มนุษย์อ่านได้ซึ่งมีข้อมูลเกี่ยวกับข้อผิดพลาด ใช้สําหรับให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดนี้แก่นักพัฒนาซอฟต์แวร์ของไคลเอ็นต์

เมธอด: google.accounts.oauth2.hasGrantedAllScopes

ตรวจสอบว่าผู้ใช้ให้สิทธิ์ขอบเขตที่ระบุทั้งหมดหรือไม่

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;

อาร์กิวเมนต์
tokenResponse	TokenResponse	ต้องระบุ ออบเจ็กต์ TokenResponse
firstScope	สตริง	ต้องระบุ ขอบเขตที่ต้องตรวจสอบ
restScopes	สตริง[]	ไม่บังคับ ขอบเขตอื่นๆ ที่ควรตรวจสอบ

การคืนสินค้า
บูลีน	เป็นจริงหากให้สิทธิ์ขอบเขตทั้งหมด

เมธอด: google.accounts.oauth2.hasGrantedAnyScope

ตรวจสอบว่าผู้ใช้ให้สิทธิ์ขอบเขตที่ระบุหรือไม่

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;

อาร์กิวเมนต์
tokenResponse	TokenResponse	ต้องระบุ ออบเจ็กต์ TokenResponse
firstScope	สตริง	ต้องระบุ ขอบเขตที่ต้องตรวจสอบ
restScopes	สตริง[]	ไม่บังคับ ขอบเขตอื่นๆ ที่ควรตรวจสอบ

การคืนสินค้า
บูลีน	เป็นจริงหากให้สิทธิ์ขอบเขตใดก็ได้

วิธีการ: google.accounts.oauth2.revoke

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

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;

อาร์กิวเมนต์
accessToken	สตริง	ต้องระบุ โทเค็นเพื่อการเข้าถึงที่ถูกต้อง
callback	ฟังก์ชัน	ไม่บังคับ RevocationResponse เครื่องจัดการ

ประเภทข้อมูล: RevocationResponse

ระบบจะส่งออบเจ็กต์ JavaScript ของ RevocationResponse ไปยังเมธอดเรียกกลับ

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล RevocationResponse

พร็อพเพอร์ตี้
successful	บูลีน true สําเร็จ false ล้มเหลว
error	สตริง ไม่ระบุความสําเร็จ รหัสข้อผิดพลาด ASCII เดียว ซึ่งรวมถึงแต่ไม่จํากัดเพียงรหัสข้อผิดพลาด OAuth 2.0 แบบมาตรฐาน ข้อผิดพลาดที่พบบ่อยสําหรับเมธอด revoke: invalid_token - โทเค็นหมดอายุหรือถูกเพิกถอนก่อนที่จะเรียกใช้เมธอด revoke ในกรณีส่วนใหญ่ คุณอาจเพิกถอนการให้สิทธิ์ที่เชื่อมโยงกับ accessToken ได้ invalid_request - เพิกถอนโทเค็นไม่ได้ คุณควรตรวจสอบว่า accessToken เป็นข้อมูลรับรอง Google OAuth 2.0 ที่ถูกต้อง
error_description	สตริง ไม่ระบุความสําเร็จ ข้อความ ASCII ที่มนุษย์อ่านได้จะให้ข้อมูลเพิ่มเติมเกี่ยวกับพร็อพเพอร์ตี้ error นักพัฒนาซอฟต์แวร์จึงใช้ข้อมูลนี้เพื่อทําความเข้าใจข้อผิดพลาดที่เกิดขึ้นได้ดีขึ้น สตริง error_description เป็นภาษาอังกฤษเท่านั้น สําหรับข้อผิดพลาดทั่วไปที่แสดงใน error error_descriptionที่เกี่ยวข้องมีดังนี้ invalid_token - โทเค็นหมดอายุหรือถูกเพิกถอน invalid_request - เพิกถอนโทเค็นไม่ได้