يصف هذا المرجع واجهة برمجة تطبيقات Google 3P Auth JavaScript Library API، والتي يمكنك استخدامها لتحميل رموز التفويض أو رموز الدخول من Google.
الطريقة: google.accounts.oauth2.initCodeClient
تعمل الطريقة initCodeClient
على إعداد برنامج رمز وعرضه باستخدام الإعدادات في المَعلمة.
google.accounts.oauth2.initCodeClient(config: CodeClientConfig)
نوع البيانات: CodeClientConfig
يعرض الجدول التالي خصائص نوع بيانات CodeClientConfig
.
أماكن إقامة | |
---|---|
client_id
|
يجب ملء هذا الحقل. معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في وحدة تحكم واجهة برمجة التطبيقات. |
scope
|
يجب ملء هذا الحقل. قائمة بالنطاقات المفصولة بمسافات والتي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتوضِّح هذه القيم شاشة طلب الموافقة التي تعرضها Google للمستخدم. |
include_granted_scopes |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . للسماح للتطبيقات باستخدام التفويض المتزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة هذه المَعلمة على false وتم منح طلب التفويض، لن يشمل رمز الدخول الجديد سوى النطاقات التي طلب scope استخدامها في CodeClientConfig .
|
redirect_uri
|
مطلوب لإعادة توجيه UX. يُحدِّد المكان الذي يُعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل المستخدم عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرِّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لعميل OAuth 2.0، وقد تم ضبطه في وحدة تحكُّم واجهة برمجة التطبيقات ويجب أن تتوافق مع قواعد التحقُّق من معرِّف الموارد المنتظم (URI) لإعادة التوجيه. وستتجاهل النافذة المنبثقة تجربة المستخدم الموقع. |
callback |
مطلوب للنافذة المنبثقة UX. دالة JavaScript التي تتعامل مع استجابة الرمز المعروض. ستتجاهل تجربة المستخدم الخاصة بإعادة التوجيه الموقع. |
state |
اختياريّ. يُنصَح به لإعادة توجيه تجربة المستخدم. يحدّد هذا الإعداد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض. |
enable_granular_consent |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . أمّا في حال ضبط السياسة على false ، فسيتم إيقاف أذونات أكثر دقة لحساب Google
لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. في حال ضبط كل من enable_granular_consent وenable_serial_consent ، سيتم تطبيق قيمة enable_granular_consent فقط ويتم تجاهل قيمة enable_serial_consent .ما مِن تأثير لمعرّفات عملاء OAuth الأحدث، لأنّه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها. |
enable_serial_consent |
تم إيقاف العمل بها، لذا يجب استخدام السمة enable_granular_consent بدلاً منها. ويؤدي هذا الإجراء
إلى التأثير نفسه الناتج عن enable_granular_consent . ويمكن للتطبيقات الحالية التي تستخدم enable_serial_consent مواصلة استخدامها، ولكن ننصحك
بتحديث الرمز الخاص بك لاستخدام enable_granular_consent في
التحديث التالي للتطبيق.
|
login_hint |
اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي يجب أن يصادق على الطلب، يمكنه استخدام هذه السمة لتقديم تلميح تسجيل الدخول إلى Google. عند نجاح هذا الإجراء، يتم تخطّي اختيار الحساب. تشير هذه السمة إلى قيمة الحقل sub لعنوان البريد الإلكتروني أو الرمز المميّز لرقم التعريف للمستخدم المستهدَف.
للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحقل login_hint في مستندات OpenID Connect.
|
hd |
اختياريّ. إذا كان تطبيقك يعرف نطاق Workspace الذي ينتمي إليه المستخدم، استخدِم هذا الإذن لتقديم تلميح إلى Google. عند نجاح هذا الإجراء، تقتصر حسابات المستخدمين على النطاق المقدَّم أو تكون محدّدة مسبقًا له.
للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحقل hd في مستندات OpenID Connect.
|
ux_mode |
اختياريّ. وضع تجربة المستخدم المراد استخدامه في تدفق التفويض. سيؤدي ذلك تلقائيًا إلى فتح مسار الموافقة في نافذة منبثقة. القيمتان الصالحتان هما popup وredirect .
|
select_account |
وتكون قيمة هذه السمة اختيارية، ويتم ضبطها تلقائيًا على "false". قيمة منطقية لمطالبة المستخدم باختيار حساب. |
error_callback |
اختياريّ. وظيفة JavaScript التي تعالج بعض الأخطاء غير المتعلقة ببروتوكول OAuth، مثل
تعذُّر فتح النافذة المنبثقة، أو إغلاقها قبل عرض استجابة OAuth.
يقدّم الحقل "type" لمَعلمة الإدخال السبب التفصيلي.
|
نوع البيانات: CodeClient
تحتوي الفئة على قيمة requestCode واحدة للطريقة العامة، والتي تبدأ مسار تجربة المستخدم لرمز OAuth 2.0.
interface CodeClient {
requestCode(): void;
}
نوع البيانات: CodeResponse
سيتم تمرير كائن JavaScript CodeResponse
إلى طريقة callback
في النافذة المنبثقة 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 |
يجب ملء هذا الحقل. معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في وحدة تحكّم واجهة برمجة التطبيقات. |
callback |
يجب ملء هذا الحقل. دالة JavaScript التي تتعامل مع استجابة الرمز المميز المعروض. |
scope |
يجب ملء هذا الحقل. قائمة بالنطاقات المفصولة بمسافات والتي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتوضِّح هذه القيم شاشة طلب الموافقة التي تعرضها Google للمستخدم. |
include_granted_scopes |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . للسماح للتطبيقات باستخدام التفويض المتزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة هذه المَعلمة على false وتم منح طلب التفويض، لن يشمل رمز الدخول الجديد سوى النطاقات التي طلب scope استخدامها في TokenClientConfig .
|
prompt |
ويتم ضبط الإعداد التلقائي على 'select_account'. هي قائمة بالطلبات التي يتم تقديمها للمستخدم مع الفصل بينها بمسافات والحساسة لحالة الأحرف. القيم المتاحة:
|
enable_granular_consent |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . أمّا في حال ضبط السياسة على false ، فسيتم إيقاف أذونات أكثر دقة لحساب Google
لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. في حال ضبط كل من enable_granular_consent وenable_serial_consent ، سيتم تطبيق قيمة enable_granular_consent فقط ويتم تجاهل قيمة enable_serial_consent .ما مِن تأثير لمعرّفات عملاء OAuth الأحدث، لأنّه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها. |
enable_serial_consent |
تم إيقاف العمل بها، لذا يجب استخدام السمة enable_granular_consent بدلاً منها. ويؤدي هذا الإجراء
إلى التأثير نفسه الناتج عن enable_granular_consent . ويمكن للتطبيقات الحالية التي تستخدم enable_serial_consent مواصلة استخدامها، ولكن ننصحك
بتحديث الرمز الخاص بك لاستخدام enable_granular_consent في
التحديث التالي للتطبيق.
|
login_hint |
اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي يجب أن يصادق على الطلب، يمكنه استخدام هذه السمة لتقديم تلميح تسجيل الدخول إلى Google. عند نجاح هذا الإجراء، يتم تخطّي اختيار الحساب. تشير هذه السمة إلى قيمة الحقل sub لعنوان البريد الإلكتروني أو الرمز المميّز لرقم التعريف للمستخدم المستهدَف.
للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحقل login_hint في مستندات OpenID Connect.
|
hd |
اختياريّ. إذا كان تطبيقك يعرف نطاق Workspace الذي ينتمي إليه المستخدم، استخدِم هذا الإذن لتقديم تلميح إلى Google. عند نجاح هذا الإجراء، تقتصر حسابات المستخدمين على النطاق المقدَّم أو تكون محدّدة مسبقًا له.
للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحقل hd في مستندات OpenID Connect.
|
state |
اختياريّ. خيار غير مقترَح يحدّد هذا الإعداد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض. |
error_callback |
اختياريّ. وظيفة JavaScript التي تعالج بعض الأخطاء غير المتعلقة ببروتوكول OAuth، مثل
تعذُّر فتح النافذة المنبثقة، أو إغلاقها قبل عرض استجابة OAuth.
يقدّم الحقل "type" لمَعلمة الإدخال السبب التفصيلي.
|
نوع البيانات: TokenClient
تستخدم الفئة طريقة علنية واحدة فقط requestAccessToken
، وهي تبدأ مسار تجربة المستخدم للرمز المميز لـ OAuth 2.0.
interface TokenClient {
requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
الوسيطات | ||
---|---|---|
overrideConfig |
OverridableTokenClientConfig | اختياريّ. سيتم إلغاء الإعدادات بهذه الطريقة. |
نوع البيانات: OverridableTokenClientConfig
يسرد الجدول التالي خصائص نوع بيانات OverridableTokenClientConfig
.
أماكن إقامة | |
---|---|
scope |
اختياريّ. هذه قائمة بالنطاقات مع الفصل بينها بمسافات والتي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتوضّح هذه القيم شاشة طلب الموافقة التي يعرضها محرّك بحث Google للمستخدم. |
include_granted_scopes |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . للسماح للتطبيقات باستخدام التفويض المتزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة هذه المَعلمة على false وتم منح طلب التفويض، لن يشمل رمز الدخول الجديد سوى النطاقات التي طلب scope استخدامها في OverridableTokenClientConfig .
|
prompt |
اختياريّ. قائمة بالمطالبات التي يتم الفصل بينها بمسافات والحساسة لحالة الأحرف، والتي يتم خلالها تقديم المستخدم. |
enable_granular_consent |
إجراء اختياري، ويتم ضبطه تلقائيًا على true . أمّا في حال ضبط السياسة على false ، فسيتم إيقاف أذونات أكثر دقة لحساب Google
لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل 2019.وفي حال ضبط كل من enable_granular_consent وenable_serial_consent ، لن يسري
سوى قيمة enable_granular_consent وسيتم تجاهل قيمة enable_serial_consent .ما مِن تأثير لمعرّفات عملاء OAuth الأحدث، لأنّه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها. |
enable_serial_consent |
تم إيقاف العمل بها، لذا يجب استخدام السمة enable_granular_consent بدلاً منها. ويؤدي هذا الإجراء
إلى التأثير نفسه الناتج عن enable_granular_consent . ويمكن للتطبيقات الحالية التي تستخدم enable_serial_consent مواصلة استخدامها، ولكن ننصحك
بتحديث الرمز الخاص بك لاستخدام enable_granular_consent في
التحديث التالي للتطبيق.
|
login_hint |
اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي يجب أن يصادق على الطلب، يمكنه استخدام هذه السمة لتقديم تلميح تسجيل الدخول إلى Google. عند نجاح هذا الإجراء، يتم تخطّي اختيار الحساب. تشير هذه السمة إلى قيمة الحقل sub لعنوان البريد الإلكتروني أو الرمز المميّز لرقم التعريف للمستخدم المستهدَف.
للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحقل 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 |
سلسلة[] | اختياريّ. النطاقات الأخرى المطلوب التحقق منها. |
المرتجعات | |
---|---|
boolean | صحيح إذا تم منح جميع النطاقات. |
الطريقة: google.accounts.oauth2.hasGrantedAnyScope
للتحقق مما إذا كان المستخدم قد منح أي نطاق أو نطاقات محددة.
google.accounts.oauth2.hasGrantedAnyScope(
tokenResponse: TokenResponse,
firstScope: string, ...restScopes: string[]
): boolean;
الوسيطات | ||
---|---|---|
tokenResponse |
TokenResponse
|
يجب ملء هذا الحقل. عنصر TokenResponse :
|
firstScope |
سلسلة | يجب ملء هذا الحقل. النطاق المطلوب التحقّق منه. |
restScopes |
سلسلة[] | اختياريّ. النطاقات الأخرى المطلوب التحقق منها. |
المرتجعات | |
---|---|
boolean | صحيح إذا تم منح أي من النطاقات. |
الطريقة: google.accounts.oauth2.revoke
تُبطل طريقة revoke
جميع النطاقات التي منحها المستخدم للتطبيق.
يجب توفُّر رمز دخول صالح لإبطال الإذن.
google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
الوسيطات | ||
---|---|---|
accessToken |
سلسلة | يجب ملء هذا الحقل. رمز دخول صالح. |
callback |
function | اختياريّ. RevocationResponse |
نوع البيانات: RevocationResponse
سيتم تمرير عنصر JavaScript من RevocationResponse
إلى طريقة معاودة الاتصال التي تستخدمها.
يعرض الجدول التالي خصائص نوع بيانات RevocationResponse
.
أماكن إقامة | |
---|---|
successful |
منطقي. تم تنفيذ الإجراء على "true " بنجاح، و"false " عند تعذّر الإجراء. |
error |
سلسلة. غير محدّد عند النجاح. رمز خطأ ASCII فردي. ويشمل ذلك على سبيل المثال لا الحصر رموز خطأ OAuth 2.0 العادية. الأخطاء الشائعة في طريقة revoke :
|
error_description |
سلسلة. غير محدّد عند النجاح. يوفّر نص ASCII القابل للقراءة البشرية معلومات إضافية في السمة error . ويمكن لمطوّري البرامج استخدام هذه المعلومات لفهم الخطأ الذي حدث بشكل أفضل. تتوفّر سلسلة error_description باللغة الإنجليزية فقط.
بالنسبة إلى الأخطاء الشائعة الواردة في error السمة error_description المقابلة:
|