تعرض هذه الصفحة من دليل Cloud Search التعليمي طريقة إعداد مصدر بيانات وموصل محتوى لفهرسة البيانات. للبدء من بداية هذا البرنامج التعليمي، يُرجى الاطّلاع على الدليل التعليمي لبدء استخدام Cloud Search
بناء أداة الربط
غيِّر دليل العمل إلى دليل cloud-search-samples/end-to-end/connector
وشغِّل الأمر التالي:
mvn package -DskipTests
يقوم الأمر بتنزيل التبعيات المطلوبة اللازمة لإنشاء موصل المحتوى وتجميع التعليمة البرمجية.
إنشاء بيانات اعتماد حساب الخدمة
يتطلب الموصل بيانات اعتماد حساب الخدمة لطلب بيانات واجهات برمجة التطبيقات في Cloud Search. لإنشاء بيانات الاعتماد:
- ارجِع إلى Google Cloud Console.
- في شريط التنقل الأيمن، انقر على بيانات الاعتماد. تظهر صفحة "بيانات الاعتماد".
- انقر على القائمة المنسدلة + إنشاء بيانات الاعتماد واختَر حساب الخدمة. ستظهر لك صفحة "إنشاء حساب خدمة".
- في حقل اسم حساب الخدمة، أدخِل "البرنامج التعليمي".
- سجِّل قيمة رقم تعريف حساب الخدمة (بعد اسم حساب الخدمة مباشرةً). وسيتم استخدام هذه القيمة لاحقًا.
- انقر على إنشاء. سيظهر مربّع الحوار "أذونات حساب الخدمة (اختيارية)".
- انقر على متابعة. سيظهر مربّع الحوار "منح المستخدمين إذن الوصول إلى حساب الخدمة هذا (اختياري)".
- انقر على تمّ. ستظهر شاشة "بيانات الاعتماد".
- ضمن "حسابات الخدمة"، انقر على البريد الإلكتروني لحساب الخدمة. تظهر صفحة "تفاصيل حساب الخدمة".
- ضمن "المفاتيح"، انقر على القائمة المنسدلة إضافة مفتاح واختَر إنشاء مفتاح جديد. سيظهر مربّع الحوار "إنشاء مفتاح خاص".
- انقر على إنشاء.
- (اختياري) في حال ظهور مربّع الحوار "هل تريد السماح بعمليات التنزيل على 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 رمز تفويض. - انقر على تبادل رمز تفويض الرموز المميّزة. يتم إرجاع رمز مميّز.
لتهيئة دعم الجهات الخارجية لخدمة 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.
- انقر على رمز Apps (التطبيقات). ستظهر صفحة "إدارة التطبيقات".
- انقر على Google Workspace. ستظهر لك صفحة "إدارة التطبيقات على Google Workspace".
- مرِّر للأسفل وانقر على Cloud Search. ستظهر لك صفحة "إعدادات Google Workspace".
- انقر على مصادر البيانات التابعة لجهات خارجية. ستظهر صفحة "مصادر البيانات".
- انقر على المربّع الأصفر المستدير +. سيظهر مربّع الحوار "إضافة مصدر بيانات جديد".
- في حقل الاسم المعروض، اكتب "tutorial".
- في الحقل عناوين البريد الإلكتروني لحساب الخدمة، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الذي أنشأته في القسم السابق. إذا كنت لا تعرف عنوان البريد الإلكتروني لحساب الخدمة، ابحث عن القيمة في صفحة حسابات الخدمة.
- انقر على إضافة. سيظهر مربّع الحوار "تم إنشاء مصدر البيانات بنجاح".
- انقر على *حسنًا. سجِّل رقم تعريف المصدر لمصدر البيانات الذي تم إنشاؤه حديثًا. ويتم استخدام رقم تعريف المصدر لإعداد موصِّل المحتوى.
إنشاء رمز دخول شخصي لواجهة برمجة تطبيقات GitHub
يتطلب الموصل الوصول المصادق إلى واجهة برمجة تطبيقات GitHub للحصول على حصة كافية. ولتبسيط الأمر، يستفيد الموصل من رموز الوصول الشخصية بدلاً من OAuth. تتيح الرموز المميزة الشخصية المصادقة بصفتك مستخدمًا لديه مجموعة محدودة من الأذونات المشابهة لـ OAuth.
- سجِّل الدخول إلى GitHub.
- في أعلى يسار الصفحة، انقر على صورة ملفك الشخصي. تظهر قائمة منسدلة.
- انقر على الإعدادات.
- انقر على إعدادات المطوِّر.
- انقر على رموز الدخول الشخصية.
- انقر على إنشاء رمز الدخول الشخصي.
- في حقل ملاحظة، أدخِل "البرنامج التعليمي لـ Cloud Search".
- راجِع النطاق public_repo.
- انقر على إنشاء رمز مميّز.
- دوِّن الرمز المميّز الذي تم إنشاؤه. يتم استخدامه من قبل الموصل لاستدعاء واجهات برمجة التطبيقات GitHub وتوفر حصة واجهة برمجة التطبيقات (API) لإجراء الفهرسة.
ضبط الموصل
بعد إنشاء بيانات الاعتماد ومصدر البيانات، يمكنك تعديل إعدادات الموصل لتضمين القيم التالية:
- من سطر الأوامر، غيِّر الدليل إلى
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
التي توفّرها حزمة تطوير البرامج استراتيجية تمرير تستفيد من قوائم انتظار Cloud Search
لتتبُّع حالة العناصر في الفهرس. يفوّض المستخدم إلى "GithubRepository
"، الذي ينفّذه نموذج الموصِّل، للوصول إلى المحتوى من GitHub.
اجتياز مستودعات GitHub
أثناء عمليات الاجتياز الكاملة، يتم استدعاء الطريقة getIds()
لدفع العناصر التي قد تحتاج إلى فهرستها في قائمة الانتظار.
يمكن للموصل فهرسة عدة مستودعات أو مؤسسات. للتقليل من تأثير الفشل،
يتم اجتياز مستودع جيت هب واحد في كل مرة. يتم إرجاع نقطة مرجعية مع نتائج عملية الاجتياز التي تحتوي على قائمة المستودعات المطلوب فهرستها في عمليات الاستدعاء اللاحقة إلى getIds()
. إذا حدث خطأ، يتم استئناف الفهرسة في المستودع الحالي بدلاً من البدء من البداية.
تتعامل الطريقة collectRepositoryItems()
مع اجتياز
تكرار GitHub واحد. تعرض هذه الطريقة مجموعة من ApiOperations
التي تمثل العناصر ليتم دفعها إلى قائمة الانتظار. يتم دفع العناصر كاسم مورد وقيمة تجزئة تمثل الحالة الحالية للعنصر.
ويتم استخدام قيمة التجزئة في الاجتيازات اللاحقة لمستودعات GitHub. توفّر هذه القيمة فحصًا بسيطًا لتحديد ما إذا كان المحتوى قد تغيّر بدون الحاجة إلى تحميل محتوى إضافي. يضع الموصل بشكل عشوائي جميع العناصر في قائمة انتظار. إذا كان العنصر جديدًا أو تم تغيير قيمة التجزئة، فسيكون متاحًا للاستطلاع في قائمة الانتظار. وبخلاف ذلك، سيتم اعتبار العنصر غير معدّل.
جارٍ معالجة قائمة الانتظار
بعد اكتمال الاجتياز الكامل، يبدأ الموصل في استطلاع
قائمة الانتظار للعناصر التي تحتاج إلى فهرستها. يتم استدعاء طريقة getDoc()
لكل عنصر يتم سحبه من قائمة الانتظار. تقرأ الطريقة العنصر من GitHub وتحوّله إلى التمثيل المناسب للفهرسة.
بما أنّ الموصِّل يعمل مع البيانات المباشرة التي يمكن تغييرها في أي وقت، يتحقّق getDoc()
أيضًا من أنّ العنصر الوارد في قائمة الانتظار لا يزال صالحًا ويحذف أي عناصر من الفهرس لم تعُد متاحة.
بالنسبة إلى كل عنصر من عناصر GitHub التي يفهرسها الموصِّل، تتعامل طريقة indexItem()
المقابلة مع إنشاء تمثيل العناصر لخدمة Cloud Search. على سبيل المثال، لإنشاء تمثيل لعناصر المحتوى:
بعد ذلك، انشر واجهة البحث.