Your Account Linking API

تتضمّن صفحة المرجع هذه مستندات حول نقاط نهاية واجهة برمجة التطبيقات التي يجب أن تنفّذها خدمتك لإتاحة ربط الحسابات بخدمة Google. ويشمل ذلك ربط الحساب المستند إلى OAuth وربط الحساب المبسّط والتبديل السريع بين التطبيقات.

المتطلبات الأساسية والمعايير

لتنفيذ نقاط النهاية هذه بنجاح، يجب أن تلتزم خدمتك بالمعايير التالية:

  • بروتوكول OAuth 2.0: متوافق مع RFC 6749.
  • إبطال الرمز المميز: متوافق مع RFC 7009.
  • رموز JSON المميزة للويب (JWT): متوافقة مع RFC 7519 (مطلوبة لتفعيل ميزة "الربط السلس").
  • HTTPS: يجب عرض جميع نقاط النهاية عبر اتصال HTTPS آمن.

نقطة نهاية التفويض

نقطة نهاية التفويض مسؤولة عن مصادقة المستخدمين والحصول على موافقتهم لربط حساباتهم بحسابات Google.

  • عنوان URL: يتم ضبطه في وحدة تحكّم المهام أو Google Cloud Console.
  • الطريقة: GET

مَعلمات الطلب

المعلمات الوصف
client_id معرّف العميل الذي خصّصته لـ Google.
redirect_uri عنوان URL الذي سترسل إليه الردّ على هذا الطلب.
state قيمة مسك الدفاتر يتم إرجاعها إلى Google بدون تغيير في معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه.
response_type يجب أن تكون القيمة code لمسار رمز التفويض.
scope (اختياري) قائمة بنطاقات البيانات التي تطلبها Google، مع الفصل بينها بمسافات
user_locale (اختياري) إعدادات اللغة في حساب Google، ويتم تحديدها باستخدام علامة لغة BCP-47 (مثل en-US).

نقطة نهاية تبادل الرموز المميزة

نقطة النهاية هذه مسؤولة عن تبديل رموز التفويض برموز مميّزة وتحديث رموز الدخول المنتهية الصلاحية.

  • عنوان URL: يتم ضبطه في وحدة تحكّم المهام أو Google Cloud Console.
  • الطريقة: POST
  • Content-Type: application/x-www-form-urlencoded

تبديل رمز التفويض بالرموز المميّزة

يتم استخدام المَعلمات التالية في طلب تبادل الرموز المميزة الأوّلي.

مَعلمات الطلب

المعلمات الوصف
client_id معرّف العميل الذي خصّصته لـ Google.
client_secret سرّ العميل الذي خصّصته لـ Google.
grant_type يجب أن تكون authorization_code.
code رمز التفويض الذي تم تلقّيه من نقطة نهاية التفويض
redirect_uri عنوان URI لإعادة التوجيه نفسه المستخدَم في الطلب الأوّلي

استبدال الرمز المميز لإعادة التحميل برمز الدخول

يتم استخدام المَعلمات التالية عند إعادة تحميل رمز الدخول.

مَعلمات الطلب

المعلمات الوصف
client_id معرّف العميل الذي خصّصته لـ Google.
client_secret سرّ العميل الذي خصّصته لـ Google.
grant_type يجب أن تكون refresh_token.
refresh_token الرمز المميز لإعادة التحميل الذي تم إصداره سابقًا إلى Google

الاستجابة (JSON)

إرجاع استجابة ناجحة مع عنصر JSON في نص استجابة HTTPS

  • حالة HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
الحقول الوصف
token_type مطلوبة. يجب أن تكون bearer.
access_token مطلوبة. رمز مميز قصير الأمد يُستخدَم للوصول إلى واجهات برمجة التطبيقات الخاصة بخدمتك.
refresh_token مطلوبة لـ authorization_code grant_type. رمز مميّز طويل الأمد يُستخدَم للحصول على رموز دخول جديدة.
expires_in مطلوبة. تعرض هذه السمة المدة المتبقية لصلاحية رمز الدخول بالثواني.

الردود التي تتضمّن أخطاء

في حال تعذُّر إرسال طلب إلى نقطة نهاية الرمز المميز، يجب عرض الخطأ HTTP 400 Bad Request مع استجابة JSON تحتوي على الحقول التالية:

  • حالة HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
حقول الخطأ (JSON) الوصف
error مطلوبة. يجب أن تكون invalid_grant.
error_description (اختياري) نص يمكن لشخص عادي قراءته يقدّم معلومات إضافية.

التعامل مع أغراض الربط السلس

إذا كانت خدمتك تتيح ربط الحسابات بسلاسة (بروتوكول OAuth مع ميزة "تسجيل الدخول باستخدام Google")، يجب أن تتيح نقطة نهاية تبادل الرموز المميزة أيضًا تأكيدات JSON Web Token (JWT) وتنفيذ أغراض check وcreate وget.

تُستخدَم المَعلمات التالية في هذه الطلبات:

مَعلمات الطلب

المعلمات الوصف
intent الغرض المحدّد من الربط المبسّط المطلوب: check أو get أو create
grant_type بالنسبة إلى هذه الطلبات، تكون قيمة هذه المَعلمة دائمًا urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion رمز JSON المميّز للويب (JWT) يقدّم تأكيدًا موقّعًا لهوية مستخدم Google. يحتوي رمز JWT على معلومات تتضمّن رقم تعريف حساب المستخدم على Google واسمه وعنوان بريده الإلكتروني.

يجب أن يتحقّق الخادم من صحة رمز JWT هذا باستخدام المعايير الواردة في قسم التحقّق من صحة رمز JWT.
client_id معرّف العميل الذي خصّصته لـ Google.
client_secret سرّ العميل الذي خصّصته لـ Google.
scope اختياري: أي نطاقات ضبطت Google على طلبها من المستخدمين. تظهر عادةً أثناء طلبات البحث التي تتضمّن get وcreate.
response_type مطلوب لغرض create: يجب ضبطه على token.

التحقّق من صحة رمز JWT

لضمان أمان عملية الربط السلس، يجب أن يتحقّق الخادم من صحة assertion (رمز JWT) باستخدام المعايير التالية:

  • التوقيع: تحقَّق من التوقيع باستخدام المفاتيح العامة من Google (المتاحة في نقطة نهاية JWK من Google).
  • جهة الإصدار (iss): يجب أن تكون https://accounts.google.com.
  • الجمهور (aud): يجب أن يتطابق مع معرّف عميل Google API المخصّص لعملية الدمج.
  • تاريخ انتهاء الصلاحية (exp): يجب أن يكون في المستقبل.

الردّ على الطلب الذي يهدف إلى check

يتحقّق الطلب الذي يتضمّن intent=check مما إذا كان حساب Google (المحدّد بواسطة المطالبة sub أو email في تأكيد JWT الذي تم فك ترميزه) متوفّرًا في قاعدة بيانات المستخدمين.

  • حالة HTTP: 200 OK (تم العثور على الحساب) أو 404 Not Found (لم يتم العثور على الحساب)
  • Content-Type: application/json;charset=UTF-8
الحقول الوصف
account_found مطلوبة. true إذا كان الحساب متوفّرًا، false في الحالات الأخرى

الردّ على الطلب الذي يهدف إلى get

يطلب طلب يتضمّن intent=get رمز دخول لحساب Google حالي.

  • حالة HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

يستخدم عنصر JSON للاستجابة الناجحة البنية نفسها تمامًا كما في استجابة تبادل الرموز المميزة العادية الناجحة (مع عرض access_token وrefresh_token وما إلى ذلك).

إذا تعذّر ربط الحساب، سيتم عرض الخطأ HTTP 401.

  • حالة HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
حقول الخطأ (JSON) الوصف
error مطلوبة. يجب أن تكون linking_error.
login_hint (اختياري) عنوان البريد الإلكتروني للمستخدم الذي سيتم تمريره إلى مسار الربط الاحتياطي عبر OAuth.

الردّ على الطلب الذي يهدف إلى create

يطلب طلب يتضمّن intent=create إنشاء حساب مستخدم جديد باستخدام المعلومات المقدَّمة في رمز JWT.

  • حالة HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

يستخدم عنصر JSON للاستجابة الناجحة البنية نفسها تمامًا كما في استجابة تبادل الرموز المميزة العادية الناجحة (مع عرض access_token وrefresh_token وما إلى ذلك).

إذا كان المستخدم موجودًا من قبل، سيتم عرض الخطأ HTTP 401 ليُطلب من المستخدم ربط حسابه الحالي.

  • حالة HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
حقول الخطأ (JSON) الوصف
error مطلوبة. يجب أن تكون linking_error.
login_hint عنوان البريد الإلكتروني للمستخدم الذي سيتم تمريره إلى مسار الربط الاحتياطي عبر OAuth.

نقطة نهاية UserInfo (اختيارية)

تُستخدَم لاسترداد معلومات الملف الشخصي الأساسية الخاصة بالمستخدم المرتبط، كما هو موضّح في مواصفات OpenID Connect Core 1.0. هذا الإجراء مطلوب لميزات مثل "الربط السلس" أو "تسجيل الدخول باستخدام ميزة "نقرة واحدة"".

  • الطريقة: GET
  • المصادقة: Authorization: Bearer ACCESS_TOKEN

الاستجابة (JSON)

إرجاع استجابة ناجحة مع عنصر JSON في نص استجابة HTTPS

  • حالة HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

حقول الردّ

الحقول الوصف
sub مطلوبة. معرّف فريد يحدّد هوية المستخدِم في نظامك.
email مطلوبة. عنوان البريد الإلكتروني للمستخدِم
email_verified مطلوبة. قيمة منطقية تشير إلى ما إذا تم تأكيد عنوان البريد الإلكتروني.
given_name (اختياري) الاسم الأول للمستخدم.
family_name (اختياري) اسم عائلة المستخدم.
name (اختياري) الاسم الكامل للمستخدم.
picture (اختياري) عنوان URL لصورة الملف الشخصي للمستخدم

الردود التي تتضمّن أخطاء

إذا كان رمز الدخول غير صالح أو انتهت صلاحيته، يجب عرض الخطأ HTTP 401 Unauthorized. يجب أيضًا تضمين عنوان الاستجابة WWW-Authenticate.

يُعدّ أي ردّ غير ناجح (4xx أو 5xx) يتم عرضه أثناء عملية الربط مع حساب حالي غير قابل للاسترداد. في هذه الحالات، ستتجاهل Google أي رموز مميّزة تم استردادها، وسيكون على المستخدم بدء عملية الربط مع حساب حالي مرة أخرى.

نقطة نهاية إبطال الرمز المميز (اختياري)

تسمح هذه السمة لـ Google بإرسال إشعار إلى خدمتك عندما يلغي المستخدم ربط حسابه بسطح Google. يجب أن تستوفي نقطة النهاية هذه المتطلبات الموضّحة في RFC 7009.

  • الطريقة: POST
  • Content-Type: application/x-www-form-urlencoded

مَعلمات الطلب

المعلمات الوصف
client_id سلسلة تحدّد مصدر الطلب على أنّه Google. يجب تسجيل هذه السلسلة في نظامك كمعرّف فريد خاص بـ Google.
client_secret سلسلة سرية سجّلتها باستخدام Google للخدمة التي تقدّمها.
token الرمز المميّز المطلوب إبطاله
token_type_hint (اختياري) تلميح حول نوع الرمز المميّز الذي يتم إبطاله، إما access_token أو refresh_token. إذا لم يتم تحديدها، تكون القيمة التلقائية access_token.

الردود

يجب عرض استجابة ناجحة عند حذف الرمز المميّز بنجاح أو إذا كان الرمز المميّز غير صالح.

  • حالة HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

الردود التي تتضمّن أخطاء

إذا تعذّر حذف الرمز المميّز لأي سبب (مثل عدم توفّر قاعدة البيانات)، يجب عرض الخطأ 503 في بروتوكول نقل الروابط النصية (HTTP). ستعيد Google محاولة الطلب لاحقًا أو وفقًا لما يحدّده العنوان Retry-After.

  • حالة HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • العناوين: Retry-After: <HTTP-date / delay-seconds>