ربط الحساب باستخدام بروتوكول OAuth

يتوافق نوع ربط حساب OAuth مع مسارَي OAuth 2.0 وفقًا للمعيار المتّبع في المجال، وهما مسار الربط الضمني ومسار رمز التفويض.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

تنفيذ عملية ربط حساب OAuth

ضبط إعدادات المشروع

لضبط مشروعك لاستخدام ميزة ربط الحسابات عبر OAuth، اتّبِع الخطوات التالية:

1. افتح Actions Console واختَر المشروع الذي تريد استخدامه.
2. انقر على علامة التبويب تطوير واختَر ربط الحساب.
3. فعِّل مفتاح التبديل بجانب ربط الحساب.
4. في قسم إنشاء الحساب، اختَر لا، أريد فقط السماح بإنشاء الحساب على موقعي الإلكتروني.

5. في نوع الربط، اختَر OAuth وضمنيّ.

   

6. في معلومات العميل:

   • عيِّن قيمة لمعرّف العميل الصادر عن "إجراءات على Google" لتحديد الطلبات الواردة من Google.
   • أدرِج عناوين URL لنقاط نهاية التفويض وتبادل الرموز المميزة.

6. انقر على حفظ.

تنفيذ خادم OAuth

لدعم تدفق OAuth 2.0 الضمني، تُجري خدمتك تفويضًا. نقطة النهاية متوفرة عبر HTTPS. نقطة النهاية هذه مسؤولة عن مصادقة الحصول على موافقة من المستخدمين للوصول إلى البيانات. نقطة نهاية التفويض توفّر واجهة مستخدم لتسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول إلى حساباتهم الموافقة على الوصول المطلوب.

عندما يحتاج الإجراء الخاص بك إلى استدعاء إحدى واجهات برمجة التطبيقات المعتمَدة لخدمتك، تستخدمها Google. نقطة النهاية هذه للحصول على إذن من المستخدمين بطلب واجهات برمجة التطبيقات هذه على بالنيابة عنك.

تتضمن جلسة مسار OAuth 2.0 الضمني النموذجية التي تبدأها Google التدفق التالي:

1. تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. تشير رسالة الأشكال البيانية تسجيل دخول المستخدم إذا لم يكن مسجّلاً الدخول، ويمنح Google إذنًا بالوصول بياناته من خلال واجهة برمجة التطبيقات إذا لم يسبق له منحها الإذن بذلك.
2. تنشئ الخدمة رمز دخول وتعيده إلى Google عن طريق إعادة توجيه متصفّح المستخدم إلى Google باستخدام رمز الدخول المرفق بالطلب.
3. تستدعي Google واجهات برمجة التطبيقات التابعة لخدمتك، وترفق رمز الدخول المميز لكل طلب. تتحقّق خدمتك من أنّ رمز الدخول يمنح Google. للوصول إلى واجهة برمجة التطبيقات ثم يُكمل طلب البيانات من واجهة برمجة التطبيقات.

التعامل مع طلبات التفويض

عندما يحتاج الإجراء الخاص بك إلى ربط الحساب من خلال مسار OAuth 2.0 الضمني، ترسل Google المستخدم إلى نقطة نهاية التفويض من خلال طلب يتضمن المعلمات التالية:

على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على https://myservice.example.com/auth، قد يبدو الطلب كما يلي:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

لكي تعالج نقطة نهاية التفويض طلبات تسجيل الدخول، عليك اتّباع الخطوات التالية:

1. يُرجى التحقّق من القيمتَين client_id وredirect_uri من أجل: منع منح الوصول إلى تطبيقات العميل غير المقصودة أو التي تم إعدادها بشكلٍ غير صحيح:

   • تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي أدخلته. تعيينه إلى Google.
   • تأكَّد من أنّ عنوان URL المحدّد من قِبل redirect_uri على النحو التالي:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID هو رقم التعريف الوارد في صفحة إعدادات المشروع. من وحدة التحكم في المهام.

2. تحقق مما إذا كان المستخدم قد سجّل الدخول إلى خدمتك. في حال لم يكن المستخدم مسجِّلاً الدخول أو أكمل عملية تسجيل الدخول أو الاشتراك في الخدمة.

3. أنشئ رمز الدخول المميز الذي ستستخدمه Google للوصول إلى واجهة برمجة التطبيقات الخاصة بك. تشير رسالة الأشكال البيانية يمكن أن يكون رمز الدخول أي قيمة سلسلة، ولكن يجب أن يمثل المستخدم والعميل الذي يرتبط به الرمز المميز ويجب ألا يكون من الممكن تخمينه.

4. إرسال استجابة HTTP تؤدي إلى إعادة توجيه متصفّح المستخدم إلى عنوان URL التي تحددها المعلمة redirect_uri. تضمين جميع المعلمات التالية في جزء عنوان URL:

   • access_token: رمز الدخول الذي أنشأته للتو
   • token_type: السلسلة bearer
   • state: قيمة الحالة غير المعدَّلة من القيمة الأصلية طلب في ما يلي مثال على عنوان URL الناتج:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

سيستلم معالج إعادة التوجيه OAuth 2.0 من Google رمز الدخول وسيتأكد من ذلك أن قيمة state لم تتغير. بعد حصول Google على رمز الدخول لخدمتك، فستلحق Google الرمز المميز بالمكالمات اللاحقة إلى الإجراء الخاص بك كجزء من AppRequest.

تصميم واجهة المستخدم الصوتية لمسار المصادقة

التحقّق من إثبات هوية المستخدم وبدء عملية ربط الحساب

1. افتح مشروعك في Actions Builder في Actions Console.
2. أنشئ مشهدًا جديدًا لبدء ربط الحساب في تطبيقك:
   1. انقر على المشاهد.
   2. انقر على رمز إضافة (+) لإضافة مشهد جديد.
3. في المشهد الذي تم إنشاؤه حديثًا، انقر على رمز الإضافة add الشروط.
4. أضِف شرطًا يتحقّق مما إذا كان المستخدم المرتبط بالمحادثة مستخدمًا تم التحقّق منه. إذا لم تنجح عملية التحقّق، لن تتمكّن مهمتك من ربط الحساب أثناء المحادثة، ويجب أن تعود إلى توفير إمكانية الوصول إلى الوظائف التي لا تتطلّب ربط الحساب.
   1. في الحقل Enter new expression ضِمن الشرط، أدخِل المنطق التالي: user.verificationStatus != "VERIFIED"
   2. ضمن الانتقال، اختَر مشهدًا لا يتطلّب ربط الحساب أو مشهدًا يشكّل نقطة دخول إلى الوظائف المتاحة للضيوف فقط.

1. انقر على رمز الإضافة add في الشروط.
2. أضِف شرطًا لتفعيل مسار ربط الحساب إذا لم يكن لدى المستخدم هوية مرتبطة.
   1. في الحقل Enter new expression ضِمن الشرط، أدخِل المنطق التالي: user.verificationStatus == "VERIFIED"
   2. ضمن الانتقال، اختَر مشهد نظام ربط الحساب.
   3. انقر على حفظ.

بعد الحفظ، تتم إضافة مشهد جديد لنظام ربط الحسابات باسم <SceneName>_AccountLinking إلى مشروعك.

تخصيص مشهد ربط الحساب

1. ضمن المشاهد، اختَر مشهد نظام ربط الحساب.
2. انقر على إرسال الطلب وأضِف جملة قصيرة لتوضيح سبب حاجة الإجراء إلى الوصول إلى هوية المستخدم (مثلاً "لحفظ إعداداتك المفضّلة").
3. انقر على حفظ.

1. ضمن الشروط، انقر على في حال أكمل المستخدم ربط الحساب بنجاح.
2. اضبط كيفية سير العملية إذا وافق المستخدم على ربط حسابه. على سبيل المثال، يمكنك استدعاء Webhook لمعالجة أي منطق مخصّص للنشاط التجاري مطلوب والعودة إلى المشهد الأصلي.
3. انقر على حفظ.

1. ضمن الشروط، انقر على في حال ألغى المستخدم ربط الحساب أو رفضه.
2. اضبط طريقة سير العملية إذا لم يوافق المستخدم على ربط حسابه. على سبيل المثال، أرسِل رسالة تأكيد وأعِد التوجيه إلى مشاهد توفّر وظائف لا تتطلّب ربط الحساب.
3. انقر على حفظ.

1. ضمن الشروط، انقر على في حال حدوث خطأ في النظام أو الشبكة.
2. اضبط كيفية سير العملية إذا تعذّر إكمال عملية ربط الحساب بسبب أخطاء في النظام أو الشبكة. على سبيل المثال، أرسِل رسالة تأكيد وأعِد التوجيه إلى مشاهد توفّر وظائف لا تتطلّب ربط الحساب.
3. انقر على حفظ.

التعامل مع طلبات الوصول إلى البيانات

إذا كان طلب "مساعد Google" يتضمّن رمز دخول، عليك أولاً التأكّد من أنّ رمز الدخول صالح (ولم تنتهِ صلاحيته)، ثم استرداد حساب المستخدم المرتبط من قاعدة البيانات.