توفر أداة البحث واجهة بحث قابلة للتخصيص لتطبيقات الويب. لا تتطلب الأداة سوى قدر صغير من HTML وجافا سكريبت لتنفيذ ميزات البحث الشائعة وتمكينها مثل الواجهات وتقسيم الصفحات. كما يمكنك تخصيص أجزاء من الواجهة باستخدام CSS وجافا سكريبت.
إذا كنت بحاجة إلى مرونة أكثر من الأداة، يمكنك استخدام واجهة برمجة تطبيقات طلب البحث. للحصول على معلومات عن إنشاء واجهة بحث باستخدام واجهة برمجة تطبيقات طلبات البحث، راجع إنشاء واجهة بحث باستخدام واجهة برمجة تطبيقات طلبات البحث.
إنشاء واجهة بحث
يتطلب إنشاء واجهة البحث عدة خطوات:
- تهيئة تطبيق بحث
- إنشاء معرِّف عميل للتطبيق
- إضافة ترميز HTML لمربع البحث والنتائج
- تحميل الأداة على الصفحة
- تهيئة الأداة
تهيئة تطبيق بحث
يجب أن يكون لكل واجهة بحث تطبيق بحث محدد في وحدة تحكم المشرف. يوفّر تطبيق البحث معلومات إضافية عن طلب البحث، مثل مصادر البيانات والواجهات وإعدادات جودة البحث.
لإنشاء تطبيق بحث، يمكنك الرجوع إلى إنشاء تجربة بحث مخصّصة.
إنشاء معرِّف عميل للتطبيق
بالإضافة إلى الخطوات الواردة في ضبط الوصول إلى واجهة برمجة تطبيقات Google Cloud Search، عليك أيضًا إنشاء معرِّف عميل لتطبيق الويب.
عند إعداد المشروع:
- اختر نوع برنامج متصفح الويب
- قدم معرّف الموارد المنتظم (URI) المصدر لتطبيقك.
- ملاحظة عن معرِّف العميل الذي تم إنشاؤه. ستحتاج إلى معرِّف عميل لإكمال الخطوات التالية. سر العميل غير مطلوب للأداة.
للحصول على معلومات إضافية، يُرجى الاطِّلاع على OAuth 2.0 لتطبيق الويب من جهة العميل.
إضافة ترميز HTML
تتطلب الأداة قدرًا صغيرًا من HTML لكي تعمل. يجب عليك تقديم:
- عنصر
input
لمربع البحث. - عنصر لتثبيت النافذة المنبثقة للاقتراح.
- عنصر يحتوي على نتائج البحث.
- (اختياري) قدِّم عنصرًا لاحتواء عناصر التحكم في الواجهات.
يعرض مقتطف HTML التالي رمز HTML لأداة بحث، حيث يتم تحديد العناصر المطلوب ربطها من خلال السمة id
:
تحميل الأداة
يتم تحميل الأداة ديناميكيًا عبر نص برمجي للقائم بالتحميل. لتضمين برنامج التحميل، استخدم علامة <script>
كما هو موضح:
يجب توفير رد اتصال onload
في علامة النص البرمجي. ويتم استدعاء الدالة
عندما يكون برنامج التحميل جاهزًا. عندما يكون برنامج التحميل جاهزًا، واصل تحميل الأداة من خلال استدعاء gapi.load()
لتحميل عميل واجهة برمجة التطبيقات، ووحدات تسجيل الدخول إلى Google، ووحدات Cloud Search.
يتم استدعاء الدالة initializeApp()
بعد تحميل جميع الوحدات.
تهيئة الأداة
عليك أولاً إعداد مكتبة العميل من خلال استدعاء
gapi.client.init()
أو gapi.auth2.init()
باستخدام معرِّف العميل الذي تم إنشاؤه
والنطاق https://www.googleapis.com/auth/cloud_search.query
. بعد ذلك، استخدم الصفين gapi.cloudsearch.widget.resultscontainer.Builder
وgapi.cloudsearch.widget.searchbox.Builder
لتهيئة الأداة وربطها بعناصر HTML.
يوضح المثال التالي كيفية تهيئة الأداة:
يشير المثال أعلاه إلى متغيرين للتهيئة تم تعريفهما كما يلي:
تخصيص تجربة تسجيل الدخول
تطالب الأداة تلقائيًا المستخدمين بتسجيل الدخول وتفويض التطبيق في الوقت الذي يبدأون فيه كتابة طلب البحث. يمكنك استخدام تسجيل الدخول بحساب Google للمواقع الإلكترونية لتقديم تجربة تسجيل دخول أكثر تخصيصًا للمستخدمين.
تفويض المستخدمين مباشرة
استخدم ميزة تسجيل الدخول باستخدام حساب Google لمراقبة حالة تسجيل الدخول لدى المستخدم
ومستخدمي تسجيل الدخول أو الخروج عند الحاجة. على سبيل المثال، يلاحظ المثال التالي الحالة isSignedIn
لمراقبة تغييرات تسجيل الدخول ويستخدم طريقة GoogleAuth.signIn()
لبدء تسجيل الدخول من خلال النقر على زر:
للحصول على تفاصيل إضافية، راجع تسجيل الدخول باستخدام Google.
تسجيل دخول المستخدمين تلقائيًا
يمكنك إجراء المزيد من الانسيابية في تجربة تسجيل الدخول من خلال السماح المسبق للتطبيق نيابة عن المستخدمين في مؤسستك. هذه التقنية مفيدة أيضًا في حالة استخدام Cloud Identity Aware Proxy لحماية التطبيق.
لمزيد من المعلومات، يُرجى الاطِّلاع على استخدام تسجيل الدخول بحساب Google مع تطبيقات تكنولوجيا المعلومات.
تخصيص الواجهة
يمكنك تغيير مظهر واجهة البحث من خلال مجموعة من الأساليب:
- إلغاء الأنماط باستخدام CSS
- تزيين العناصر باستخدام محوّل
- إنشاء عناصر مخصصة باستخدام محوّل
إلغاء الأنماط باستخدام CSS
يتم تقديم أداة البحث مع CSS الخاصة بها لتحديد النمط وعناصر النتائج، كما تتضمن عناصر التحكم في صفحات. يمكنك تغيير نمط هذه العناصر حسب الحاجة.
أثناء التحميل، تقوم أداة البحث بتحميل ورقة الأنماط الافتراضية الخاصة بها ديناميكيًا. يحدث ذلك بعد تحميل أوراق تطبيق، مما يزيد من أولوية القواعد. للتأكد من أن أنماطك الخاصة تحظى بالأولوية على الأنماط الافتراضية، استخدم محددات الأصل لزيادة خصوصية القواعد الافتراضية.
على سبيل المثال، لا يكون للقاعدة التالية أي تأثير إذا تم تحميلها في علامة link
أو style
ثابتة في المستند.
.cloudsearch_suggestion_container {
font-size: 14px;
}
وبدلاً من ذلك، يجب تأهيل القاعدة برقم التعريف أو فئة حاوية الأصل المذكورة في الصفحة.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
للحصول على قائمة بفئات الدعم ونموذج HTML الذي تم إنشاؤه بواسطة الأداة، راجع المرجع فئات CSS المدعومة.
تزيين العناصر باستخدام محوّل
لتزيين عنصر قبل العرض، عليك إنشاء محوّل يستخدم إحدى طرق التزيين وتسجيله، مثل decorateSuggestionElement
أو decorateSearchResultElement.
.
على سبيل المثال، تضيف المحوّلات التالية فئة مخصّصة إلى عناصر الاقتراحات والنتيجة.
لتسجيل المحوّل عند إعداد الأداة، استخدِم طريقة setAdapter()
لفئة Builder
المعنيّة:
قد يعدّل المصمِّمون سمات عنصر الحاوية بالإضافة إلى أي عناصر فرعية. يمكن إضافة العناصر الفرعية أو إزالتها أثناء عملية التزيين. ولكن إذا أردت إجراء تغييرات هيكلية على العناصر، ننصحك بإنشاء العناصر مباشرةً بدلاً من تزيينها.
إنشاء عناصر مخصصة باستخدام محوّل
لإنشاء عنصر مُخصَّص لاقتراح أو حاوية واجهة أو نتيجة بحث،
يمكنك إنشاء وتسجيل محوِّل ينفِّذ
createSuggestionElement
أو
createFacetResultElement
أو createSearchResultElement
بشكل تفاعلي.
توضح المحولات التالية إنشاء اقتراحات مخصصة وعناصر نتائج بحث باستخدام علامات HTML <template>
.
لإعادة ضبط المحوّل عند إعداد الأداة، استخدِم طريقة setAdapter()
لفئة Builder
المعنية:
يخضع إنشاء عناصر واجهة مخصّصة باستخدام createFacetResultElement
للعديد من القيود:
- يجب إرفاق فئة CSS
cloudsearch_facet_bucket_clickable
بالعنصر الذي ينقر عليه المستخدمون لتبديل إحدى الحزم. - يجب عليك لف كل مجموعة في عنصر يشتمل على فئة CSS
cloudsearch_facet_bucket_container
. - لا يمكنك عرض الحزم بترتيب مختلف عما تراه في الاستجابة.
على سبيل المثال، يعرض المقتطف التالي الواجهات باستخدام الروابط بدلاً من مربعات الاختيار.
تخصيص سلوك البحث
تمثل إعدادات تطبيق البحث التهيئة الافتراضية لواجهة بحث وهي ثابتة. لتنفيذ الفلاتر أو الواجهات الديناميكية، مثل السماح للمستخدمين بتبديل مصادر البيانات، يمكنك تجاوز إعدادات تطبيق البحث من خلال اعتراض طلب البحث باستخدام محوّل.
نفِّذ محوّلًا باستخدام طريقة
interceptSearchRequest
لتعديل الطلبات المقدّمة إلى
واجهة برمجة تطبيقات البحث
قبل التنفيذ.
على سبيل المثال، يعترض المحوّل التالي الطلبات لقصر طلبات البحث على مصدر يحدده المستخدم:
لتسجيل المحوّل عند إعداد الأداة، استخدِم طريقة
setAdapter()
أثناء إنشاء ResultsContainer
يتم استخدام رمز HTML التالي لعرض مربّع اختيار للفلترة حسب المصادر:
تراعي الشفرة التالية التغيير وتعيّن التحديد وتعيد تنفيذ طلب البحث إذا لزم الأمر.
يمكنك أيضًا اعتراض استجابة البحث من خلال تنفيذ
interceptSearchResponse
في المحوّل.
تثبيت إصدار واجهة برمجة التطبيقات
تستخدم الأداة تلقائيًا أحدث إصدار ثابت من واجهة برمجة التطبيقات. لقفل إصدار معيّن، اضبط معلمة ضبط cloudsearch.config/apiVersion
على الإصدار المفضّل قبل إعداد الأداة.
في حال تم ترك السياسة بدون ضبط أو تم ضبطها على قيمة غير صالحة، سيتم تلقائيًا ضبط إصدار واجهة برمجة التطبيقات على الإصدار 1.0.
تثبيت إصدار الأداة
ولتجنُّب حدوث تغييرات غير متوقعة في واجهات البحث، اضبط
معلّمة الضبط cloudsearch.config/clientVersion
على النحو التالي:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
وسيتم ضبط إصدار الأداة تلقائيًا على 1.0 في حال ترك هذه السياسة بدون ضبط أو تم ضبطها على قيمة غير صالحة.
تأمين واجهة البحث
تحتوي نتائج البحث على معلومات حساسة للغاية. اتبع أفضل الممارسات لتأمين تطبيقات الويب، خصوصًا ضد هجمات خداع.
لمزيد من المعلومات، راجع مشروع دليل OWASP
تفعيل تصحيح الأخطاء
استخدِم interceptSearchRequest
لتفعيل تصحيح الأخطاء في أداة البحث. مثلاً:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;