custom web experience with amazon q business

تجربة ويب مخصصة مع Amazon Q Business

⚡ إذا قمت بإنشاء تطبيق Amazon Q Business جديد في 30 أبريل 2024 أو بعده، فيمكنك الآن إعداد واجهة مستخدم مخصصة باستخدام الإرشادات المحدثة الواردة أدناه.

ملاحظة: الإرشادات الواردة في هذا الدليل خاصة بـ Cognito، ولكن يجب أن تعمل أيضًا مع موفري الهوية الآخرين المتوافقين مع OIDC 2.0 مع تعديلات طفيفة.

غالبًا ما يرغب العملاء في القدرة على دمج الوظائف المخصصة في واجهة مستخدم Amazon Q، مثل التعامل مع التعليقات، واستخدام ألوان وقوالب الشركة، وتسجيل الدخول المخصص، وتقليل تبديل السياق من خلال دمج واجهة المستخدم في منصة واحدة. سيوضح مستودع التعليمات البرمجية كيفية دمج واجهة مستخدم مخصصة على Amazon Q باستخدام Amazon Cognito لمصادقة المستخدم وAmazon Q SDK لاستدعاء تطبيق chatbot برمجيًا، من خلال واجهة برمجة تطبيقات chat_sync.

‍ يتضمن سير العمل الخطوات التالية:

1. أولاً، يصل المستخدم إلى تطبيق chatbot، الذي تتم استضافته خلف Application Load Balancer.

2. يُطلب من المستخدم تسجيل الدخول باستخدام Cognito

3. يقوم تطبيق واجهة المستخدم بتبادل الرمز المميز من Cognito مع رمز IAM Identity Center مع نطاق Amazon Q

4. تفترض تطبيقات واجهة المستخدم دور IAM وتسترد جلسة AWS من Secure Token Service (STS)، معززة برمز IAM Identity Center للتفاعل مع Amazon Q

   • تم توضيح التدفق التفصيلي لتبادل الرمز المميز بين IAM Identity Center وIdp في منشورات المدونة أدناه

   ؟ المدونة 1

   ؟ المدونة 2

5. يستخدم Amazon Q واجهة برمجة تطبيقات ChatSync لإجراء المحادثة. بفضل جلسة التعرف على الهوية، تعرف Amazon Q المستخدم الذي تتفاعل معه.

   • يستخدم الطلب المعلمات الإلزامية التالية.

     1. applicationId : معرف تطبيق Amazon Q المرتبط بمحادثة Amazon Q.

     2. userMessage : رسالة المستخدم النهائي في المحادثة.

   • يقوم Amazon Q بإرجاع الاستجابة ككائن JSON (مفصل في وثائق Amazon Q) وفيما يلي بعض السمات الأساسية من حمولة الاستجابة.

     1. systemMessage : رسالة تم إنشاؤها بواسطة الذكاء الاصطناعي في محادثة

     2. sourceAttributions : المستندات المصدر المستخدمة لإنشاء استجابة المحادثة. في RAG (إنشاء تعزيز الاسترجاع)، يشير هذا دائمًا إلى مستند واحد أو أكثر من قواعد معارف المؤسسة التي تمت فهرستها في Amazon Q.

نشر هذا الحل

المتطلبات الأساسية:

قبل نشر هذا الحل، تأكد من إعداد المتطلبات الأساسية التالية:

• حساب AWS صالح.
• دور AWS Identity and Access Management (IAM) في الحساب الذي يتمتع بأذونات كافية لإنشاء الموارد اللازمة.
  إذا كان لديك حق وصول المسؤول إلى الحساب، فلا يلزم اتخاذ أي إجراء.
• تم إنشاء شهادة TLS واستيرادها إلى AWS Certified Manager (ACM).
  لمزيد من التفاصيل، راجع استيراد شهادة.
  إذا لم يكن لديك شهادة TLS عامة، فاتبع الخطوات الواردة في القسم التالي لمعرفة كيفية إنشاء شهادة خاصة.
• تطبيق Amazon Q موجود وعامل
• IAM Identity Center، وقم بإنشاء عدد قليل من المستخدمين في Identity Center عن طريق تكوين عنوان بريدهم الإلكتروني وأسمائهم

إنشاء شهادة خاصة

إذا كان لديك بالفعل شهادة TLS، فيمكنك تخطي هذا القسم.
ومع ذلك، إذا لم يكن لديك واحدة وتريد متابعة تشغيل هذا العرض التوضيحي، فيمكنك إنشاء شهادة خاصة مرتبطة بالمجال باستخدام أمر opensl التالي:

 openssl req 
  -x509 -nodes -days 365 -sha256 
  -subj '/C=US/ST=Oregon/L=Portland/CN=sampleexample.com' 
  -newkey rsa:2048 -keyout key.pem -out cert.pem

aws acm import-certificate --certificate fileb://cert.pem --private-key fileb://key.pem

➡️ يرجى ملاحظة أنك ستتلقى تحذيرًا من متصفحك عند الوصول إلى واجهة المستخدم إذا لم تقدم شهادة TLS مخصصة عند تشغيل AWS CloudFormation Stack. توضح لك الإرشادات المذكورة أعلاه كيفية إنشاء شهادة موقعة ذاتيًا، والتي يمكن استخدامها كنسخة احتياطية، ولكن بالتأكيد لا يُنصح بهذا في حالات استخدام الإنتاج.

يجب عليك الحصول على شهادة TLS التي تم التحقق من صحتها بواسطة مرجع مصدق، واستيرادها إلى AWS Certified Manager، والرجوع إليها عند تشغيل AWS CloudFormation Stack.

إذا كنت ترغب في الاستمرار في استخدام الشهادة الموقعة ذاتيًا (لأغراض التطوير)، فيجب أن تكون قادرًا على المتابعة بعد صفحة تحذير المتصفح. مع Chrome، ستشاهد رسالة الخطأ "اتصالك ليس خاصًا" (NET::ERR_CERT_AUTHORITY_INVALID)، ولكن بالنقر على "متقدم"، يجب أن ترى بعد ذلك رابطًا للمتابعة.

نشر هذا الحل:

الخطوة 1: قم بتشغيل قالب AWS CloudFormation التالي لنشر ELB ومجمع مستخدمي Cognito، بما في ذلك مثيل EC2 لاستضافة تطبيق الويب.

توفير المعلمات التالية للمكدس

• اسم المكدس – اسم مكدس CloudFormation (على سبيل المثال، AmazonQ-UI-Demo)

• AuthName – اسم فريد عالميًا لتعيينه لمجمع مستخدمي Amazon Cognito. يرجى التأكد من أن اسم النطاق الخاص بك لا يتضمن أي كلمات محجوزة، مثل cognito أو aws أو amazon.

• شهادة ARN – شهادة ARN التي تم إنشاؤها من الخطوة السابقة

• IdcApplicationArn - ARN لتطبيق عميل مركز الهوية، اتركه فارغًا عند التشغيل لأول مرة حيث نحتاج إلى إنشاء مجمع مستخدمين متخفيين كجزء من هذه المجموعة لإنشاء تطبيق IAM Identity Center مع مُصدر رمز مميز موثوق به

• PublicSubnetIds – معرفات الشبكات الفرعية العامة التي يمكن استخدامها لنشر مثيل EC2 وموازن تحميل التطبيق. الرجاء تحديد شبكتين فرعيتين عامتين على الأقل

• QApplicationId - معرف التطبيق الحالي لـ Amazon Q

• VPCID – معرف VPC الحالي الذي يمكن استخدامه لنشر العرض التوضيحي

؟ بمجرد اكتمال المكدس، انسخ المفتاح التالي من علامة التبويب "الإخراج".

الجمهور : الجمهور لإعداد تطبيق العميل في مركز الهوية

RoleArn : ARN لدور IAM المطلوب لإعداد تبادل الرمز المميز في مركز الهوية

TrustedIssuerUrl : نقطة نهاية المُصدر الموثوق به لإعداد مركز الهوية

عنوان URL : عنوان URL لموازن التحميل للوصول إلى التطبيق المبسط

الخطوة 2: إنشاء تطبيق مركز هوية IAM

• انتقل إلى AWS IAM Identity Center، وأضف تطبيقًا مُدارًا مخصصًا جديدًا.

  حدد نوع التطبيق -> ثم حدد OAuth2.0 -> التالي

  

  إذا لم تتمكن من العثور على خيار إنشاء تطبيق مُدار جديد مخصص، فيرجى تمكين المؤسسات باستخدام IAM Identity Center.

• أدخل اسم التطبيق ووصفه ثم حدد الخيار أدناه كما هو موضح في الصورة

  

• الآن قم بإنشاء مُصدر رمز مميز موثوق به

  

• في عنوان URL لجهة الإصدار -> قم بتوفير TrustedIssuerUrl من الخطوة 1، ثم قم بتوفير اسم جهة الإصدار واحتفظ بسمات الخريطة كبريد إلكتروني

  

• ثم انتقل مرة أخرى إلى إعدادات مصادقة تطبيق IAM Identity Center، وحدد مصدر الرمز المميز الموثوق به الذي تم إنشاؤه في الخطوة السابقة [قم بتحديثه إذا كنت لا ترى في القائمة] وأضف مطالبة Aud -> قم بتوفير الجمهور من الخطوة 1، ثم انقر فوق التالي

  

• في تحديد بيانات اعتماد التطبيق، أدخل أدوار IAM -> قم بتوفير RoleArn من الخطوة 1

  

• ثم قم بمراجعة جميع الخطوات وإنشاء التطبيق.

• بمجرد إنشاء التطبيق، انتقل إلى التطبيق ثم -> المستخدمون والمجموعات المعينة.

  

• ثم قم بإعداد التطبيق الموثوق به لنشر الهوية، واتبع الخطوات التالية إلى Amazon Q كتطبيقات موثوقة لنشر الهوية

  

الخطوة 4: بمجرد إنشاء تطبيق IAM Identity Center، انسخ Application ARN وانتقل إلى Cloudformation لتحديث المكدس الذي تم إنشاؤه مسبقًا. أدخل ARN لتطبيق مركز الهوية في المعلمة IdcApplicationArn وقم بتشغيل المكدس.

الخطوة 5: بمجرد اكتمال التحديث، انتقل إلى علامة تبويب إخراج Cloudformation لنسخ عنوان URL وفتح عنوان URL في المتصفح

الخطوة 6: سيطالبك تطبيق Streamlit بالاتصال بـ Cognito ، ولمحاولة تسجيل الدخول الأولى حاول التسجيل، استخدم نفس معرف البريد الإلكتروني وكلمة المرور للمستخدم الموجود بالفعل في IAM Identity Center.

⚡ للتخلص من الحاجة إلى توفير المستخدمين في كل من مجمع مستخدمي Cognito ومركز الهوية، يمكنك اتباع الرابط أدناه لإنشاء تطبيق مخصص ثانٍ (SAML) في مركز الهوية. سيكون هذا التطبيق المخصص بمثابة موفر الهوية لمجمع مستخدمي Cognito.

؟ فيديو

؟ تعليمات

اتصل بـ EC2 من خلال AWS Session Manager [اختياري]:

 sudo -i
cd /opt/custom-web-experience-with-amazon-q-business

استكشاف الأخطاء وإصلاحها

راجع استكشاف الأخطاء وإصلاحها لمزيد من المعلومات.

حماية

انظر المساهمة لمزيد من المعلومات.

رخصة

هذه المكتبة مرخصة بموجب ترخيص MIT-0. انظر ملف الترخيص.