مرجع Google Account Authorization JavaScript API

يصف هذا المرجع واجهة برمجة التطبيقات Google Account Authorization JavaScript API، المستخدَمة للحصول على رموز تفويض أو رموز مميّزة للوصول من Google.

الطريقة: google.accounts.oauth2.initCodeClient

تُهيّئ الطريقة initCodeClient عميل الرمز وتعرضه، مع الإعدادات في المَعلمة.

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

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

يسرد الجدول التالي سمات نوع البيانات CodeClientConfig.

الخصائص
client_id مطلوبة. معرّف العميل لتطبيقك يمكنك العثور على هذه القيمة في API Console.
scope مطلوبة. قائمة مفصولة بمسافات تتضمّن النطاقات التي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. تُعلم هذه القيم شاشة الموافقة التي تعرضها Google للمستخدم.
include_granted_scopes اختياري، والقيمة التلقائية هي true. تتيح هذه السمة للتطبيقات استخدام المصادقة المتزايدة لطلب الوصول إلى نطاقات إضافية حسب السياق. إذا ضبطت قيمة هذه المَعلمة على false وتم منح طلب التفويض، سيشمل رمز الدخول الجديد أي نطاقات تم طلبها في scope ضمن هذا CodeClientConfig فقط.
redirect_uri مطلوبة لتجربة المستخدم الخاصة بإعادة التوجيه. تحدِّد هذه السمة المكان الذي يعيد خادم واجهة برمجة التطبيقات توجيه المستخدم إليه بعد إكمال عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المصرّح بها لإعادة التوجيه لعميل OAuth 2.0 الذي ضبطته في API Console، ويجب أن تتوافق مع قواعد التحقّق من صحة معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه. سيتجاهل تصميم تجربة المستخدم المنبثق هذه السمة.
callback مطلوب لتجربة المستخدم المنبثقة. دالة JavaScript التي تعالج استجابة الرمز المعروض. سيتجاهل تجربة المستخدم لإعادة التوجيه الموقع.
state اختياريّ. يُنصح باستخدام هذا الخيار لتحسين تجربة المستخدم عند إعادة التوجيه. تحدّد هذه السمة أي قيمة سلسلة تستخدمها تطبيقاتك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.
enable_granular_consent تم إيقاف هذه السياسة نهائيًا، ولن يكون لها أي تأثير في حال ضبطها. يمكنك الاطّلاع على الأذونات الدقيقة لمعرفة تفاصيل سلوك الموافقة.
enable_serial_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` الخاص بمَعلمة الإدخال السبب المفصّل.
  • popup_failed_to_open تعذّر فتح النافذة المنبثقة.
  • popup_closed: تم إغلاق النافذة المنبثقة قبل عرض ردّ OAuth.
  • unknown عنصر نائب للأخطاء الأخرى.

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

لا يحتوي الصف إلا على طريقة عامة واحدة، وهي requestCode، التي تبدأ مسار تجربة المستخدم لرمز OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

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

سيتم تمرير كائن CodeResponse JavaScript إلى طريقة 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 تم إيقاف هذه السياسة نهائيًا، ولن يكون لها أي تأثير في حال ضبطها. يمكنك الاطّلاع على الأذونات الدقيقة لمعرفة تفاصيل سلوك الموافقة.
enable_serial_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.
  • unknown عنصر نائب للأخطاء الأخرى.

نوع البيانات: 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 تم إيقاف هذه السياسة نهائيًا، ولن يكون لها أي تأثير في حال ضبطها. يمكنك الاطّلاع على الأذونات الدقيقة لمعرفة تفاصيل سلوك الموافقة.
enable_serial_consent تم إيقاف هذه السياسة نهائيًا، ولن يكون لها أي تأثير في حال ضبطها. يمكنك الاطّلاع على الأذونات الدقيقة لمعرفة تفاصيل سلوك الموافقة.
login_hint اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي يجب أن يمنح الإذن بالطلب، يمكنه استخدام هذه السمة لتقديم تلميح تسجيل دخول إلى Google. في حال نجاح العملية، يتم تخطّي خطوة اختيار الحساب. عنوان البريد الإلكتروني أو قيمة حقل رمز التعريف sub للمستخدم المستهدَف لمزيد من المعلومات، يُرجى الاطّلاع على حقل login_hint في مستندات OpenID Connect.
state اختياريّ. خيار غير مقترَح تحدّد هذه السمة أي قيمة سلسلة تستخدمها تطبيقاتك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.

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

سيتم تمرير كائن TokenResponse JavaScript إلى طريقة ردّ الاتصال في تجربة المستخدم المنبثقة.

يسرد الجدول التالي سمات نوع البيانات 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 string[] اختياريّ. نطاقات أخرى يجب التحقّق منها
المرتجعات
قيمة منطقية تعرض القيمة "صحيح" إذا تم منح جميع النطاقات.

الطريقة: google.accounts.oauth2.hasGrantedAnyScope

للتحقّق مما إذا كان المستخدم قد منح أيًا من النطاقات المحدّدة.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
الوسيطات
tokenResponse TokenResponse مطلوبة. كائن TokenResponse
firstScope سلسلة مطلوبة. نطاق التحقّق.
restScopes string[] اختياريّ. نطاقات أخرى يجب التحقّق منها
المرتجعات
قيمة منطقية تعرض القيمة "صحيح" إذا تم منح أي من النطاقات.

الطريقة: 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 - لا يمكن إبطال الرمز المميّز.