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

يصف هذا المرجع واجهة برمجة تطبيقات 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" لمَعلمة الإدخال السبب التفصيلي.
  • popup_failed_to_open تعذّر فتح النافذة المنبثقة.
  • popup_closed؛ يتم إغلاق النافذة المنبثقة قبل عرض استجابة OAuth.
  • غير معروف عنصر نائب للأخطاء الأخرى.

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