مكتبة JavaScript لتفويض الجهات الخارجية من Google للمواقع الإلكترونية - مرجع واجهة برمجة التطبيقات

يصف هذا المرجع واجهة برمجة تطبيقات مكتبة JavaScript لتفويض الجهات الخارجية من Google، التي يمكنك استخدامها لتحميل رموز التفويض أو رموز الدخول من 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 مطلوبة لتجربة المستخدم لإعادة التوجيه. تحدِّد هذه السياسة أماكن إعادة توجيه خادم واجهة برمجة التطبيقات للمستخدم بعد أن يكمل المستخدم مسار التفويض. يجب أن تتطابق القيمة بشكل تام مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل OAuth 2.0، الذي ضبطته في وحدة تحكم واجهة برمجة التطبيقات ويجب أن تتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) لإعادة التوجيه. ستتجاهل نافذة "تجربة المستخدم" المنبثقة هذه السمة.
callback مطلوب لتجربة المستخدم المنبثقة. دالة 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 اختياريّ. وضع تجربة المستخدم (UX) المطلوب استخدامه لتدفق التفويض. سيتم تلقائيًا فتح مسار الموافقة في نافذة منبثقة. القيمتان الصالحتان هما popup وredirect.
select_account اختياري، القيمة التلقائية هي 'false'. قيمة منطقية لمطالبة المستخدم باختيار حساب
error_callback اختياريّ. دالة JavaScript التي تتعامل مع بعض الأخطاء التي لا تتبع OAuth، مثل فشل فتح النافذة المنبثقة؛ أو إغلاقه قبل بدء استجابة OAuth عاد.

يقدّم الحقل "type" لمَعلمة الإدخال السبب التفصيلي.
  • popup_failed_to_open تعذّر فتح النافذة المنبثقة.
  • popup_closed يتم إغلاق النافذة المنبثقة قبل بدء OAuth. يتم إرجاع الاستجابة.
  • غير معروف عنصر نائب للأخطاء الأخرى.

نوع البيانات: CodeClient

تتضمن الفئة طريقة عامة واحدة requestCode واحدة تبدأ تشغيل OAuth 2.0. تدفق تجربة المستخدم للتعليمة البرمجية.

interface CodeClient {
  requestCode(): void;
}

نوع البيانات: CodeResponse

سيتم تمرير كائن JavaScript CodeResponse إلى طريقة callback في نافذة تجربة المستخدم المنبثقة. في تجربة المستخدم لإعادة التوجيه، سيتم تمرير 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'. ملف محدد بمسافات، قائمة برسائل طلب حسّاسة لحالة الأحرف لتقديمها إلى المستخدم القيم المتاحة:
  • سلسلة فارغة لن يُطلب من المستخدم سوى في المرة الأولى التي يطلب فيها تطبيقك إذن الوصول. لا يمكن تحديدها بقيم أخرى.
  • 'none' لا تعرض أي شاشات مصادقة أو موافقة. يجب ألا يتم تحديده مع قيم أخرى.
  • 'consent' لطلب الموافقة من المستخدِم.
  • '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" لمَعلمة الإدخال السبب التفصيلي.
  • popup_failed_to_open تعذّر فتح النافذة المنبثقة.
  • popup_closed يتم إغلاق النافذة المنبثقة قبل بدء OAuth. يتم إرجاع الاستجابة.
  • غير معروف عنصر نائب للأخطاء الأخرى.

نوع البيانات: 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 إلى طريقة معاودة الاتصال في نافذة تجربة المستخدم المنبثقة.

يسرد الجدول التالي خصائص نوع البيانات 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 بيانات اعتماد صالحة لبروتوكول OAuth 2.0 في Google.
error_description سلسلة. غير محدَّد عند النجاح. يوفر نص ASCII الذي يفهمه الإنسان معلومات إضافية عن الموقع: error. يمكن للمطوّرين استخدام هذه المعلومات للتعرّف بشكل أفضل على الخطأ الذي حدث. تتوفّر السلسلة error_description باللغة الإنجليزية فقط. بالنسبة إلى الأخطاء الشائعة الواردة في error، error_description المقابلة:
  • invalid_token - انتهت صلاحية الرمز المميّز أو تم إبطاله.
  • invalid_request - الرمز المميّز غير قابل للإلغاء.