कॉन्टेंट कनेक्टर बनाना

कॉन्टेंट कनेक्टर एक सॉफ़्टवेयर प्रोग्राम होता है. इसका इस्तेमाल, किसी कंपनी की रिपॉज़िटरी में मौजूद डेटा को खोजने और डेटा सोर्स को भरने के लिए किया जाता है. Google, कॉन्टेंट कनेक्टर डेवलप करने के लिए ये विकल्प उपलब्ध कराता है:

  • Content Connector SDK. अगर Java में प्रोग्रामिंग की जा रही है, तो यह एक अच्छा विकल्प है. Content Connector SDK, REST API के चारों ओर एक रैपर है. इसकी मदद से, कनेक्टर को तुरंत बनाया जा सकता है. एसडीके का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाने के लिए, Content Connector SDK का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाना लेख पढ़ें.

  • लो-लेवल REST API या एपीआई लाइब्रेरी. अगर आपको Java में प्रोग्रामिंग नहीं करनी है या आपका कोडबेस, REST API या लाइब्रेरी के साथ बेहतर तरीके से काम करता है, तो इन विकल्पों का इस्तेमाल करें. REST API का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाने के लिए, REST API का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाना लेख पढ़ें.

कॉन्टेंट कनेक्टर आम तौर पर ये काम करता है:

  1. यह कुकी, कॉन्फ़िगरेशन पैरामीटर को पढ़ती है और उन्हें प्रोसेस करती है.
  2. यह तीसरे पक्ष के कॉन्टेंट रिपॉज़िटरी से इंडेक्स किए जा सकने वाले डेटा के अलग-अलग हिस्सों को खींचता है. इन्हें "आइटम" कहा जाता है.
  3. यह इंडेक्स किए जा सकने वाले आइटम में, एसीएल, मेटाडेटा, और कॉन्टेंट डेटा को जोड़ता है.
  4. यह Cloud Search डेटा सोर्स में मौजूद आइटम को इंडेक्स करता है.
  5. (ज़रूरी नहीं) तीसरे पक्ष के कॉन्टेंट रिपॉज़िटरी से मिलने वाली सूचनाओं में हुए बदलावों को सुनता है. बदलाव की सूचनाओं को इंडेक्स करने के अनुरोधों में बदल दिया जाता है, ताकि Cloud Search डेटा सोर्स को तीसरे पक्ष के डेटा स्टोर करने की जगह के साथ सिंक किया जा सके. कनेक्टर, यह टास्क सिर्फ़ तब करता है, जब रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम करती हो.

Content Connector SDK का इस्तेमाल करके, कॉन्टेंट कनेक्टर बनाना

यहां दिए गए सेक्शन में, Content Connector SDK का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाने का तरीका बताया गया है.

डिपेंडेंसी सेट अप करना

एसडीके का इस्तेमाल करने के लिए, आपको अपनी बिल्ड फ़ाइल में कुछ डिपेंडेंसी शामिल करनी होंगी. अपने बिल्ड एनवायरमेंट की डिपेंडेंसी देखने के लिए, यहां दिए गए किसी टैब पर क्लिक करें:

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

ग्रेडल

compile group: 'com.google.enterprise.cloudsearch',
        name: 'google-cloudsearch-indexing-connector-sdk',
        version: 'v1-0.0.3'

कनेक्टर कॉन्फ़िगरेशन बनाना

हर कनेक्टर में एक कॉन्फ़िगरेशन फ़ाइल होती है. इसमें कनेक्टर इस्तेमाल करने वाले पैरामीटर होते हैं. जैसे, आपकी रिपॉज़िटरी का आईडी. पैरामीटर को की-वैल्यू पेयर के तौर पर तय किया जाता है. जैसे, api.sourceId=1234567890abcdef.

Google Cloud Search SDK में, Google की ओर से दिए गए कई कॉन्फ़िगरेशन पैरामीटर होते हैं. इनका इस्तेमाल सभी कनेक्टर करते हैं. आपको कॉन्फ़िगरेशन फ़ाइल में, Google की ओर से उपलब्ध कराए गए इन पैरामीटर के बारे में बताना होगा:

  • कॉन्टेंट कनेक्टर के लिए, आपको api.sourceId और api.serviceAccountPrivateKeyFile की जानकारी देनी होगी. इन पैरामीटर से आपकी रिपॉज़िटरी की जगह की जानकारी मिलती है. साथ ही, रिपॉज़िटरी को ऐक्सेस करने के लिए ज़रूरी निजी कुंजी की जानकारी भी मिलती है.
  • आइडेंटिटी कनेक्टर के लिए, आपको api.identitySourceId को इस पैरामीटर के तौर पर एलान करना होगा. ऐसा इसलिए, क्योंकि यह पैरामीटर आपके बाहरी आइडेंटिटी सोर्स की जगह की जानकारी देता है. अगर आपको उपयोगकर्ताओं को सिंक करना है, तो आपको अपने एंटरप्राइज़ के Google Workspace खाते के लिए, api.customerId को यूनीक आईडी के तौर पर भी सेट करना होगा.

अगर आपको Google की ओर से दिए गए अन्य पैरामीटर की डिफ़ॉल्ट वैल्यू बदलनी हैं, तो आपको उन्हें अपनी कॉन्फ़िगरेशन फ़ाइल में शामिल करने की ज़रूरत नहीं है. Google की ओर से उपलब्ध कराए गए कॉन्फ़िगरेशन पैरामीटर के बारे में ज़्यादा जानकारी के लिए, Google की ओर से उपलब्ध कराए गए कॉन्फ़िगरेशन पैरामीटर लेख पढ़ें. इसमें यह भी बताया गया है कि कुछ आईडी और कुंजियां कैसे जनरेट करें.

कॉन्फ़िगरेशन फ़ाइल में इस्तेमाल करने के लिए, रिपॉज़िटरी के हिसाब से पैरामीटर भी तय किए जा सकते हैं.

कॉन्फ़िगरेशन फ़ाइल को कनेक्टर को पास करना

सिस्टम प्रॉपर्टी config को सेट करें, ताकि कॉन्फ़िगरेशन फ़ाइल को आपके कनेक्टर को पास किया जा सके. कनेक्टर शुरू करते समय, -D आर्ग्युमेंट का इस्तेमाल करके प्रॉपर्टी सेट की जा सकती है. उदाहरण के लिए, यहां दी गई कमांड, कनेक्टर को MyConfig.properties कॉन्फ़िगरेशन फ़ाइल के साथ शुरू करती है:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

अगर यह आर्ग्युमेंट मौजूद नहीं है, तो SDK, connector-config.properties नाम की डिफ़ॉल्ट कॉन्फ़िगरेशन फ़ाइल को ऐक्सेस करने की कोशिश करता है.

डेटा ट्रांसफ़र करने की रणनीति तय करना

कॉन्टेंट कनेक्टर का मुख्य काम, किसी रिपॉज़िटरी को ट्रैवर्स करना और उसके डेटा को इंडेक्स करना होता है. आपको अपनी रिपॉज़िटरी में मौजूद डेटा के साइज़ और लेआउट के आधार पर, ट्रैवर्सल की रणनीति लागू करनी होगी. आपके पास अपनी रणनीति बनाने या एसडीके में लागू की गई इन रणनीतियों में से किसी एक को चुनने का विकल्प है:

पूरे डेटा को ट्रैवर्स करने की रणनीति

पूरी तरह से ट्रैवर्स करने की रणनीति, पूरी रिपॉज़िटरी को स्कैन करती है और हर आइटम को बिना किसी शर्त के इंडेक्स करती है. इस रणनीति का इस्तेमाल आम तौर पर तब किया जाता है, जब आपके पास छोटी रिपॉज़िटरी हो और हर बार इंडेक्स करते समय, पूरे ट्रैवर्सल का खर्च वहन किया जा सकता हो.

यह ट्रैवर्सल रणनीति, ऐसी छोटी रिपॉज़िटरी के लिए सही है जिनमें ज़्यादातर स्टैटिक, नॉन-हायरार्किकल डेटा होता है. इस ट्रैवर्सल रणनीति का इस्तेमाल तब भी किया जा सकता है, जब बदलाव का पता लगाना मुश्किल हो या रिपॉज़िटरी में यह सुविधा काम न करती हो.

सूची को ट्रैवर्स करने की रणनीति

सूची को ट्रैवर्स करने की रणनीति, पूरी रिपॉज़िटरी को स्कैन करती है. इसमें सभी चाइल्ड नोड शामिल होते हैं. इससे हर आइटम की स्थिति का पता चलता है. इसके बाद, कनेक्टर दूसरी बार पास होता है और सिर्फ़ उन आइटम को इंडेक्स करता है जो नए हैं या जिन्हें पिछली इंडेक्सिंग के बाद अपडेट किया गया है. इस रणनीति का इस्तेमाल आम तौर पर, मौजूदा इंडेक्स में इंक्रीमेंटल अपडेट करने के लिए किया जाता है. इससे, इंडेक्स को अपडेट करते समय हर बार पूरा ट्रैवर्सल करने की ज़रूरत नहीं पड़ती.

यह ट्रैवर्सल रणनीति तब सही होती है, जब बदलाव का पता लगाना मुश्किल हो या रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम न करती हो. इसके अलावा, यह रणनीति तब भी सही होती है, जब आपके पास गैर-अनुक्रमिक डेटा हो और आपको बहुत बड़े डेटा सेट के साथ काम करना हो.

ग्राफ़ ट्रैवर्सल

ग्राफ़ ट्रैवर्सल की रणनीति, पूरे पैरंट नोड को स्कैन करती है. इससे हर आइटम की स्थिति का पता चलता है. इसके बाद, कनेक्टर दूसरी बार पास होता है और सिर्फ़ उन आइटम को इंडेक्स करता है जो रूट नोड में नए हैं या जिन्हें पिछली इंडेक्सिंग के बाद अपडेट किया गया है. आखिर में, कनेक्टर सभी चाइल्ड आईडी पास करता है. इसके बाद, चाइल्ड नोड में मौजूद उन आइटम को इंडेक्स करता है जो नए हैं या जिन्हें अपडेट किया गया है. कनेक्टर, सभी चाइल्ड नोड में बार-बार तब तक खोज करता रहता है, जब तक सभी आइटम की जांच पूरी नहीं हो जाती. इस तरह के ट्रैवर्सल का इस्तेमाल आम तौर पर, क्रमबद्ध रिपॉज़िटरी के लिए किया जाता है. इनमें सभी आईडी की सूची बनाना व्यावहारिक नहीं होता.

यह रणनीति तब सही होती है, जब आपके पास क्रम के हिसाब से व्यवस्थित किया गया ऐसा डेटा हो जिसे क्रॉल करने की ज़रूरत हो. जैसे, डायरेक्ट्री या वेब पेजों की सीरीज़.

इनमें से हर एक ट्रैवर्सल रणनीति को एसडीके में मौजूद टेंप्लेट कनेक्टर क्लास लागू करती है. हालांकि, ट्रैवर्सल की अपनी रणनीति लागू की जा सकती है, लेकिन इन टेंप्लेट से कनेक्टर को डेवलप करने में काफ़ी समय बचता है. टेंप्लेट का इस्तेमाल करके कनेक्टर बनाने के लिए, अपनी ट्रैवर्सल रणनीति से जुड़े सेक्शन पर जाएं:

टेंप्लेट क्लास का इस्तेमाल करके, पूरा ट्रैवर्सल कनेक्टर बनाना

दस्तावेज़ के इस सेक्शन में, FullTraversalSample उदाहरण के कोड स्निपेट के बारे में बताया गया है.

कनेक्टर के एंट्री पॉइंट को लागू करना

कनेक्टर का एंट्री पॉइंट, main() तरीका है. इस तरीके का मुख्य काम, Application क्लास का इंस्टेंस बनाना और कनेक्टर को चलाने के लिए, इसके start() मेथड को लागू करना है.

application.start() को कॉल करने से पहले, IndexingApplication.Builder क्लास का इस्तेमाल करके FullTraversalConnector टेंप्लेट को इंस्टैंशिएट करें. FullTraversalConnector, Repository ऑब्जेक्ट को स्वीकार करता है. आपको इसके तरीकों को लागू करना होगा. यहां दिए गए कोड स्निपेट में, main() तरीके को लागू करने का तरीका बताया गया है:

FullTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

पर्दे के पीछे, SDK टूल initConfig() वाले तरीके को कॉल करता है. ऐसा तब होता है, जब आपके कनेक्टर का main() वाला तरीका Application.build को कॉल करता है. initConfig() तरीका ये काम करता है:

  1. यह Configuation.isInitialized() मेथड को कॉल करता है, ताकि यह पक्का किया जा सके कि Configuration को शुरू नहीं किया गया है.
  2. यह फ़ंक्शन, Google की ओर से दिए गए कुंजी-वैल्यू पेयर के साथ Configuration ऑब्जेक्ट को शुरू करता है. हर की-वैल्यू पेयर, Configuration ऑब्जेक्ट में मौजूद ConfigValue ऑब्जेक्ट में सेव होता है.

Repository इंटरफ़ेस लागू करना

Repository ऑब्जेक्ट का मुख्य मकसद, रिपॉज़िटरी आइटम को ट्रैवर्स करना और इंडेक्स करना है. टेंप्लेट का इस्तेमाल करते समय, कॉन्टेंट कनेक्टर बनाने के लिए, आपको सिर्फ़ Repository इंटरफ़ेस में कुछ तरीकों को बदलना होगा. जिन तरीकों को बदला जाता है वे आपके इस्तेमाल किए गए टेंप्लेट और ट्रैवर्सल की रणनीति पर निर्भर करते हैं. FullTraversalConnector के लिए, इन तरीकों को बदलें:

  • init() तरीका. डेटा रिपॉज़िटरी को सेट अप करने और शुरू करने के लिए, init() तरीके को बदलें.

  • getAllDocs() तरीका. डेटा रिपॉज़िटरी में मौजूद सभी आइटम को ट्रैवर्स और इंडेक्स करने के लिए, getAllDocs() तरीके को बदलें. इस तरीके को, शेड्यूल किए गए हर ट्रैवर्सल के लिए एक बार कॉल किया जाता है. ट्रैवर्सल को आपके कॉन्फ़िगरेशन के हिसाब से तय किया जाता है.

  • (ज़रूरी नहीं) getChanges() तरीका. अगर आपकी रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम करती है, तो getChanges() तरीके को बदलें. इस तरीके को हर शेड्यूल किए गए इंक्रीमेंटल ट्रैवर्सल के लिए एक बार कॉल किया जाता है. इसे आपके कॉन्फ़िगरेशन के हिसाब से तय किया जाता है, ताकि बदले गए आइटम वापस पाए जा सकें और उन्हें इंडेक्स किया जा सके.

  • (ज़रूरी नहीं) close() तरीका. अगर आपको रिपॉज़िटरी को क्लीन अप करना है, तो close() तरीके को बदलें. कनेक्टर बंद होने के दौरान, इस तरीके को एक बार कॉल किया जाता है.

Repository ऑब्जेक्ट के हर तरीके से, किसी तरह का ApiOperation ऑब्जेक्ट मिलता है. ApiOperation ऑब्जेक्ट, एक या शायद कई IndexingService.indexItem() कॉल के ज़रिए कार्रवाई करता है, ताकि आपकी रिपॉज़िटरी की इंडेक्सिंग की जा सके.

कस्टम कॉन्फ़िगरेशन पैरामीटर पाना

कनेक्टर के कॉन्फ़िगरेशन को मैनेज करने के लिए, आपको Configuration ऑब्जेक्ट से कोई भी कस्टम पैरामीटर पाना होगा. आम तौर पर, यह टास्क Repository क्लास के init() तरीके से किया जाता है.

Configuration क्लास में, कॉन्फ़िगरेशन से अलग-अलग तरह का डेटा पाने के कई तरीके होते हैं. हर तरीका, एक ConfigValue ऑब्जेक्ट दिखाता है. इसके बाद, आपको ConfigValue ऑब्जेक्ट के get() तरीके का इस्तेमाल करके, असल वैल्यू वापस लानी होगी. FullTraversalSample से लिया गया यह स्निपेट दिखाता है कि Configuration ऑब्जेक्ट से, पूर्णांक की एक कस्टम वैल्यू कैसे वापस पाई जाती है:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

कई वैल्यू वाले पैरामीटर को पाने और पार्स करने के लिए, Configuration क्लास के टाइप पार्सर में से किसी एक का इस्तेमाल करें, ताकि डेटा को अलग-अलग हिस्सों में पार्स किया जा सके. ट्यूटोरियल कनेक्टर का यह स्निपेट, GitHub रिपॉज़िटरी के नामों की सूची पाने के लिए getMultiValue तरीके का इस्तेमाल करता है:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

पूरे डेटा को ट्रैवर्स करना

पूरी ट्रैवर्सल करने और अपनी रिपॉज़िटरी को इंडेक्स करने के लिए, getAllDocs() को ओवरराइड करें. getAllDocs() वाला तरीका, चेकपॉइंट स्वीकार करता है. इस चेकपॉइंट का इस्तेमाल, किसी खास आइटम के लिए इंडेक्सिंग को फिर से शुरू करने के लिए किया जाता है. ऐसा तब किया जाता है, जब प्रोसेस में रुकावट आ जाए. अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, getAllDocs()तरीके में यह तरीका अपनाएं:

  1. अनुमतियां सेट करें.
  2. उस आइटम के लिए मेटाडेटा सेट करें जिसे इंडेक्स किया जा रहा है.
  3. मेटाडेटा और आइटम को एक इंडेक्स किए जा सकने वाले RepositoryDoc में जोड़ें.
  4. इंडेक्स किए जा सकने वाले हर आइटम को, getAllDocs() तरीके से मिले इटरेटर में पैकेज करें. ध्यान दें कि getAllDocs() असल में CheckpointCloseableIterable दिखाता है. यह ApiOperation ऑब्जेक्ट का एक वर्शन है. हर ऑब्जेक्ट, RepositoryDoc पर की गई एपीआई रिक्वेस्ट को दिखाता है. जैसे, इसे इंडेक्स करना.

अगर आइटम का सेट इतना बड़ा है कि उसे एक कॉल में प्रोसेस नहीं किया जा सकता, तो एक चेकपॉइंट शामिल करें और hasMore(true) सेट करें. इससे पता चलेगा कि इंडेक्स करने के लिए और आइटम उपलब्ध हैं.

किसी आइटम के लिए अनुमतियां सेट करना

आपकी रिपॉज़िटरी, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का इस्तेमाल करती है. इससे उन उपयोगकर्ताओं या ग्रुप की पहचान की जाती है जिनके पास किसी आइटम का ऐक्सेस है. एसीएल, उन ग्रुप या उपयोगकर्ताओं के आईडी की सूची होती है जो आइटम को ऐक्सेस कर सकते हैं.

आपको अपनी रिपॉज़िटरी में इस्तेमाल की गई एसीएल को डुप्लीकेट करना होगा. इससे यह पक्का किया जा सकेगा कि खोज के नतीजे में सिर्फ़ वे उपयोगकर्ता आइटम देख पाएं जिनके पास आइटम को ऐक्सेस करने की अनुमति है. किसी आइटम को इंडेक्स करते समय, उसके लिए एसीएल को शामिल करना ज़रूरी है. इससे Google Cloud Search को वह जानकारी मिल पाती है जिसकी मदद से वह आइटम को ऐक्सेस करने का सही लेवल तय कर पाता है.

Content Connector SDK, एसीएल क्लास और तरीकों का एक बड़ा सेट उपलब्ध कराता है. इसकी मदद से, ज़्यादातर रिपॉज़िटरी के एसीएल को मॉडल किया जा सकता है. आपको अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का विश्लेषण करना होगा. साथ ही, किसी आइटम को इंडेक्स करते समय, Google Cloud Search के लिए उससे जुड़ी एसीएल बनानी होगी. अगर आपकी रिपॉज़िटरी के एसीएल में एसीएल इनहेरिटेंस जैसे कॉन्सेप्ट का इस्तेमाल किया जाता है, तो उस एसीएल को मॉडल करना मुश्किल हो सकता है. Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) के बारे में ज़्यादा जानने के लिए, Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) लेख पढ़ें.

ध्यान दें: Cloud Search Indexing API, एक डोमेन वाले एसीएल के साथ काम करता है. यह क्रॉस-डोमेन एसीएल के साथ काम नहीं करता. एसीएल का इस्तेमाल करके, हर आइटम के लिए ऐक्सेस सेट करने के लिए, Acl.Builder क्लास का इस्तेमाल करें. यहां दिया गया कोड स्निपेट, पूरे ट्रैवर्सल के सैंपल से लिया गया है. इससे सभी उपयोगकर्ताओं या “प्रिंसिपल” (getCustomerPrincipal()) को खोज करते समय, सभी आइटम (.setReaders()) के “रीडर” बनने की अनुमति मिलती है.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

रिपॉज़िटरी के लिए एसीएल को सही तरीके से मॉडल करने के लिए, आपको एसीएल को समझना होगा. उदाहरण के लिए, हो सकता है कि किसी फ़ाइल सिस्टम में फ़ाइलों को इंडेक्स किया जा रहा हो. इस फ़ाइल सिस्टम में, इनहेरिटेंस मॉडल का इस्तेमाल किया जाता है. इस मॉडल के तहत, सब-फ़ोल्डर को पैरंट फ़ोल्डर से अनुमतियां मिलती हैं. एसीएल इनहेरिटेंस की मॉडलिंग के लिए, Google Cloud Search के एसीएल में दी गई अतिरिक्त जानकारी की ज़रूरत होती है

किसी आइटम के लिए मेटाडेटा सेट करना

मेटाडेटा, Item ऑब्जेक्ट में सेव होता है. Item बनाने के लिए, आपको आइटम के लिए कम से कम एक यूनीक स्ट्रिंग आईडी, आइटम टाइप, एसीएल, यूआरएल, और वर्शन की ज़रूरत होती है. नीचे दिए गए कोड स्निपेट में, IndexingItemBuilder हेल्पर क्लास का इस्तेमाल करके Item बनाने का तरीका दिखाया गया है.

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

इंडेक्स किया जा सकने वाला आइटम बनाना

आइटम के लिए मेटाडेटा सेट करने के बाद, RepositoryDoc.Builder क्लास का इस्तेमाल करके, इंडेक्स किए जा सकने वाले आइटम बनाए जा सकते हैं. इस उदाहरण में, इंडेक्स किए जा सकने वाले एक आइटम को बनाने का तरीका दिखाया गया है.

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc, ApiOperation का एक टाइप है. यह IndexingService.indexItem() अनुरोध को पूरा करता है.

इंडेक्स करने के अनुरोध को ASYNCHRONOUS या SYNCHRONOUS के तौर पर पहचानने के लिए, RepositoryDoc.Builder क्लास के setRequestMode() तरीके का भी इस्तेमाल किया जा सकता है:

ASYNCHRONOUS
एसिंक मोड में, इंडेक्स करने से लेकर विज्ञापन दिखाने तक की प्रोसेस में ज़्यादा समय लगता है. साथ ही, इसमें इंडेक्स करने के अनुरोधों के लिए थ्रूपुट का बड़ा कोटा होता है. पूरी रिपॉज़िटरी की शुरुआती इंडेक्सिंग (बैकफ़िल) के लिए, एसिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है.
SYNCHRONOUS
सिंक्रोनस मोड में, इंडेक्सिंग से लेकर विज्ञापन दिखाने तक के समय का अंतर कम होता है. साथ ही, इसमें थ्रूपुट का कोटा सीमित होता है. अपडेट और रिपॉज़िटरी में किए गए बदलावों को इंडेक्स करने के लिए, सिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है. अगर इसे तय नहीं किया जाता है, तो अनुरोध मोड डिफ़ॉल्ट रूप से SYNCHRONOUS पर सेट होता है.

इंडेक्स किए जा सकने वाले हर आइटम को इटरेटर में पैकेज करें

getAllDocs() वाला तरीका, RepositoryDoc ऑब्जेक्ट का Iterator दिखाता है. खास तौर पर, CheckpointCloseableIterable दिखाता है. CheckpointClosableIterableImpl.Builder क्लास का इस्तेमाल करके, एक इटरेटर बनाया और उसे वापस किया जा सकता है. नीचे दिए गए कोड स्निपेट में, इटरेटर बनाने और उसे वापस लाने का तरीका बताया गया है.

FullTraversalSample.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

एसडीके, इटरेटर में शामिल हर इंडेक्सिंग कॉल को एक्ज़ीक्यूट करता है.

अगले चरण

यहां कुछ ऐसे तरीके दिए गए हैं जिन्हें आज़माया जा सकता है:

टेंप्लेट क्लास का इस्तेमाल करके, सूची ट्रैवर्सल कनेक्टर बनाना

Cloud Search इंडेक्सिंग क्यू का इस्तेमाल, रिपॉज़िटरी में मौजूद हर आइटम के लिए आईडी और हैश वैल्यू को सेव करने के लिए किया जाता है. सूची ट्रैवर्सल कनेक्टर, आइटम आईडी को Google Cloud Search की इंडेक्सिंग कतार में पुश करता है. साथ ही, इंडेक्सिंग के लिए उन्हें एक-एक करके वापस लाता है. Google Cloud Search, कतारों को मैनेज करता है. साथ ही, कतारों में मौजूद कॉन्टेंट की तुलना करके आइटम की स्थिति का पता लगाता है. जैसे, किसी आइटम को रिपॉज़िटरी से मिटाया गया है या नहीं. Cloud Search की इंडेक्सिंग कतार के बारे में ज़्यादा जानने के लिए, Cloud Search की इंडेक्सिंग कतार पर जाएं.

दस्तावेज़ के इस सेक्शन में, ListTraversalSample उदाहरण के कोड स्निपेट के बारे में बताया गया है.

कनेक्टर के एंट्री पॉइंट को लागू करना

कनेक्टर का एंट्री पॉइंट, main() तरीका है. इस तरीके का मुख्य काम, Application क्लास का इंस्टेंस बनाना और कनेक्टर को चलाने के लिए, इसके start() मेथड को लागू करना है.

application.start() को कॉल करने से पहले, IndexingApplication.Builder क्लास का इस्तेमाल करके ListingConnector टेंप्लेट को इंस्टैंशिएट करें. ListingConnector, Repository ऑब्जेक्ट को स्वीकार करता है. आपको इसके तरीके लागू करने होते हैं. यहां दिए गए स्निपेट में, ListingConnector और उससे जुड़े Repository को इंस्टैंटिएट करने का तरीका बताया गया है:

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

पर्दे के पीछे, SDK टूल initConfig() वाले तरीके को कॉल करता है. ऐसा तब होता है, जब आपके कनेक्टर का main() वाला तरीका Application.build को कॉल करता है. initConfig() तरीका:

  1. यह Configuation.isInitialized() मेथड को कॉल करता है, ताकि यह पक्का किया जा सके कि Configuration को शुरू नहीं किया गया है.
  2. यह फ़ंक्शन, Google की ओर से दिए गए कुंजी-वैल्यू पेयर के साथ Configuration ऑब्जेक्ट को शुरू करता है. हर की-वैल्यू पेयर, Configuration ऑब्जेक्ट में मौजूद ConfigValue ऑब्जेक्ट में सेव होता है.

Repository इंटरफ़ेस लागू करना

Repository ऑब्जेक्ट का मुख्य मकसद, रिपॉज़िटरी आइटम को ट्रैवर्स करना और इंडेक्स करना है. टेंप्लेट का इस्तेमाल करते समय, कॉन्टेंट कनेक्टर बनाने के लिए, आपको सिर्फ़ Repository इंटरफ़ेस में कुछ तरीकों को बदलना होगा. जिन तरीकों को बदला जाता है वे आपके इस्तेमाल किए गए टेम्प्लेट और ट्रैवर्सल की रणनीति पर निर्भर करते हैं. ListingConnector के लिए, इन तरीकों को बदलें:

  • init() तरीका. डेटा रिपॉज़िटरी को सेट अप करने और शुरू करने के लिए, init() तरीके को बदलें.

  • getIds() तरीका. रिपॉज़िटरी में मौजूद सभी रिकॉर्ड के लिए आईडी और हैश वैल्यू पाने के लिए, getIds() तरीके को बदलें.

  • getDoc() तरीका. इंडेक्स में नए आइटम जोड़ने, अपडेट करने, उनमें बदलाव करने या उन्हें मिटाने के लिए, getDoc() तरीके को बदलें.

  • (ज़रूरी नहीं) getChanges() तरीका. अगर आपकी रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम करती है, तो getChanges() तरीके को बदलें. इस तरीके को हर शेड्यूल किए गए इंक्रीमेंटल ट्रैवर्सल के लिए एक बार कॉल किया जाता है. इसे आपके कॉन्फ़िगरेशन के हिसाब से तय किया जाता है, ताकि बदले गए आइटम वापस पाए जा सकें और उन्हें इंडेक्स किया जा सके.

  • (ज़रूरी नहीं) close() तरीका. अगर आपको रिपॉज़िटरी को क्लीन अप करना है, तो close() तरीके को बदलें. कनेक्टर बंद होने के दौरान, इस तरीके को एक बार कॉल किया जाता है.

Repository ऑब्जेक्ट के हर तरीके से, किसी तरह का ApiOperation ऑब्जेक्ट मिलता है. ApiOperation ऑब्जेक्ट, एक या शायद कई IndexingService.indexItem() कॉल के ज़रिए कार्रवाई करता है, ताकि आपकी रिपॉज़िटरी की इंडेक्सिंग की जा सके.

कस्टम कॉन्फ़िगरेशन पैरामीटर पाना

कनेक्टर के कॉन्फ़िगरेशन को मैनेज करने के लिए, आपको Configuration ऑब्जेक्ट से कोई भी कस्टम पैरामीटर पाना होगा. आम तौर पर, यह टास्क Repository क्लास के init() तरीके से किया जाता है.

Configuration क्लास में, कॉन्फ़िगरेशन से अलग-अलग तरह का डेटा पाने के कई तरीके होते हैं. हर तरीका, एक ConfigValue ऑब्जेक्ट दिखाता है. इसके बाद, आपको ConfigValue ऑब्जेक्ट के get() तरीके का इस्तेमाल करके, असल वैल्यू वापस लानी होगी. FullTraversalSample से लिया गया यह स्निपेट दिखाता है कि Configuration ऑब्जेक्ट से, पूर्णांक की एक कस्टम वैल्यू कैसे वापस पाई जाती है:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

कई वैल्यू वाले पैरामीटर को पाने और पार्स करने के लिए, Configuration क्लास के टाइप पार्सर में से किसी एक का इस्तेमाल करें, ताकि डेटा को अलग-अलग हिस्सों में पार्स किया जा सके. ट्यूटोरियल कनेक्टर का यह स्निपेट, GitHub रिपॉज़िटरी के नामों की सूची पाने के लिए getMultiValue तरीके का इस्तेमाल करता है:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

सूची को ट्रैवर्स करना

बदलें getIds() रिपॉज़िटरी में मौजूद सभी रिकॉर्ड के लिए आईडी और हैश वैल्यू वापस पाने का तरीका. getIds() तरीके में चेकपॉइंट स्वीकार किया जाता है. इस चेकपॉइंट का इस्तेमाल, किसी खास आइटम पर इंडेक्सिंग को फिर से शुरू करने के लिए किया जाता है. ऐसा तब किया जाता है, जब प्रोसेस में रुकावट आ जाए.

इसके बाद, Cloud Search इंडेक्सिंग क्यू में मौजूद हर आइटम को हैंडल करने के लिए, getDoc() तरीके को बदलें.

आइटम आईडी और हैश वैल्यू पुश करना

ओवरराइड getIds() का इस्तेमाल करके, रिपॉज़िटरी से आइटम आईडी और उनसे जुड़ी कॉन्टेंट हैश वैल्यू फ़ेच करें. इसके बाद, आईडी और हैश वैल्यू के जोड़े को पुश ऑपरेशन के अनुरोध में पैकेज किया जाता है. यह अनुरोध, Cloud Search Indexing Queue को भेजा जाता है. आम तौर पर, रूट या पैरंट आईडी को सबसे पहले पुश किया जाता है. इसके बाद, चाइल्ड आईडी को तब तक पुश किया जाता है, जब तक कि आइटम के पूरे क्रम को प्रोसेस न कर लिया जाए.

getIds() वाला तरीका, इंडेक्स किए जाने वाले आखिरी आइटम को दिखाने वाले चेकपॉइंट को स्वीकार करता है. अगर प्रोसेस में रुकावट आती है, तो चेकपॉइंट का इस्तेमाल करके किसी आइटम को इंडेक्स करने की प्रोसेस फिर से शुरू की जा सकती है. अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, getIds() तरीके में यह तरीका अपनाएं:

  • हर आइटम का आईडी और उससे जुड़ी हैश वैल्यू, रिपॉज़िटरी से पाएं.
  • हर आईडी और हैश वैल्यू के जोड़े को PushItems में पैकेज करें.
  • हर PushItems को getIds() तरीके से लौटाए गए इटरेटर में मिलाएं. ध्यान दें कि getIds() फ़ंक्शन, असल में CheckpointCloseableIterable दिखाता है. यह ApiOperation ऑब्जेक्ट का एक वर्शन है. हर ऑब्जेक्ट, RepositoryDoc पर की गई एपीआई रिक्वेस्ट को दिखाता है. जैसे, आइटम को कतार में जोड़ना.

नीचे दिए गए कोड स्निपेट में, हर आइटम आईडी और हैश वैल्यू पाने और उन्हें PushItems में डालने का तरीका बताया गया है. PushItems, Cloud Search इंडेक्सिंग क्यू में किसी आइटम को पुश करने का ApiOperation अनुरोध होता है.

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

यहां दिए गए कोड स्निपेट में, आईडी और हैश वैल्यू को एक ही पुश ApiOperation में पैकेज करने के लिए, PushItems.Builder क्लास का इस्तेमाल करने का तरीका बताया गया है.

ListTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

आइटम को Cloud Search इंडेक्सिंग की प्रोसेसिंग के लिए, इंडेक्सिंग की प्रोसेसिंग वाली सूची में भेज दिया जाता है.

हर आइटम को वापस पाना और उसे मैनेज करना

Cloud Search इंडेक्सिंग की कतार में मौजूद हर आइटम को मैनेज करने के लिए, getDoc() को बदलें. कोई आइटम नया हो सकता है, उसमें बदलाव किया गया हो सकता है, वह पहले जैसा हो सकता है या सोर्स रिपॉज़िटरी में अब मौजूद नहीं हो सकता. नए या बदले गए हर आइटम को वापस पाना और उसे इंडेक्स करना. उन आइटम को इंडेक्स से हटाएं जो अब सोर्स रिपॉज़िटरी में मौजूद नहीं हैं.

getDoc() तरीका, Google Cloud Search की इंडेक्सिंग कतार से आइटम स्वीकार करता है. कतार में मौजूद हर आइटम के लिए, getDoc() तरीके में यह तरीका अपनाएं:

  1. देखें कि Cloud Search इंडेक्सिंग क्यू में मौजूद आइटम का आईडी, रिपॉज़िटरी में मौजूद है या नहीं. अगर ऐसा नहीं है, तो इंडेक्स से आइटम मिटाएं.

  2. आइटम के स्टेटस के लिए इंडेक्स को पोल करें. अगर किसी आइटम में कोई बदलाव नहीं हुआ है (ACCEPTED), तो कुछ न करें.

  3. इंडेक्स में बदलाव हुआ है या नए आइटम जोड़े गए हैं:

    1. अनुमतियां सेट करें.
    2. उस आइटम के लिए मेटाडेटा सेट करें जिसे इंडेक्स किया जा रहा है.
    3. मेटाडेटा और आइटम को एक इंडेक्स किए जा सकने वाले RepositoryDoc में जोड़ें.
    4. RepositoryDoc को वापस लाएं.

ध्यान दें: ListingConnector टेंप्लेट, getDoc() मेथड पर null को वापस लाने की सुविधा के साथ काम नहीं करता. null नतीजे मिलने पर NullPointerException. दिखता है

मिटाए गए आइटम मैनेज करना

यहां दिए गए कोड स्निपेट में बताया गया है कि किसी आइटम के रिपॉज़िटरी में मौजूद होने का पता कैसे लगाया जाता है. साथ ही, अगर वह मौजूद नहीं है, तो उसे मिटाने का तरीका भी बताया गया है.

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

ध्यान दें कि documents एक डेटा स्ट्रक्चर है, जो रिपॉज़िटरी को दिखाता है. अगर documentID, documents में नहीं मिलता है, तो इंडेक्स से आइटम मिटाने के लिए, APIOperations.deleteItem(resourceName) दिखाएं.

बदलाव नहीं किए गए आइटम मैनेज करना

नीचे दिए गए कोड स्निपेट में, Cloud Search इंडेक्सिंग कतार में आइटम के स्टेटस को पोल करने और बिना बदलाव वाले आइटम को मैनेज करने का तरीका बताया गया है.

ListTraversalSample.java
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

यह पता लगाने के लिए कि आइटम में कोई बदलाव नहीं किया गया है, आइटम के स्टेटस के साथ-साथ अन्य मेटाडेटा की जांच करें. इससे बदलाव के बारे में पता चल सकता है. इस उदाहरण में, मेटाडेटा हैश का इस्तेमाल यह पता लगाने के लिए किया गया है कि आइटम में बदलाव हुआ है या नहीं.

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

किसी आइटम के लिए अनुमतियां सेट करना

आपकी रिपॉज़िटरी, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का इस्तेमाल करती है. इससे उन उपयोगकर्ताओं या ग्रुप की पहचान की जाती है जिनके पास किसी आइटम का ऐक्सेस है. एसीएल, उन ग्रुप या उपयोगकर्ताओं के आईडी की सूची होती है जो आइटम को ऐक्सेस कर सकते हैं.

आपको अपनी रिपॉज़िटरी में इस्तेमाल की गई एसीएल को डुप्लीकेट करना होगा. इससे यह पक्का किया जा सकेगा कि खोज के नतीजे में सिर्फ़ वे उपयोगकर्ता आइटम देख पाएं जिनके पास आइटम को ऐक्सेस करने की अनुमति है. किसी आइटम को इंडेक्स करते समय, उसके लिए एसीएल को शामिल करना ज़रूरी है. इससे Google Cloud Search को वह जानकारी मिल पाती है जिसकी मदद से वह आइटम को ऐक्सेस करने का सही लेवल तय कर पाता है.

Content Connector SDK, एसीएल क्लास और तरीकों का एक बड़ा सेट उपलब्ध कराता है. इसकी मदद से, ज़्यादातर रिपॉज़िटरी के एसीएल को मॉडल किया जा सकता है. आपको अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का विश्लेषण करना होगा. साथ ही, किसी आइटम को इंडेक्स करते समय, Google Cloud Search के लिए उससे जुड़ी एसीएल बनानी होगी. अगर आपकी रिपॉज़िटरी के एसीएल में एसीएल इनहेरिटेंस जैसे कॉन्सेप्ट का इस्तेमाल किया जाता है, तो उस एसीएल को मॉडल करना मुश्किल हो सकता है. Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) के बारे में ज़्यादा जानने के लिए, Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) लेख पढ़ें.

ध्यान दें: Cloud Search Indexing API, एक डोमेन वाले एसीएल के साथ काम करता है. यह क्रॉस-डोमेन एसीएल के साथ काम नहीं करता. एसीएल का इस्तेमाल करके, हर आइटम के लिए ऐक्सेस सेट करने के लिए, Acl.Builder क्लास का इस्तेमाल करें. यहां दिया गया कोड स्निपेट, पूरे ट्रैवर्सल के सैंपल से लिया गया है. इससे सभी उपयोगकर्ताओं या “प्रिंसिपल” (getCustomerPrincipal()) को खोज करते समय, सभी आइटम (.setReaders()) के “रीडर” बनने की अनुमति मिलती है.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

रिपॉज़िटरी के लिए एसीएल को सही तरीके से मॉडल करने के लिए, आपको एसीएल को समझना होगा. उदाहरण के लिए, हो सकता है कि किसी फ़ाइल सिस्टम में फ़ाइलों को इंडेक्स किया जा रहा हो. इस फ़ाइल सिस्टम में, इनहेरिटेंस मॉडल का इस्तेमाल किया जाता है. इस मॉडल के तहत, सब-फ़ोल्डर को पैरंट फ़ोल्डर से अनुमतियां मिलती हैं. एसीएल इनहेरिटेंस की मॉडलिंग के लिए, Google Cloud Search के एसीएल में दी गई अतिरिक्त जानकारी की ज़रूरत होती है

किसी आइटम के लिए मेटाडेटा सेट करना

मेटाडेटा, Item ऑब्जेक्ट में सेव होता है. Item बनाने के लिए, आपको आइटम के लिए कम से कम एक यूनीक स्ट्रिंग आईडी, आइटम टाइप, एसीएल, यूआरएल, और वर्शन की ज़रूरत होती है. नीचे दिए गए कोड स्निपेट में, IndexingItemBuilder हेल्पर क्लास का इस्तेमाल करके Item बनाने का तरीका दिखाया गया है.

ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

इंडेक्स किया जा सकने वाला आइटम बनाना

किसी आइटम के लिए मेटाडेटा सेट करने के बाद, RepositoryDoc.Builder का इस्तेमाल करके इंडेक्स किया जा सकने वाला असली आइटम बनाया जा सकता है. इस उदाहरण में, इंडेक्स किए जा सकने वाले एक आइटम को बनाने का तरीका दिखाया गया है.

ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc एक तरह का ApiOperation होता है, जो असल में IndexingService.indexItem() अनुरोध करता है.

इंडेक्स करने के अनुरोध को ASYNCHRONOUS या SYNCHRONOUS के तौर पर पहचानने के लिए, RepositoryDoc.Builder क्लास के setRequestMode() तरीके का भी इस्तेमाल किया जा सकता है:

ASYNCHRONOUS
एसिंक मोड में, इंडेक्स करने से लेकर विज्ञापन दिखाने तक की प्रोसेस में ज़्यादा समय लगता है. साथ ही, इसमें इंडेक्स करने के अनुरोधों के लिए थ्रूपुट का बड़ा कोटा होता है. पूरी रिपॉज़िटरी की शुरुआती इंडेक्सिंग (बैकफ़िल) के लिए, एसिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है.
SYNCHRONOUS
सिंक्रोनस मोड में, इंडेक्सिंग से लेकर विज्ञापन दिखाने तक के समय का अंतर कम होता है. साथ ही, इसमें थ्रूपुट का कोटा सीमित होता है. अपडेट और रिपॉज़िटरी में किए गए बदलावों को इंडेक्स करने के लिए, सिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है. अगर इसे तय नहीं किया जाता है, तो अनुरोध मोड डिफ़ॉल्ट रूप से SYNCHRONOUS पर सेट होता है.

अगले चरण

यहां कुछ ऐसे तरीके दिए गए हैं जिन्हें आज़माया जा सकता है:

  • (ज़रूरी नहीं) बंद करने से पहले किसी भी संसाधन को रिलीज़ करने के लिए, close() तरीके का इस्तेमाल करें.
  • (ज़रूरी नहीं) Content Connector SDK का इस्तेमाल करके, पहचान कनेक्टर बनाएं.

टेंप्लेट क्लास का इस्तेमाल करके, ग्राफ़ ट्रैवर्सल कनेक्टर बनाना

Cloud Search की इंडेक्सिंग क्यू का इस्तेमाल, रिपॉज़िटरी में मौजूद हर आइटम के लिए आईडी और हैश वैल्यू (ज़रूरी नहीं) को सेव करने के लिए किया जाता है. ग्राफ़ ट्रैवर्सल कनेक्टर, आइटम आईडी को Google Cloud Search की इंडेक्सिंग कतार में भेजता है. साथ ही, इंडेक्सिंग के लिए उन्हें एक-एक करके वापस पाता है. Google Cloud Search, कतारों को मैनेज करता है. साथ ही, कतारों में मौजूद कॉन्टेंट की तुलना करके आइटम की स्थिति का पता लगाता है. जैसे, किसी आइटम को रिपॉज़िटरी से मिटाया गया है या नहीं. Cloud Search इंडेक्सिंग की प्रोसेस में शामिल किए जाने वाले डेटा की सूची के बारे में ज़्यादा जानने के लिए, Google Cloud Search इंडेक्सिंग की प्रोसेस में शामिल किए जाने वाले डेटा की सूची पर जाएं.

इंडेक्सिंग के दौरान, डेटा रिपॉज़िटरी से आइटम का कॉन्टेंट फ़ेच किया जाता है. साथ ही, किसी भी चाइल्ड आइटम के आईडी को क्यू में पुश किया जाता है. कनेक्टर, पैरंट और चाइल्ड आईडी को तब तक प्रोसेस करता रहता है, जब तक सभी आइटम प्रोसेस नहीं हो जाते.

दस्तावेज़ के इस सेक्शन में, GraphTraversalSample उदाहरण के कोड स्निपेट के बारे में बताया गया है.

कनेक्टर के एंट्री पॉइंट को लागू करना

कनेक्टर का एंट्री पॉइंट, main() तरीका है. इस तरीके का मुख्य काम, Application क्लास का इंस्टेंस बनाना और कनेक्टर को चलाने के लिए, इसके start() मेथड को लागू करना है.

application.start() को कॉल करने से पहले, ListingConnector टेंप्लेट को इंस्टैंशिएट करने के लिए, IndexingApplication.Builder क्लास का इस्तेमाल करें. ListingConnector, Repository ऑब्जेक्ट को स्वीकार करता है. आपको इसके तरीकों को लागू करना होगा.

यहां दिए गए स्निपेट में, ListingConnector और उससे जुड़े Repository को इंस्टैंटिएट करने का तरीका बताया गया है:

GraphTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

पर्दे के पीछे, SDK टूल initConfig() वाले तरीके को कॉल करता है. ऐसा तब होता है, जब आपके कनेक्टर का main() वाला तरीका Application.build को कॉल करता है. initConfig() तरीका:

  1. यह Configuation.isInitialized() मेथड को कॉल करता है, ताकि यह पक्का किया जा सके कि Configuration को शुरू नहीं किया गया है.
  2. यह फ़ंक्शन, Google की ओर से दिए गए कुंजी-वैल्यू पेयर के साथ Configuration ऑब्जेक्ट को शुरू करता है. हर की-वैल्यू पेयर, Configuration ऑब्जेक्ट में मौजूद ConfigValue ऑब्जेक्ट में सेव होता है.

Repository इंटरफ़ेस लागू करना

Repository ऑब्जेक्ट का मुख्य मकसद, रिपॉज़िटरी आइटम को ट्रैवर्स करना और इंडेक्स करना है. टेंप्लेट का इस्तेमाल करते समय, कॉन्टेंट कनेक्टर बनाने के लिए आपको सिर्फ़ Repository इंटरफ़ेस में कुछ तरीकों को बदलना होगा. जिन तरीकों को बदला जाता है वे आपके इस्तेमाल किए गए टेंप्लेट और ट्रैवर्सल की रणनीति पर निर्भर करते हैं. ListingConnector के लिए, इन तरीकों को बदलें:

  • init() तरीका. डेटा रिपॉज़िटरी को सेट अप करने और शुरू करने के लिए, init() तरीके को बदलें.

  • getIds() तरीका. रिपॉज़िटरी में मौजूद सभी रिकॉर्ड के लिए आईडी और हैश वैल्यू पाने के लिए, getIds() तरीके को बदलें.

  • getDoc() तरीका. इंडेक्स में नए आइटम जोड़ने, अपडेट करने, उनमें बदलाव करने या उन्हें मिटाने के लिए, getDoc() तरीके को बदलें.

  • (ज़रूरी नहीं) getChanges() तरीका. अगर आपकी रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम करती है, तो getChanges() तरीके को बदलें. इस तरीके को हर शेड्यूल किए गए इंक्रीमेंटल ट्रैवर्सल के लिए एक बार कॉल किया जाता है. इसे आपके कॉन्फ़िगरेशन के हिसाब से तय किया जाता है, ताकि बदले गए आइटम वापस पाए जा सकें और उन्हें इंडेक्स किया जा सके.

  • (ज़रूरी नहीं) close() तरीका. अगर आपको रिपॉज़िटरी को क्लीन अप करना है, तो close() तरीके को बदलें. कनेक्टर बंद होने के दौरान, इस तरीके को एक बार कॉल किया जाता है.

Repository ऑब्जेक्ट के हर तरीके से, किसी तरह का ApiOperation ऑब्जेक्ट मिलता है. ApiOperation ऑब्जेक्ट, एक या एक से ज़्यादा IndexingService.indexItem() कॉल के ज़रिए कार्रवाई करता है. इससे आपकी रिपॉज़िटरी की इंडेक्सिंग की जा सकती है.

कस्टम कॉन्फ़िगरेशन पैरामीटर पाना

कनेक्टर के कॉन्फ़िगरेशन को मैनेज करने के लिए, आपको Configuration ऑब्जेक्ट से कोई भी कस्टम पैरामीटर पाना होगा. आम तौर पर, यह टास्क Repository क्लास के init() तरीके से किया जाता है.

Configuration क्लास में, कॉन्फ़िगरेशन से अलग-अलग तरह का डेटा पाने के कई तरीके होते हैं. हर तरीका, एक ConfigValue ऑब्जेक्ट दिखाता है. इसके बाद, आपको ConfigValue ऑब्जेक्ट के get() तरीके का इस्तेमाल करके, असल वैल्यू वापस लानी होगी. FullTraversalSample से लिया गया यह स्निपेट दिखाता है कि Configuration ऑब्जेक्ट से, पूर्णांक की एक कस्टम वैल्यू कैसे वापस पाई जाती है:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

कई वैल्यू वाले पैरामीटर को पाने और पार्स करने के लिए, Configuration क्लास के टाइप पार्सर में से किसी एक का इस्तेमाल करें, ताकि डेटा को अलग-अलग हिस्सों में पार्स किया जा सके. ट्यूटोरियल कनेक्टर का यह स्निपेट, GitHub रिपॉज़िटरी के नामों की सूची पाने के लिए getMultiValue तरीके का इस्तेमाल करता है:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

ग्राफ़ ट्रैवर्सल करना

बदलें getIds() रिपॉज़िटरी में मौजूद सभी रिकॉर्ड के लिए आईडी और हैश वैल्यू वापस पाने का तरीका. getIds() तरीके में चेकपॉइंट स्वीकार किया जाता है. इस चेकपॉइंट का इस्तेमाल, किसी खास आइटम पर इंडेक्सिंग को फिर से शुरू करने के लिए किया जाता है. ऐसा तब किया जाता है, जब प्रोसेस में रुकावट आ जाए.

इसके बाद, Cloud Search इंडेक्सिंग क्यू में मौजूद हर आइटम को हैंडल करने के लिए, getDoc() तरीके को बदलें.

आइटम आईडी और हैश वैल्यू पुश करना

ओवरराइड getIds() का इस्तेमाल करके, रिपॉज़िटरी से आइटम आईडी और उनसे जुड़ी कॉन्टेंट हैश वैल्यू फ़ेच करें. इसके बाद, आईडी और हैश वैल्यू के जोड़े को पुश ऑपरेशन के अनुरोध में पैकेज किया जाता है. यह अनुरोध, Cloud Search Indexing Queue को भेजा जाता है. आम तौर पर, रूट या पैरंट आईडी को सबसे पहले पुश किया जाता है. इसके बाद, चाइल्ड आईडी को तब तक पुश किया जाता है, जब तक कि आइटम के पूरे क्रम को प्रोसेस न कर लिया जाए.

getIds() वाला तरीका, इंडेक्स किए जाने वाले आखिरी आइटम को दिखाने वाले चेकपॉइंट को स्वीकार करता है. अगर प्रोसेस में रुकावट आती है, तो चेकपॉइंट का इस्तेमाल करके किसी आइटम को इंडेक्स करने की प्रोसेस फिर से शुरू की जा सकती है. अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, getIds() तरीके में यह तरीका अपनाएं:

  • हर आइटम का आईडी और उससे जुड़ी हैश वैल्यू, रिपॉज़िटरी से पाएं.
  • हर आईडी और हैश वैल्यू के जोड़े को PushItems में पैकेज करें.
  • हर PushItems को getIds() तरीके से लौटाए गए इटरेटर में मिलाएं. ध्यान दें कि getIds() फ़ंक्शन, असल में CheckpointCloseableIterable दिखाता है. यह ApiOperation ऑब्जेक्ट का एक वर्शन है. हर ऑब्जेक्ट, RepositoryDoc पर की गई एपीआई रिक्वेस्ट को दिखाता है. जैसे, आइटम को कतार में जोड़ना.

यहां दिए गए कोड स्निपेट में, हर आइटम आईडी और हैश वैल्यू पाने और उन्हें PushItems में डालने का तरीका बताया गया है. PushItems, Cloud Search इंडेक्सिंग की कतार में किसी आइटम को भेजने का ApiOperation अनुरोध होता है.

GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

यहां दिए गए कोड स्निपेट में, आईडी और हैश वैल्यू को एक ही पुश ApiOperation में पैकेज करने के लिए, PushItems.Builder क्लास का इस्तेमाल करने का तरीका बताया गया है.

GraphTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

आइटम को Cloud Search इंडेक्सिंग की प्रोसेसिंग के लिए, इंडेक्सिंग की प्रोसेसिंग वाली सूची में भेज दिया जाता है.

हर आइटम को वापस पाना और उसे मैनेज करना

Cloud Search इंडेक्सिंग की कतार में मौजूद हर आइटम को मैनेज करने के लिए, getDoc() को बदलें. कोई आइटम नया हो सकता है, उसमें बदलाव किया गया हो सकता है, वह पहले जैसा हो सकता है या सोर्स रिपॉज़िटरी में अब मौजूद नहीं हो सकता. नए या बदले गए हर आइटम को वापस पाना और उसे इंडेक्स करना. उन आइटम को इंडेक्स से हटाएं जो अब सोर्स रिपॉज़िटरी में मौजूद नहीं हैं.

getDoc() वाला तरीका, Cloud Search इंडेक्सिंग की कतार से आइटम स्वीकार करता है. कतार में मौजूद हर आइटम के लिए, getDoc() तरीके में यह तरीका अपनाएं:

  1. देखें कि Cloud Search इंडेक्सिंग क्यू में मौजूद आइटम का आईडी, रिपॉज़िटरी में मौजूद है या नहीं. अगर ऐसा नहीं है, तो इंडेक्स से आइटम मिटाएं. अगर आइटम मौजूद है, तो अगले चरण पर जाएं.

  2. इंडेक्स में बदलाव हुआ है या नए आइटम जोड़े गए हैं:

    1. अनुमतियां सेट करें.
    2. उस आइटम के लिए मेटाडेटा सेट करें जिसे इंडेक्स किया जा रहा है.
    3. मेटाडेटा और आइटम को एक इंडेक्स किए जा सकने वाले RepositoryDoc में जोड़ें.
    4. आगे की प्रोसेस के लिए, चाइल्ड आईडी को Cloud Search इंडेक्सिंग क्यू में रखें.
    5. RepositoryDoc को वापस लाएं.

मिटाए गए आइटम मैनेज करना

यहां दिए गए कोड स्निपेट में बताया गया है कि इंडेक्स में कोई आइटम मौजूद है या नहीं. अगर मौजूद नहीं है, तो उसे मिटा दें.

GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

किसी आइटम के लिए अनुमतियां सेट करना

आपकी रिपॉज़िटरी, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का इस्तेमाल करती है. इससे उन उपयोगकर्ताओं या ग्रुप की पहचान की जाती है जिनके पास किसी आइटम का ऐक्सेस है. एसीएल, उन ग्रुप या उपयोगकर्ताओं के आईडी की सूची होती है जो आइटम को ऐक्सेस कर सकते हैं.

आपको अपनी रिपॉज़िटरी में इस्तेमाल की गई एसीएल को डुप्लीकेट करना होगा. इससे यह पक्का किया जा सकेगा कि खोज के नतीजे में सिर्फ़ वे उपयोगकर्ता आइटम देख पाएं जिनके पास आइटम को ऐक्सेस करने की अनुमति है. किसी आइटम को इंडेक्स करते समय, उसके लिए एसीएल को शामिल करना ज़रूरी है. इससे Google Cloud Search को वह जानकारी मिल पाती है जिसकी मदद से वह आइटम को ऐक्सेस करने का सही लेवल तय कर पाता है.

Content Connector SDK, एसीएल क्लास और तरीकों का एक बड़ा सेट उपलब्ध कराता है. इसकी मदद से, ज़्यादातर रिपॉज़िटरी के एसीएल को मॉडल किया जा सकता है. आपको अपनी रिपॉज़िटरी में मौजूद हर आइटम के लिए, ऐक्सेस कंट्रोल लिस्ट (एसीएल) का विश्लेषण करना होगा. साथ ही, किसी आइटम को इंडेक्स करते समय, Google Cloud Search के लिए उससे जुड़ी एसीएल बनानी होगी. अगर आपकी रिपॉज़िटरी के एसीएल में एसीएल इनहेरिटेंस जैसे कॉन्सेप्ट का इस्तेमाल किया जाता है, तो उस एसीएल को मॉडल करना मुश्किल हो सकता है. Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) के बारे में ज़्यादा जानने के लिए, Google Cloud Search के ऐक्सेस कंट्रोल लिस्ट (एसीएल) लेख पढ़ें.

ध्यान दें: Cloud Search Indexing API, एक डोमेन वाले एसीएल के साथ काम करता है. यह क्रॉस-डोमेन एसीएल के साथ काम नहीं करता. एसीएल का इस्तेमाल करके, हर आइटम के लिए ऐक्सेस सेट करने के लिए, Acl.Builder क्लास का इस्तेमाल करें. यहां दिया गया कोड स्निपेट, पूरे ट्रैवर्सल के सैंपल से लिया गया है. इससे सभी उपयोगकर्ताओं या “प्रिंसिपल” (getCustomerPrincipal()) को खोज करते समय, सभी आइटम (.setReaders()) के “रीडर” बनने की अनुमति मिलती है.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

रिपॉज़िटरी के लिए एसीएल को सही तरीके से मॉडल करने के लिए, आपको एसीएल को समझना होगा. उदाहरण के लिए, हो सकता है कि किसी फ़ाइल सिस्टम में फ़ाइलों को इंडेक्स किया जा रहा हो. इस फ़ाइल सिस्टम में, इनहेरिटेंस मॉडल का इस्तेमाल किया जाता है. इस मॉडल के तहत, सब-फ़ोल्डर को पैरंट फ़ोल्डर से अनुमतियां मिलती हैं. एसीएल इनहेरिटेंस की मॉडलिंग के लिए, Google Cloud Search के एसीएल में दी गई अतिरिक्त जानकारी की ज़रूरत होती है

किसी आइटम के लिए मेटाडेटा सेट करना

मेटाडेटा, Item ऑब्जेक्ट में सेव होता है. Item बनाने के लिए, आपको आइटम के लिए कम से कम एक यूनीक स्ट्रिंग आईडी, आइटम टाइप, एसीएल, यूआरएल, और वर्शन की ज़रूरत होती है. नीचे दिए गए कोड स्निपेट में, IndexingItemBuilder हेल्पर क्लास का इस्तेमाल करके Item बनाने का तरीका दिखाया गया है.

GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

इंडेक्स किया जा सकने वाला आइटम बनाना

किसी आइटम के लिए मेटाडेटा सेट करने के बाद, RepositoryDoc.Builder का इस्तेमाल करके इंडेक्स किया जा सकने वाला असली आइटम बनाया जा सकता है. इस उदाहरण में, इंडेक्स किए जा सकने वाले एक आइटम को बनाने का तरीका दिखाया गया है.

GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc, ApiOperation का एक टाइप है. यह IndexingService.indexItem() अनुरोध को पूरा करता है.

इंडेक्स करने के अनुरोध को ASYNCHRONOUS या SYNCHRONOUS के तौर पर पहचानने के लिए, RepositoryDoc.Builder क्लास के setRequestMode() तरीके का भी इस्तेमाल किया जा सकता है:

ASYNCHRONOUS
एसिंक मोड में, इंडेक्स करने से लेकर विज्ञापन दिखाने तक की प्रोसेस में ज़्यादा समय लगता है. साथ ही, इसमें इंडेक्स करने के अनुरोधों के लिए थ्रूपुट का बड़ा कोटा होता है. पूरी रिपॉज़िटरी की शुरुआती इंडेक्सिंग (बैकफ़िल) के लिए, एसिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है.
SYNCHRONOUS
सिंक्रोनस मोड में, इंडेक्सिंग से लेकर विज्ञापन दिखाने तक के समय का अंतर कम होता है. साथ ही, इसमें थ्रूपुट का कोटा सीमित होता है. अपडेट और रिपॉज़िटरी में किए गए बदलावों को इंडेक्स करने के लिए, सिंक्रोनस मोड का इस्तेमाल करने का सुझाव दिया जाता है. अगर इसे तय नहीं किया जाता है, तो अनुरोध मोड डिफ़ॉल्ट रूप से SYNCHRONOUS पर सेट होता है.

चाइल्ड आईडी को Cloud Search इंडेक्सिंग की सूची में रखें

नीचे दिए गए कोड स्निपेट में बताया गया है कि प्रोसेस किए जा रहे मौजूदा पैरंट आइटम के लिए, बच्चों के आईडी को प्रोसेस करने के लिए कतार में कैसे शामिल किया जाए. इन आईडी को, पैरंट आइटम के इंडेक्स होने के बाद प्रोसेस किया जाता है.

GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

अगले चरण

यहां कुछ ऐसे तरीके दिए गए हैं जिन्हें आज़माया जा सकता है:

  • (ज़रूरी नहीं) बंद करने से पहले किसी भी संसाधन को रिलीज़ करने के लिए, close() तरीके का इस्तेमाल करें.
  • (ज़रूरी नहीं) Identity Connector SDK का इस्तेमाल करके, पहचान से जुड़ा कनेक्टर बनाएं.

REST API का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाना

यहां दिए गए सेक्शन में, REST API का इस्तेमाल करके कॉन्टेंट कनेक्टर बनाने का तरीका बताया गया है.

डेटा ट्रांसफ़र करने की रणनीति तय करना

कॉन्टेंट कनेक्टर का मुख्य काम, किसी रिपॉज़िटरी को ट्रैवर्स करना और उसके डेटा को इंडेक्स करना होता है. आपको अपनी रिपॉज़िटरी में मौजूद डेटा के साइज़ और लेआउट के आधार पर, ट्रैवर्सल की रणनीति लागू करनी होगी. यहां ट्रैवर्सल की तीन सामान्य रणनीतियां दी गई हैं:

पूरे डेटा को ट्रैवर्स करने की रणनीति

पूरी तरह से ट्रैवर्स करने की रणनीति, पूरी रिपॉज़िटरी को स्कैन करती है और हर आइटम को बिना किसी शर्त के इंडेक्स करती है. इस रणनीति का इस्तेमाल आम तौर पर तब किया जाता है, जब आपके पास छोटी रिपॉज़िटरी हो और हर बार इंडेक्स करते समय, पूरे ट्रैवर्सल का खर्च वहन किया जा सकता हो.

यह ट्रैवर्सल रणनीति, ऐसी छोटी रिपॉज़िटरी के लिए सही है जिनमें ज़्यादातर स्टैटिक, नॉन-हायरार्किकल डेटा होता है. इस ट्रैवर्सल रणनीति का इस्तेमाल तब भी किया जा सकता है, जब बदलाव का पता लगाना मुश्किल हो या रिपॉज़िटरी में यह सुविधा काम न करती हो.

सूची को ट्रैवर्स करने की रणनीति

सूची को ट्रैवर्स करने की रणनीति, पूरी रिपॉज़िटरी को स्कैन करती है. इसमें सभी चाइल्ड नोड शामिल होते हैं. इससे हर आइटम की स्थिति का पता चलता है. इसके बाद, कनेक्टर दूसरी बार पास होता है और सिर्फ़ उन आइटम को इंडेक्स करता है जो नए हैं या जिन्हें पिछली इंडेक्सिंग के बाद अपडेट किया गया है. इस रणनीति का इस्तेमाल आम तौर पर, मौजूदा इंडेक्स में इंक्रीमेंटल अपडेट करने के लिए किया जाता है. इससे, इंडेक्स को अपडेट करते समय हर बार पूरा ट्रैवर्सल करने की ज़रूरत नहीं पड़ती.

यह ट्रैवर्सल रणनीति तब सही होती है, जब बदलाव का पता लगाना मुश्किल हो या रिपॉज़िटरी में बदलाव का पता लगाने की सुविधा काम न करती हो. इसके अलावा, यह रणनीति तब भी सही होती है, जब आपके पास गैर-अनुक्रमिक डेटा हो और आपको बहुत बड़े डेटा सेट के साथ काम करना हो.

ग्राफ़ ट्रैवर्सल

ग्राफ़ ट्रैवर्सल की रणनीति, पूरे पैरंट नोड को स्कैन करती है. इससे हर आइटम की स्थिति का पता चलता है. इसके बाद, कनेक्टर दूसरी बार पास होता है और सिर्फ़ उन आइटम को इंडेक्स करता है जो रूट नोड में नए हैं या जिन्हें पिछली इंडेक्सिंग के बाद अपडेट किया गया है. आखिर में, कनेक्टर सभी चाइल्ड आईडी पास करता है. इसके बाद, चाइल्ड नोड में मौजूद उन आइटम को इंडेक्स करता है जो नए हैं या जिन्हें अपडेट किया गया है. कनेक्टर, सभी चाइल्ड नोड में बार-बार तब तक खोज करता रहता है, जब तक सभी आइटम की जांच पूरी नहीं हो जाती. इस तरह के ट्रैवर्सल का इस्तेमाल आम तौर पर, क्रमबद्ध रिपॉज़िटरी के लिए किया जाता है. इनमें सभी आईडी की सूची बनाना व्यावहारिक नहीं होता.

यह रणनीति तब सही होती है, जब आपके पास क्रम के हिसाब से व्यवस्थित किया गया ऐसा डेटा हो जिसे क्रॉल करने की ज़रूरत हो. जैसे, डायरेक्ट्री या वेब पेजों की सीरीज़.

ट्रावर्सल की रणनीति लागू करना और आइटम इंडेक्स करना

Cloud Search में इंडेक्स किए जा सकने वाले हर एलिमेंट को Cloud Search API में आइटम कहा जाता है. कोई आइटम, फ़ाइल, फ़ोल्डर, CSV फ़ाइल में मौजूद कोई लाइन या डेटाबेस रिकॉर्ड हो सकता है.

स्कीमा रजिस्टर होने के बाद, इंडेक्स में डेटा भरने के लिए:

  1. (वैकल्पिक) इंडेक्सिंग के लिए, 100 केआईबी से बड़ी फ़ाइलें अपलोड करने के लिए items.upload का इस्तेमाल करें. छोटी फ़ाइलों के लिए, कॉन्टेंट को inlineContent के तौर पर एम्बेड करें. इसके लिए, items.index का इस्तेमाल करें.

  2. (ज़रूरी नहीं) इंडेक्सिंग के लिए मीडिया फ़ाइलें अपलोड करने के लिए, media.upload का इस्तेमाल करना.

  3. आइटम को इंडेक्स करने के लिए, items.index का इस्तेमाल किया जा रहा है. उदाहरण के लिए, अगर आपका स्कीमा movie schema में ऑब्जेक्ट की परिभाषा का इस्तेमाल करता है, तो किसी एक आइटम के लिए इंडेक्सिंग का अनुरोध इस तरह दिखेगा:

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": {
            "values": [
              "Titanic"
            ]
          }
        },
        {
          "name": "releaseDate",
          "dateValues": {
            "values": [
              {
                "year": 1997,
                "month": 12,
                "day": 19
              }
            ]
          }
        },
        {
          "name": "actorName",
          "textValues": {
            "values": [
              "Leonardo DiCaprio",
              "Kate Winslet",
              "Billy Zane"
            ]
          }
        },
        {
          "name": "genre",
          "enumValues": {
            "values": [
              "Drama",
              "Action"
            ]
          }
        },
        {
          "name": "userRating",
          "integerValues": {
            "values": [
              8
            ]
          }
        },
        {
          "name": "mpaaRating",
          "textValues": {
            "values": [
              "PG-13"
            ]
          }
        },
        {
          "name": "duration",
          "textValues": {
            "values": [
              "3 h 14 min"
            ]
          }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (ज़रूरी नहीं) items.get कॉल का इस्तेमाल करके, यह पुष्टि करें कि item को इंडेक्स किया गया है.

पूरी ट्रैवर्सल प्रोसेस को पूरा करने के लिए, आपको समय-समय पर पूरी रिपॉज़िटरी को फिर से इंडेक्स करना होगा. सूची या ग्राफ़ को ट्रैवर्स करने के लिए, आपको रिपॉज़िटरी में हुए बदलावों को मैनेज करने के लिए कोड लागू करना होगा.

डेटा स्टोर करने की जगह में हुए बदलावों को हैंडल करना

पूरी इंडेक्सिंग करने के लिए, किसी रिपॉज़िटरी से समय-समय पर हर आइटम को इकट्ठा और इंडेक्स किया जा सकता है. पूरी इंडेक्सिंग से यह पक्का किया जा सकता है कि आपका इंडेक्स अप-टू-डेट है. हालांकि, बड़ी या क्रमबद्ध रिपॉज़िटरी के लिए, पूरी इंडेक्सिंग महंगी हो सकती है.

पूरी रिपॉज़िटरी को बार-बार इंडेक्स करने के लिए इंडेक्स कॉल का इस्तेमाल करने के बजाय, Google Cloud Indexing Queue का इस्तेमाल किया जा सकता है. इससे बदलावों को ट्रैक किया जा सकता है और सिर्फ़ उन आइटम को इंडेक्स किया जा सकता है जिनमें बदलाव हुआ है. बाद में पोल करने और अपडेट करने के लिए, आइटम को कतार में पुश करने के लिए items.push अनुरोधों का इस्तेमाल किया जा सकता है. Google Cloud Indexing Queue के बारे में ज़्यादा जानकारी के लिए, Google Cloud Indexing Queue लेख पढ़ें.

Google Cloud Search API के बारे में ज़्यादा जानने के लिए, Cloud Search API पर जाएं.