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

يوضّح هذا المرجع واجهة برمجة التطبيقات Google 3P Authorization 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	مطلوبة لتجربة إعادة التوجيه لتحديد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد إكمال المستخدم عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل OAuth 2.0 الذي ضبطته في "وحدة تحكّم واجهة برمجة التطبيقات"، ويجب أن تكون متوافقة مع قواعد التحقّق من معرّف الموارد المنتظم (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 Code.

interface CodeClient {
  requestCode(): void;
}

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

سيتم تمرير كائن JavaScript من النوع CodeResponse إلى طريقة callback في تجربة المستخدم للنافذة المنبثقة. في تجربة إعادة التوجيه، سيتمّ تمرير CodeResponse كمَعلمات عنوان URL.

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

الخصائص
code	رمز التفويض لردّ رمز مميّز ناجح
scope	قائمة مفصولة بمسافات لنطاقات المستخدم الموافَق عليها
state	قيمة السلسلة التي يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض والاستجابة.
error	رمز خطأ واحد بترميز ASCII
error_description	نص ASCII سهل القراءة يقدّم معلومات إضافية، ويُستخدَم لمساعدة مطوّر العميل في فهم الخطأ الذي حدث.
error_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

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

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

الخصائص
access_token	رمز دخول استجابة رمز الدخول الناجحة
expires_in	مدة صلاحية رمز الوصول بالثواني
hd	النطاق المستضاف الذي ينتمي إليه المستخدم الذي سجّل الدخول
prompt	قيمة الطلب التي تم استخدامها من قائمة القيم المحتملة التي حدّدها TokenClientConfig أو OverridableTokenClientConfig.
token_type	نوع الرمز المميّز الذي تم إصداره
scope	قائمة مفصولة بمسافات لنطاقات المستخدم الموافَق عليها
state	قيمة السلسلة التي يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض والاستجابة.
error	رمز خطأ واحد بترميز ASCII
error_description	نص ASCII سهل القراءة يقدّم معلومات إضافية، ويُستخدَم لمساعدة مطوّر العميل في فهم الخطأ الذي حدث.
error_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 - الرمز المميّز لا يمكن إبطاله.