تعرض هذه الصفحة من برنامج Cloud Search التعليمي كيفية إعداد مصدر بيانات وموصِّل محتوى لفهرسة البيانات. للبدء من بداية هذا البرنامج التعليمي، راجِع الدليل التعليمي حول بدء استخدام Cloud Search
بناء الموصل
غيِّر دليل العمل إلى دليل cloud-search-samples/end-to-end/connector
وشغِّل الأمر التالي:
mvn package -DskipTests
يقوم الأمر بتنزيل التبعيات المطلوبة اللازمة لإنشاء موصل المحتوى وتجميع التعليمات البرمجية.
إنشاء بيانات اعتماد لحساب الخدمة
يتطلب الموصِّل بيانات اعتماد حساب الخدمة لطلب واجهات برمجة تطبيقات Cloud Search. لإنشاء بيانات الاعتماد:
- ارجِع إلى وحدة تحكُّم Google Cloud.
- في شريط التنقل الأيمن، انقر على بيانات الاعتماد. ستظهر لك صفحة "بيانات الاعتماد".
- انقر على القائمة المنسدلة + إنشاء بيانات الاعتماد واختَر حساب الخدمة. ستظهر لك صفحة "إنشاء حساب خدمة".
- في الحقل اسم حساب الخدمة، أدخِل "البرنامج التعليمي".
- دوِّن قيمة رقم تعريف حساب الخدمة (بعد اسم حساب الخدمة مباشرةً). يتم استخدام هذه القيمة لاحقًا.
- انقر على إنشاء. سيظهر مربّع الحوار "أذونات حساب الخدمة (اختيارية)".
- انقر على متابعة. سيظهر مربّع الحوار "منح المستخدمين إذن الوصول إلى حساب الخدمة هذا (اختياري)".
- انقر على تم. ستظهر شاشة "بيانات الاعتماد".
- ضِمن "حسابات الخدمة"، انقر على البريد الإلكتروني لحساب الخدمة. تظهر صفحة "تفاصيل حساب الخدمة".
- ضمن "المفاتيح"، انقر على القائمة المنسدلة إضافة مفتاح واختَر إنشاء مفتاح جديد. سيظهر مربع الحوار "إنشاء مفتاح خاص".
- انقر على إنشاء.
- (اختياري) إذا ظهر مربع الحوار "هل تريد السماح بعمليات التنزيل على console.cloud.google.com؟"، انقر على السماح.
- يتم حفظ ملف مفتاح خاص على جهاز الكمبيوتر. لاحظ موقع الملف الذي تم تنزيله. يُستخدم هذا الملف لإعداد موصِّل المحتوى حتى يمكنه مصادقة نفسه عند استدعاء واجهات برمجة تطبيقات Google Cloud Search.
تهيئة دعم الجهات الخارجية
قبل أن تتمكن من طلب أي واجهات برمجة تطبيقات أخرى في Cloud Search، عليك إعداد دعم الجهات الخارجية لخدمة Google Cloud Search.
لإعداد دعم الجهات الخارجية في Cloud Search:
يحتوي مشروع منصة Cloud Search على بيانات اعتماد حساب الخدمة. ومع ذلك، يجب إنشاء بيانات اعتماد تطبيق الويب بهدف إعداد دعم الجهات الخارجية. للحصول على تعليمات عن كيفية إنشاء بيانات اعتماد تطبيق الويب، يُرجى الاطّلاع على إنشاء بيانات الاعتماد. بعد الانتهاء من هذه الخطوة، ينبغي أن يكون لديك معرف عميل وملف سر العميل.
يمكنك استخدام نموذج OAuth 2 التجريبي من Google للحصول على رمز الدخول:
- انقر على الإعدادات وضع علامة في المربّع استخدِم بيانات اعتماد المصادقة الخاصة بك.
- أدخِل معرِّف العميل وسر العميل من الخطوة 1.
- انقر على إغلاق.
- في حقل "النطاقات"، اكتب
https://www.googleapis.com/auth/cloud_search.settings
وانقر على تفويض. تعرض واجهة OAuth 2 رمز تفويض. - انقر على رمز تفويض Exchange للرموز المميّزة. يتم إرجاع رمز مميّز.
لإعداد دعم الجهات الخارجية لـ Cloud Search، استخدم أمر curl التالي. احرص على استبدال
[YOUR_ACCESS_TOKEN]
بالرمز المميّز الذي تم الحصول عليه في الخطوة الثانية.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".
- انتقِل للأسفل وانقر على Cloud Search. تظهر صفحة "إعدادات Google Workspace".
- انقر على مصادر البيانات التابعة لجهات خارجية. ستظهر لك صفحة "مصادر البيانات".
- انقر على المربّع الأصفر المستدير +، وسيظهر مربّع الحوار "إضافة مصدر بيانات جديد".
- في الحقل الاسم المعروض، اكتب "فيديو تعليمي".
- في حقل عناوين البريد الإلكتروني لحساب الخدمة، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته في القسم السابق. إذا كنت لا تعرف عنوان البريد الإلكتروني لحساب الخدمة، ابحث عن القيمة في صفحة حسابات الخدمة.
- انقر على إضافة. سيظهر مربّع الحوار "تم إنشاء مصدر البيانات بنجاح".
- انقر على *حسنًا. دوِّن معرّف المصدر لمصدر البيانات الذي تمّ إنشاؤه حديثًا. يُستخدم معرّف المصدر في ضبط موصِّل المحتوى.
إنشاء رمز دخول شخصي لواجهة GitHub API
يتطلب الموصل وصولاً مصادقًا إلى واجهة برمجة تطبيقات GitHub للحصول على حصة كافية. للتبسيط، يستفيد الموصل من رموز الدخول الشخصية بدلاً من 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
واحد. تعرض هذه الطريقة مجموعة من ApiOperations
تمثل العناصر المراد دفعها إلى قائمة الانتظار. يتم دفع العناصر كاسم مورد وقيمة تجزئة تمثل الحالة الحالية للعنصر.
يتم استخدام قيمة التجزئة في عمليات التمرير اللاحقة لمستودعات GitHub. تتيح لك هذه القيمة إجراء عملية تحقق بسيطة لتحديد ما إذا كان المحتوى قد تغيّر بدون الحاجة إلى تحميل محتوى إضافي. يضع الموصل في قائمة انتظار جميع العناصر بشكل عشوائي. إذا كان العنصر جديدًا أو تم تغيير قيمة التجزئة، يصبح متاحًا للاستطلاع في قائمة الانتظار. وبخلاف ذلك، يُعتبر العنصر غير معدّل.
جارٍ معالجة قائمة المحتوى التالي
بعد اكتمال الاجتياز بالكامل، يبدأ الموصل في استطلاع
قائمة انتظار العناصر التي يجب فهرستها. ويتم استدعاء الطريقة getDoc()
لكل عنصر يتم سحبه من قائمة الانتظار. تقرأ الطريقة العنصر من GitHub وتحوله إلى التمثيل المناسب
للفهرسة.
ونظرًا لتشغيل الموصِّل مع البيانات المباشرة التي قد يتم تغييرها في أي وقت، يتحقّق getDoc()
أيضًا من أن العنصر المدرج في قائمة الانتظار لا يزال صالحًا ويحذف أي عناصر من الفهرس لم تعُد موجودة.
بالنسبة إلى كل عنصر من كائنات GitHub التي يفهرسها الموصِّل، تعالج طريقة indexItem()
المقابلة إنشاء تمثيل العناصر في Cloud Search. على سبيل المثال، لإنشاء تمثيل لعناصر المحتوى:
بعد ذلك، انشر واجهة البحث.