Your Account Linking API

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

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

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

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

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

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

  • عنوان URL: يتم ضبطه في Actions Console أو 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).
code_challenge (مطلوب لبروتوكول OAuth 2.1) هو التحدّي المستمدّ من أداة التحقّق من الرمز.
code_challenge_method (اختياري) تمثّل هذه السمة الطريقة المستخدَمة لاشتقاق التحدي (مثل S256).

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

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

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

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

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

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

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

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

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

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

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

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

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

مخطط OpenAPI 3.1

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • حالة 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 وget، ويمكنك اختياريًا تنفيذ الغرض create.

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

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

المعلمات الوصف
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 على طلبها من المستخدمين. تظهر عادةً أثناء عمليات البحث التي تتضمّن نية الشراء أو نية التسوّق.getcreate
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 (اختياري)

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

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

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

إذا كان المستخدم موجودًا من قبل، أو إذا كانت خدمتك لا تتيح إنشاء حساب، سيتم عرض الخطأ HTTP 401 ليطلب من Google الرجوع إلى عملية الربط العادية باستخدام OAuth.

  • حالة 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

ردود الأخطاء

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

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