streamalism.org

1. הקדמה

כל מי שעבד עם Elasticsearch יודע שבניית שאילתות המשתמשות בממשק ה- API של RESTful שלהם יכולה להיות מייגעת ונוטה לטעויות.

במדריך זה נבחן את Jest, לקוח Java של HTTP עבור Elasticsearch. בעוד Elasticsearch מספק לקוח Java מקורי משלו, Jest מספק ממשק API שוטף יותר וממשקים קלים יותר לעבודה.

2. תלות של Maven

הדבר הראשון שעלינו לעשות הוא לייבא את ספריית Jest ל- POM שלנו:

 io.searchbox jest 6.3.1 

הגרסה של Jest עוקבת אחר זו של המוצר הראשי של Elasticsearch. זה עוזר להבטיח תאימות בין לקוח לשרת.

על ידי הכללת התלות ב- Jest, ספריית Elasticsearch המתאימה תיכלל כתלות מעבר.

3. שימוש ב- Jest Client

בחלק זה נבחן שימוש בלקוח Jest לביצוע משימות נפוצות עם Elasticsearch.

כדי להשתמש בלקוח Jest, אנו פשוט יוצרים a JestClient אובייקט באמצעות JestClientFactory. חפצים אלה יקרים ליצירה והם בטוחים בחוטים, אז ניצור מופע של סינגלטון שניתן לשתף בכל היישום שלנו:

JestClient ציבורי jestClient () {JestClientFactory מפעל = JestClientFactory חדש (); factory.setHttpClientConfig (חדש HttpClientConfig.Builder ("// localhost: 9200") .multiThreaded (true) .defaultMaxTotalConnectionPerRoute (2) .maxTotalConnection (10) .build ()); להחזיר factory.getObject (); }

פעולה זו תיצור לקוח Jest המחובר ללקוח Elasticsearch הפועל באופן מקומי. אמנם דוגמא לחיבור זו היא טריוויאלית, ל- Jest יש גם תמיכה מלאה ב- proxies, SSL, אימות ואפילו גילוי צומת.

ה JestClient הכיתה היא כללית ויש בה רק קומץ שיטות ציבוריות. העיקרי שנשתמש בו הוא לבצע, שלוקח מופע של ה- פעולה מִמְשָׁק. לקוח Jest מספק כמה שיעורי בנייה שיעזרו ליצור פעולות שונות אשר מתקשרות עם Elasticsearch.

התוצאה של כל שיחות Jest היא מופע של JestResult. נוכל לבדוק הצלחה על ידי התקשרות זה הצליח. עבור פעולות לא מוצלחות, אנו יכולים להתקשר getErrorMessage לקבלת פרטים נוספים:

JestResult jestResult = jestClient.execute (Delete.Builder חדש ("1"). אינדקס ("עובדים"). Build ()); אם (jestResult.isSucceeded ()) {System.out.println ("הצלחה!"); } אחר {System.out.println ("שגיאה:" + jestResult.getErrorMessage ()); }

3.1. ניהול מדדים

כדי לבדוק אם קיים אינדקס, אנו משתמשים ב- מדדים קיימים פעולה:

תוצאת JestResult = jestClient.execute (חדש IndicesExists.Builder ("עובדים"). Build ()) 

כדי ליצור אינדקס, אנו משתמשים ב- CreateIndex פעולה:

jestClient.execute (חדש CreateIndex.Builder ("עובדים"). build ());

פעולה זו תיצור אינדקס עם הגדרות ברירת מחדל. אנו יכולים לעקוף הגדרות ספציפיות במהלך יצירת האינדקס:

הגדרות מפה = HashMap חדש (); settings.put ("number_of_shards", 11); settings.put ("number_of_replicas", 2); jestClient.execute (חדש CreateIndex.Builder ("עובדים"). הגדרות (הגדרות) .build ());

ויצירה או שינוי של כינויים היא גם פשוטה באמצעות ModifyAliases פעולה:

jestClient.execute (ModifyAliases.Builder חדש (AddAliasMapping.Builder חדש ("עובדים", "e"). build ()). build ()); jestClient.execute (ModifyAliases.Builder חדש (RemoveAliasMapping.Builder חדש ("עובדים", "e"). build ()). build ());

3.2. יצירת מסמכים

לקוח Jest מקל על אינדקס - או יצירת - מסמכים חדשים באמצעות ה- אינדקס מעמד פעולה. מסמכים בחיפוש אלסטיקה הם רק נתוני JSON, וישנן מספר דרכים להעביר נתוני JSON ללקוח Jest לאינדקס.

לדוגמא זו, בואו נשתמש במסמך עובד דמיוני:

{"name": "Michael Pratt", "title": "Java Developer", "skills": ["java", "spring", "elasticsearch"], "yearsOfService": 2}

הדרך הראשונה לייצג מסמך JSON היא באמצעות Java חוּט. אמנם אנו יכולים ליצור באופן ידני את מחרוזת JSON, אך עלינו לשים לב לעיצוב נכון, לסוגריים ולתווי הציטוט הנמלטים.

לכן קל יותר להשתמש בספריית JSON כמו ג'קסון כדי לבנות את מבנה JSON שלנו ואז להמיר ל- חוּט:

ממפה ObjectMapper = ObjectMapper חדש (); עובד JsonNode JsonNode = mapper.createObjectNode () .put ("שם", "Michael Pratt") .put ("title", "Java Developer") .put ("yearsOfService", 2) .set ("skills", mapper. createArrayNode () .add ("java") .add ("spring") .add ("elasticsearch")); jestClient.execute (Index.Builder חדש (עובדJsonNode.toString ()). אינדקס ("עובדים"). build ());

אנו יכולים גם להשתמש בג'אווה מַפָּה לייצג את נתוני JSON ולהעביר את זה ל- אינדקס פעולה:

מפה עובדHashMap = חדש LinkedHashMap (); עובדHashMap.put ("שם", "מייקל פראט"); עובדHashMap.put ("כותרת", "מפתח Java"); employeeHashMap.put ("yearsOfService", 2); workerHashMap.put ("כישורים", Arrays.asList ("ג'אווה", "קפיץ", "חיפוש אלסטיות")); jestClient.execute (Index.Builder חדש (עובדHashMap). אינדקס ("עובדים"). build ());

לבסוף, לקוח Jest יכול לקבל כל POJO שמייצג את המסמך לאינדקס. בוא נגיד שיש לנו עוֹבֵד מעמד:

שכבה ציבורית עובד {שם מחרוזת; כותרת מחרוזת; רשימת מיומנויות; int yearsOfService; }

אנו יכולים להעביר מופע של מעמד זה ישירות ל- אינדקס בּוֹנֶה:

עובד שכיר = עובד חדש (); employee.setName ("מייקל פראט"); employee.setTitle ("Java Developer"); employee.setYearsOfService (2); employee.setSkills (Arrays.asList ("java", "spring", "elasticsearch")); jestClient.execute (Index.Builder חדש (עובד) .index ("עובדים"). build ());

3.3. קריאת מסמכים

ישנן שתי דרכים עיקריות לגשת למסמך מ- Elasticsearch באמצעות לקוח Jest. ראשית, אם אנו יודעים את מזהה המסמך, אנו יכולים לגשת אליו ישירות באמצעות ה- לקבל פעולה:

jestClient.execute (Get.Builder חדש ("עובדים", "17"). build ());

כדי לגשת למסמך שהוחזר, עלינו להתקשר לאחד מהשונים getSource שיטות. אנו יכולים לקבל את התוצאה כ- JSON גולמי או לבטל אותה מחדש ל DTO:

עובד GetResult = jestClient.execute (Get.Builder חדש ("עובדים", "1"). Build ()) .getSourceAsObject (שכיר עובד);

הדרך השנייה לגשת למסמכים היא באמצעות שאילתת חיפוש, אשר מיושמת ב- Jest עם ה- לחפש פעולה.

לקוח Jest תומך בשאילתת DSL המלאה של אלסטיקס. בדיוק כמו פעולות הוספה לאינדקס, שאילתות מתבטאות כמסמכי JSON, וישנן דרכים רבות לבצע חיפושים.

ראשית, נוכל להעביר מחרוזת JSON המייצגת את שאילתת החיפוש. כזכור, עלינו לדאוג להבטיח שהמחרוזת תימלט כהלכה ותקפה JSON:

חיפוש מחרוזת = "{" + "\" שאילתה \ ": {" + "\" bool \ ": {" + "\" חייב \ ": [" + "{\" להתאים \ ": {\" שם \ ": \" מייקל פראט \ "}}" + "]" + "}" + "}" + "}"; jestClient.execute (Search.Builder חדש (חיפוש) .build ());

כמו עם אינדקס בפעולה לעיל, נוכל להשתמש בספריה כמו ג'קסון כדי לבנות את מחרוזת השאילתות של JSON.

בנוסף, אנו יכולים גם להשתמש בממשק ה- API לשאילתת Elasticsearch המקורי. החיסרון היחיד בכך הוא שהיישום שלנו צריך להיות תלוי בספריית Elasticsearch המלאה.

עם ה לחפש פעולה, ניתן לגשת למסמכים התואמים באמצעות getSource שיטות. למרות זאת, ג'סט מספק גם את מכה class, שעוטף את המסמכים התואמים ומספק מטא נתונים על התוצאות. משתמש ב מכה בכיתה, אנו יכולים לגשת למטא נתונים נוספים לכל תוצאה: ציון, ניתוב והסבר לתוצאות, עד כמה שם:

רשימה searchResults = jestClient.execute (Search.Builder חדש (חיפוש) .build ()) .getHits (שכיר עובד); searchResults.forEach (hit -> {System.out.println (String.format ("למסמך% s יש ציון% s", hit.id, hit.score);});

3.4. עדכון מסמכים

Jest מספק פשוט עדכון פעולה לעדכון מסמכים:

employee.setYearOfService (3); jestClient.execute (Update.Builder חדש (עובד) .index ("עובדים"). id ("1"). build ());

הוא מקבל את אותן ייצוגי JSON כמו אינדקס פעולה שראינו קודם לכן, מה שמקל על שיתוף הקוד בין שתי הפעולות.

3.5. מחיקת מסמכים

מחיקת מסמך מאינדקס מתבצעת באמצעות לִמְחוֹק פעולה. זה דורש רק שם אינדקס ותעודת זהות:

jestClient.execute (Delete.Builder חדש ("17") .index ("עובדים") .build ());

4. פעולות גורפות

לקוח Jest תומך גם בפעולות בתפזורת. המשמעות היא שנוכל לחסוך זמן ורוחב פס על ידי שליחת פעולות מרובות יחד בו זמנית.

משתמש ב תִפזוֹרֶת פעולה, נוכל לשלב כל מספר בקשות לשיחה אחת. אנו יכולים אפילו לשלב סוגים שונים של בקשות יחד:

jestClient.execute (Bulk.Builder חדש () .defaultIndex ("עובדים") .addAction (אינדקס חדש. Builder (עובדObject1) .build ()) .addAction (Index.Builder חדש (עובדObject2) .build ()) .addAction ( Delete.Builder חדש ("17"). build ()) .build ());

5. פעולות אסינכרוניות

לקוח Jest תומך גם בפעולות אסינכרוניות, כלומר אנו יכולים לבצע כל אחת מהפעולות הנ"ל באמצעות קלט / פלט שאינו חוסם.

כדי להפעיל פעולה בצורה אסינכרונית, פשוט השתמש ב- executeAsync שיטת הלקוח:

jestClient.executeAsync (Index.Builder חדש (עובדObject1) .build (), JestResultHandler חדש () {@Override בטל ציבורי הושלם (JestResult תוצאה) {// התוצאה של התנהלות} @Override בטל ציבורי נכשל (יוצא מן הכלל חריג) }});

שים לב שבנוסף לפעולה (אינדקס במקרה זה), הזרימה האסינכרונית דורשת גם a JestResultHandler. לקוח Jest יקרא לאובייקט זה לאחר סיום הפעולה. לממשק שתי שיטות - הושלם ו נִכשָׁל - המאפשרים טיפול בהצלחה או כישלון הפעולה, בהתאמה.

6. מסקנה

במדריך זה, הסתכלנו בקצרה על לקוח Jest, לקוח Java RESTful עבור Elasticsearch.

למרות שכיסינו רק חלק קטן מהפונקציונליות שלו, ברור ש- Jest הוא לקוח חזק של Elasticsearch. שיעורי הבנאי הרהוטים והממשקים RESTful מקלים על הלימוד והתמיכה המלאה בממשקי Elasticsearch הופכים אותו לחלופה מסוגלת ללקוח המקורי.

כמו תמיד, כל דוגמאות הקוד במדריך הסתיימו ב- GitHub.