توضِّح صفحة الدليل التعليمي هذه في Cloud Search كيفية إعداد مصدر بيانات وموصّل محتوى لفهرسة البيانات. للبدء من بداية هذا الدليل التعليمي، يُرجى الرجوع إلى الدليل التعليمي لبدء استخدام Cloud Search.
إنشاء الموصِّل
غيِّر دليل العمل إلى cloud-search-samples/end-to-end/connector
directory ونفِّذ هذا الأمر:
mvn package -DskipTests
يعمل هذا الأمر على تنزيل التبعيات المطلوبة لإنشاء ملف "موصّل المحتوى" وترجمة الرمز البرمجي.
إنشاء بيانات اعتماد حساب الخدمة
يتطلّب أداة الربط بيانات اعتماد حساب الخدمة لاستدعاء واجهات برمجة تطبيقات Cloud Search. لإنشاء بيانات الاعتماد:
- ارجع إلى Google Cloud Console.
- في شريط التنقّل الأيمن، انقر على بيانات الاعتماد. تظهر صفحة "بيانات الاعتماد".
- انقر على القائمة المنسدلة + إنشاء بيانات اعتماد واختَر حساب الخدمة. تظهر صفحة "إنشاء حساب خدمة".
- في حقل اسم حساب الخدمة، أدخِل "tutorial".
- سجِّل قيمة رقم تعريف حساب الخدمة (بعد اسم حساب الخدمة مباشرةً). يتم استخدام هذه القيمة لاحقًا.
- انقر على إنشاء. يظهر مربّع الحوار "أذونات حساب الخدمة (اختيارية)".
- انقر على متابعة. يظهر مربّع الحوار "منح المستخدمين إذن الوصول إلى حساب الخدمة هذا (اختياري)".
- انقر على تم. تظهر شاشة "بيانات الاعتماد".
- ضمن "حسابات الخدمة"، انقر على عنوان البريد الإلكتروني لحساب الخدمة. تظهر صفحة "تفاصيل حساب العميل الخدمة".
- ضمن "المفاتيح"، انقر على القائمة المنسدلة إضافة مفتاح واختَر إنشاء مفتاح جديد. يظهر مربّع الحوار "إنشاء مفتاح خاص".
- انقر على إنشاء.
- (اختياري) إذا ظهر مربّع الحوار "هل تريد السماح بالتنزيلات على console.cloud.google.com؟"، انقر على السماح.
- يتم حفظ ملف المفتاح الخاص على جهاز الكمبيوتر. دوِّن الموقع الجغرافي للملف الذي تم تنزيله. يُستخدَم هذا الملف لضبط موصِّل المحتوى كي تتمكّن من مصادقة نفسها عند استدعاء Google Cloud Search APIs.
بدء دعم الجهات الخارجية
قبل أن تتمكّن من طلب أي واجهات برمجة تطبيقات أخرى لخدمة Cloud Search، عليك بدء تكامل Google Cloud Search مع خدمات تابعة لجهات خارجية.
لبدء استخدام ميزة "البحث في Cloud" مع تطبيقات تابعة لجهات خارجية، اتّبِع الخطوات التالية:
يحتوي مشروعك على منصة Cloud Search على بيانات اعتماد حساب الخدمة. ومع ذلك، لبدء استخدام ميزة الدعم التابع لجهة خارجية، عليك إنشاء بيانات اعتماد تطبيقات الويب. للحصول على تعليمات حول كيفية إنشاء بيانات اعتماد تطبيق الويب، يُرجى الرجوع إلى إنشاء بيانات الاعتماد. عند إكمال هذه الخطوة، من المفترض أن يكون لديك معرّف عميل وملف سر العميل.
استخدِم مساحة OAuth 2 في Google للحصول على رمز دخول:
- انقر على الإعدادات وضع علامة في المربّع بجانب استخدام بيانات اعتماد المصادقة الخاصة بك.
- أدخِل معرِّف العميل وسر العميل من الخطوة 1.
- انقر على إغلاق (Close).
- في حقل النطاقات، اكتب
https://www.googleapis.com/auth/cloud_search.settings
وانقر على تفويض. تعرِض ساحة OAuth 2 رمز تفويض. - انقر على Exchange authorization code for tokens (تبديل رمز التفويض بالرموز المميّزة). يتم عرض رمز مميّز.
لبدء استخدام واجهة برمجة التطبيقات التابعة لجهة خارجية مع Cloud Search، استخدِم الأمر curl التالي. احرص على استبدال
[YOUR_ACCESS_TOKEN]
بالرمز المميّز الذي تم الحصول عليه في الخطوة 2.curl --request POST \ 'https://cloudsearch.googleapis.com/v1:initializeCustomer' \ --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{}' \ --compressed
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال
operation
. على سبيل المثال:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" }
إذا لم تنجح هذه الخطوة، يُرجى التواصل مع فريق دعم Cloud Search.
استخدِم operations.get للتأكّد من أنّه تمت بدء معالجة طلبات المساعدة التابعة لجهات خارجية:
curl \ 'https://cloudsearch.googleapis.com/v1/operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY?key= [YOUR_API_KEY]' \ --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \ --header 'Accept: application/json' \ --compressed
عند اكتمال عملية الإعداد التابعة لجهة خارجية، يحتوي على حقل
done
الذي تم ضبطه علىtrue
. على سبيل المثال:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" done: true }
إنشاء مصدر البيانات
بعد ذلك، أنشئ مصدر بيانات في وحدة تحكّم المشرف. يقدّم مصدر البيانات مساحة اسم للفهرسة باستخدام الموصّل.
- افتح وحدة تحكّم المشرف في Google.
- انقر على رمز التطبيقات. تظهر صفحة "إدارة التطبيقات".
- انقر على Google Workspace. تظهر صفحة "إدارة تطبيقات Google Workspace".
- انتقِل إلى أسفل الصفحة وانقر على بحث السحابة الإلكترونية. تظهر صفحة "إعدادات Google Workspace" .
- انقر على مصادر بيانات الجهات الخارجية. تظهر صفحة "مصادر البيانات".
- انقر على الرمز الدائري الأصفر +. سيظهر مربّع الحوار "إضافة مصدر بيانات جديد".
- في حقل الاسم المعروض، اكتب "tutorial".
- في حقل عناوين البريد الإلكتروني لحساب الخدمة، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته في القسم السابق. إذا لم تكن تعرف عنوان البريد الإلكتروني لحساب الخدمة، ابحث عن القيمة في صفحة حسابات الخدمة.
- انقر على إضافة. يظهر مربّع الحوار "تمّ إنشاء مصدر البيانات بنجاح".
- انقر على حسنًا. دوِّن رقم تعريف المصدر لمصدر البيانات الذي تم إنشاؤه حديثًا. يُستخدَم معرّف المصدر لضبط موصِّل المحتوى.
إنشاء رمز مميّز شخصي للوصول إلى واجهة برمجة التطبيقات GitHub API
يتطلّب الموصّل الوصول المُعتمَد إلى واجهة برمجة التطبيقات GitHub API من أجل الحصول على حصة كافية. للتبسيط، يستخدم الموصّل رموًز دخول شخصية بدلاً من OAuth. تسمح الرموز المميّزة الشخصية بالمصادقة بصفته مستخدمًا لديه مجموعة محدودة من الأذونات تشبه OAuth.
- سجِّل الدخول إلى GitHub.
- في أعلى يسار الصفحة، انقر على صورة ملفك الشخصي. ستظهر قائمة منسدلة.
- انقر على الإعدادات.
- انقر على إعدادات المطوّر.
- انقر على رموز الوصول الشخصية.
- انقر على إنشاء رمز دخول شخصي.
- في حقل ملاحظة، أدخِل "دليل تعليمي حول Cloud Search".
- تحقَّق من نطاق public_repo.
- انقر على إنشاء رمز مميّز.
- دوِّن الرمز المميّز الذي تم إنشاؤه. ويستخدمه الموصّل لاستدعاء واجهات برمجة تطبيقات GitHub ويقدّم حصة واجهة برمجة التطبيقات لإجراء الفهرسة.
ضبط الموصّل
بعد إنشاء بيانات الاعتماد ومصدر البيانات، عدِّل إعدادات الموصِّل لتضمين القيم التالية:
- من سطر الأوامر، غيِّر الدليل إلى
cloud-search-samples/end-to-end/connector/
. - افتح ملف
sample-config.properties
باستخدام محرِّر نصوص. - اضبط المَعلمة
api.serviceAccountPrivateKeyFile
على مسار ملف بيانات اعتماد الخدمة التي نزّلتها سابقًا. - اضبط المَعلمة
api.sourceId
على معرّف مصدر البيانات الذي أنشأته سابقًا. - اضبط المَعلمة
github.user
على اسم المستخدم الخاص بك على GitHub. - اضبط المَعلمة
github.token
على رمز الدخول الذي أنشأته سابقًا. - احفظ الملف.
تعديل المخطّط
فهرس الموصّل كلّ من المحتوى المنظَّم وغير المنظَّم. قبل فهرسة البيانات، يجب تعديل مخطّط مصدر البيانات. نفِّذ الأمر التالي لتحديث المخطّط:
mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.SchemaTool \
-Dexec.args="-Dconfig=sample-config.properties"
تشغيل الموصِّل
لتشغيل الموصِّل وبدء الفهرسة، شغِّل الأمر التالي:
mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.GithubConnector \
-Dexec.args="-Dconfig=sample-config.properties"
الإعداد التلقائي للموصِّل هو فهرسة مستودع واحد
في مؤسسة googleworkspace
. تستغرق فهرسة المستودع دقيقة واحدة تقريبًا.
بعد الفهرسة الأولية، يواصل الموصّل الاستعلام عن التغييرات في
المستودع التي يجب أن تظهر في فهرس Cloud Search.
مراجعة الرمز
تتناول الأقسام المتبقية كيفية إنشاء الموصِّل.
بدء التطبيق
نقطة الدخول إلى الموصّل هي فئة GithubConnector
. تنشئ الطريقة
main
مثيلًا لـ IndexingApplication
الحزمة SDK وتبدأه.
إنّ ListingConnector
الذي تقدّمه حزمة SDK ينفّذ استراتيجية تنقّل
تستفيد من قوائم انتظار Cloud Search
لتتبُّع حالة العناصر في الفهرس. ويفوّض هذا الإجراء إلى GithubRepository
،
الذي ينفّذه موصل النماذج، للوصول إلى المحتوى من GitHub.
التنقّل في مستودعات GitHub
أثناء عمليات التنقّل الكاملة، يتمّ استدعاء الطريقة getIds()
لدفع العناصر التي قد تحتاج إلى فهرسة إلى قائمة الانتظار.
يمكن أن يفهرِس الموصِّل مستودعات أو مؤسسات متعددة. لتقليل أثر أيّ خطأ، يتمّ تصفّح مستودع GitHub واحد في كلّ مرّة. يتم عرض نقطة تفتيش
مع نتائج التنقّل التي تحتوي على قائمة
بالمستودعات التي سيتم فهرستها في عمليات الاتصال اللاحقة بخدمة getIds()
. في حال حدث خطأ، تتم استعادة الفهرسة في المستودع الحالي بدلاً من البدء مجددًا من البداية.
تعالج الطريقة collectRepositoryItems()
تنقّل ملف GitHub repo واحد. تعرض هذه الطريقة مجموعة من ApiOperations
التي تمثّل العناصر التي سيتم دفعها إلى "القائمة الانتظار". يتمّ دفع العناصر كاسم
مورد وقيمة تجزئة تمثّل الحالة الحالية للعنصر.
تُستخدَم قيمة التجزئة في عمليات التنقّل اللاحقة لمستودعات GitHub. توفّر هذه القيمة عملية تحقّق بسيطة لتحديد ما إذا كان المحتوى قد تغيّر بدون الحاجة إلى تحميل محتوى إضافي. يُضيف الموصّل جميع العناصر إلى "قائمة الانتظار" بدون تمييز. إذا كان العنصر جديدًا أو تغيّرت قيمة التجزئة، يتم جعله متاحًا للاستعلام في "القائمة الانتظار". وإلا، يتم اعتبار العنصر غير معدَّل.
معالجة قائمة المحتوى التالي
بعد اكتمال التنقّل الكامل، يبدأ الموصّل في الاستعلام عن السلسلة العميقة للعناصر التي يجب فهرستها. يتمّ استدعاء الطريقة getDoc()
لكلّ عنصر يتمّ سحبه من "القائمة الانتظار". تقرأ الطريقة
العنصر من GitHub وتحوّله إلى التمثيل المناسب
للفهرسة.
أثناء تشغيل الموصِّل على البيانات المباشرة التي يمكن تغييرها في أي
وقت، يتحقّق getDoc()
أيضًا من أنّ العنصر في "القائمة الانتظار" لا يزال صالحًا ويحذف أي عناصر من الفهرس لم تعُد متوفّرة.
لكل عنصر من عناصر GitHub التي يفهرسها الموصِّل، تتعامل طريقة
indexItem()
المقابلة مع إنشاء تمثيل العنصر لأجل
بحث Cloud. على سبيل المثال، لإنشاء تمثيل لعناصر المحتوى:
بعد ذلك، يمكنك نشر واجهة البحث.