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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يصف هذا المرجع واجهة برمجة تطبيقات مكتبة جافا سكريبت لأطراف ثالثة في 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_serial_consent اختياري، يتم استخدام الإعدادات التلقائية لـ true. وفي حال ضبط هذه السياسة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. ليس هناك أي تأثير للأرقام التعريفية الأحدث لعملاء OAuth، نظرًا لأنه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها.
hint اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي عليه تفويض الطلب، فيمكنه استخدام هذه الخاصية لتقديم تلميح إلى Google. عنوان البريد الإلكتروني للمستخدم المستهدف. لمزيد من المعلومات، راجِع حقل login_hint في مستندات "اتصال OpenID".
hosted_domain اختياريّ. إذا كان تطبيقك يعرف نطاق Workspace الذي ينتمي إليه المستخدم، استخدِم هذا الحقل لتقديم تلميح إلى Google. لمزيد من المعلومات، راجِع حقل hd في مستندات "اتصال OpenID".
ux_mode اختياريّ. وضع تجربة المُستخدِم المطلوب استخدامه لتدفق التفويض. وسيؤدي هذا الإعداد تلقائيًا إلى فتح تدفق الموافقة في نافذة منبثقة. القيمتان الصالحتان هما popup وredirect.
select_account اختياري، يتم ضبط الإعدادات التلقائية على 'false'. قيمة منطقية لمطالبة المستخدم باختيار حساب.
error_callback اختياريّ. دالة جافا سكريبت التي تعالج بعض أخطاء بروتوكول OAuth، مثل النافذة المنبثقة غير ناجحة، أو مغلقة قبل عرض استجابة OAuth.

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

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

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

interface CodeClient {
  requestCode(): void;
}

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

سيتم تمرير كائن JavaScript 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_serial_consent اختياري، يتم استخدام الإعدادات التلقائية لـ true. وفي حال ضبط هذه السياسة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. ليس هناك أي تأثير للأرقام التعريفية الأحدث لعملاء OAuth، نظرًا لأنه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها.
hint اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي عليه تفويض الطلب، فيمكنه استخدام هذه الخاصية لتقديم تلميح إلى Google. عنوان البريد الإلكتروني للمستخدم المستهدف. لمزيد من المعلومات، راجِع حقل login_hint في مستندات "اتصال OpenID".
hosted_domain اختياريّ. إذا كان تطبيقك يعرف نطاق Workspace الذي ينتمي إليه المستخدم، استخدِم هذا الحقل لتقديم تلميح إلى Google. لمزيد من المعلومات، راجِع حقل hd في مستندات "اتصال OpenID".
state اختياريّ. خيار غير مقترَح لتحديد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.
error_callback اختياريّ. دالة جافا سكريبت التي تعالج بعض أخطاء بروتوكول OAuth، مثل النافذة المنبثقة غير ناجحة، أو مغلقة قبل عرض استجابة OAuth.

يعرض حقل "النوع" في معلمة الإدخال السبب التفصيلي.
  • 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_serial_consent اختياري، يتم استخدام الإعدادات التلقائية لـ true. وفي حال ضبط هذه السياسة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرِّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. ليس هناك أي تأثير للأرقام التعريفية الأحدث لعملاء OAuth، نظرًا لأنه يتم دائمًا تفعيل المزيد من الأذونات الدقيقة لها.
hint اختياريّ. إذا كان تطبيقك يعرف المستخدم الذي عليه تفويض الطلب، فيمكنه استخدام هذه الخاصية لتقديم تلميح إلى Google. عنوان البريد الإلكتروني للمستخدم المستهدف. لمزيد من المعلومات، راجِع حقل login_hint في مستندات "اتصال OpenID".
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 سلسلة[] اختياريّ. نطاقات أخرى للتحقق منها.
المرتجعات
منطقي True إذا تم منح جميع النطاقات.

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

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

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 سلسلة مطلوبة. رمز دخول صالح.
done الدالة اختياريّ. وظيفة معاودة الاتصال عند انتهاء إجراء الإلغاء.