Node.js और Oracle डेटाबेस के साथ REST API बनाना। भाग 5

भाग 5. एक रीस्ट एपीआई बनाना: पेजिनेशन, मैनुअल सॉर्टिंग और फ़िल्टरिंग

पिछले लेख में, आपने CRUD API की मुख्य कार्यक्षमता का निर्माण किया।

और अब, जब कर्मचारियों के मार्ग पर HTTP GET अनुरोध जारी किया जाता है, तो तालिका की सभी पंक्तियाँ वापस आ जाती हैं। यह HR.EMPLOYEES तालिका में केवल 107 पंक्तियों के साथ अधिक मायने नहीं रखता है, लेकिन कल्पना करें कि यदि तालिका में हजारों या लाखों पंक्तियाँ हों तो क्या होगा। मोबाइल और वेब एप्लिकेशन जैसे ग्राहक आमतौर पर डेटाबेस में उपलब्ध पंक्तियों का कुछ अंश ही प्रदर्शित करते हैं, और तब आवश्यक होने पर अधिक पंक्तियों का चयन करते हैं - शायद जब उपयोगकर्ता स्क्रॉल करता है या कुछ विराम नियंत्रण पर "अगला" बटन क्लिक करता है उपयोगकर्ता इंटरफ़ेस में पृष्ठों के लिए।

इसके लिए, REST API को लौटे परिणामों के लिए पेजिनेशन टूल का समर्थन करना चाहिए। एक बार जब पृष्ठांकन का समर्थन किया जाता है, तो छँटाई क्षमता आवश्यक हो जाती है, क्योंकि आमतौर पर पृष्ठांकन लागू होने से पहले डेटा को क्रमबद्ध किया जाना चाहिए। इसके अलावा, डेटा फ़िल्टरिंग टूल प्रदर्शन के लिए बहुत महत्वपूर्ण है। डेटाबेस से डेटा क्यों भेजें, मध्यवर्ती परत के माध्यम से और पूरी तरह से क्लाइंट के लिए, यदि यह आवश्यक नहीं है?

मैं URL क्वेरी स्ट्रिंग पैरामीटर का उपयोग करूंगा ताकि क्लाइंट निर्दिष्ट कर सकें कि परिणाम कैसे पृष्ठांकित, सॉर्ट किए गए और फ़िल्टर किए जाने चाहिए। हमेशा की तरह प्रोग्रामिंग में, कार्यान्वयन आपकी आवश्यकताओं, प्रदर्शन लक्ष्यों आदि के आधार पर भिन्न हो सकता है। इस पोस्ट में मैं आपको इन कार्यों को एपीआई में जोड़ने के लिए एक मैनुअल दृष्टिकोण के बारे में बताऊंगा।

पृष्ठ पर अंक लगाना

क्वेरी स्ट्रिंग पैरामीटर जो मैं पेजिनेशन के लिए उपयोग करूंगा: छोड़ें और सीमित करें। स्किप पैरामीटर का उपयोग निर्दिष्ट संख्याओं को छोड़ने के लिए किया जाएगा, जबकि सीमा सीमित लाइनों की संख्या को लौटाएगी। यदि ग्राहक मूल्य प्रदान नहीं करता है तो मैं सीमा के लिए 30 के डिफ़ॉल्ट मान का उपयोग करूंगा।

क्वेरी स्ट्रिंग से मान निकालने के लिए कंट्रोलर लॉजिक को अपडेट करके शुरू करें और उन्हें डेटाबेस एपीआई में पास करें। नियंत्रकों / कर्मचारी.जेएस फ़ाइल खोलें और कोड के निम्नलिखित पंक्तियों को उस रेखा के बाद फ़ंक्शन में जोड़ें, जो req.params.id पैरामीटर को पार्स करती है।

// *** line that parses req.params.id is here *** context.skip = parseInt(req.query.skip, 10); context.limit = parseInt(req.query.limit, 10); 

अब आपको इन मूल्यों को ध्यान में रखने के लिए डेटाबेस तर्क को अपडेट करने और तदनुसार SQL क्वेरी को अपडेट करने की आवश्यकता है। SQL में, ऑफसेट क्लॉज का उपयोग पंक्तियों को छोड़ने के लिए किया जाता है, और क्वेरी द्वारा लौटी पंक्तियों की संख्या को सीमित करने के लिए लाने के लिए क्लॉज का उपयोग किया जाता है। हमेशा की तरह, मान सीधे क्वेरी में नहीं जोड़े जाएंगे - इसके बजाय, उन्हें प्रदर्शन और सुरक्षा कारणों से बाइंड चर के रूप में जोड़ा जाएगा। Db_apis / कर्मचारी.js खोलें और खोज फ़ंक्शन में ब्लॉक होने के बाद निम्न कोड जोड़ें, जिसमें अनुरोध के लिए क्लॉज़ जोड़ा गया है।

 // *** if block that appends where clause ends here *** if (context.skip) { binds.row_offset = context.skip; query += '\noffset :row_offset rows'; } const limit = (context.limit > 0) ? context.limit : 30; binds.row_limit = limit; query += '\nfetch next :row_limit rows only'; 

यह सब आपको पेजेट करने के लिए करने की आवश्यकता है! एपीआई लॉन्च करें, और फिर इसे परीक्षण करने के लिए दूसरे टर्मिनल में कुछ URL कमांड चलाएं। यहां कुछ उदाहरण दिए गए हैं जिनका आप उपयोग कर सकते हैं:

 # use default limit (30) curl "http://localhost:3000/api/employees" # set limit to 5 curl "http://localhost:3000/api/employees?limit=5" # use default limit and set skip to 5 curl "http://localhost:3000/api/employees?skip=5" # set both skip and limit to 5 curl "http://localhost:3000/api/employees?skip=5&limit=5" 

छंटाई

न्यूनतम पर, ग्राहकों को सॉर्ट और ऑर्डर करने के लिए एक कॉलम निर्दिष्ट करना चाहिए (आरोही या अवरोही)। ऐसा करने का सबसे आसान तरीका एक क्वेरी पैरामीटर (मैं सॉर्ट का उपयोग करेगा) को परिभाषित करने के लिए है, जो आपको 'last_name: asc' या 'salary: desc' जैसे स्ट्रिंग को पास करने की अनुमति देता है। SQL क्वेरी से लौटाए गए परिणाम सेट के आदेश की गारंटी देने का एकमात्र तरीका खंड द्वारा आदेश को शामिल करना है। इस कारण से, जब ग्राहक इसे निर्दिष्ट नहीं करता है तो स्थिरता सुनिश्चित करने के लिए एक डिफ़ॉल्ट ऑर्डर परिभाषा को परिभाषित करना अच्छा होगा।

नियंत्रकों / कर्मचारी के पास वापस जाएं। req.query.limit पैरामीटर को पार्स करने वाली लाइन के बाद प्राप्त फ़ंक्शन के लिए कोड की निम्न पंक्ति जोड़ें।

 // *** line that parses req.query.limit is here *** context.sort = req.query.sort; 

फिर db_apis / कर्मचारी.js खोलें और बेस लाइन घोषित करने और आरंभ करने के लिए नीचे दी गई पंक्ति जोड़ें।

 // *** lines that initalize baseQuery end here *** const sortableColumns = ['id', 'last_name', 'email', 'hire_date', 'salary']; 

SortableColumns स्तंभों का एक श्वेतसूची है जिसे ग्राहक क्रमबद्ध करने के लिए उपयोग कर सकते हैं। फिर, खोज फ़ंक्शन के अंदर, निम्न जोड़ें यदि ब्लॉक, जो खंड द्वारा आदेश जोड़ता है। यह जहां क्लॉज जोड़ने के बाद किया जाना चाहिए, लेकिन ऑफसेट और लाने से पहले।

 // *** if block that appends where clause ends here *** if (context.sort === undefined) { query += '\norder by last_name asc'; } else { let [column, order] = context.sort.split(':'); if (!sortableColumns.includes(column)) { throw new Error('Invalid "sort" column'); } if (order === undefined) { order = 'asc'; } if (order !== 'asc' && order !== 'desc') { throw new Error('Invalid "sort" order'); } query += `\norder by "${column}" ${order}`; } 

यदि क्लाइंट सॉर्ट वैल्यू पास करता है, तो ब्लॉक का पहला भाग चेक करता है। यदि नहीं, तो एसक्यूएल क्वेरी में क्लॉज़ द्वारा डिफ़ॉल्ट ऑर्डर जोड़ा जाता है, जो आरोही क्रम में last_name द्वारा सॉर्ट करता है। यदि एक सॉर्ट मान निर्दिष्ट किया जाता है, तो इसे पहले कॉलम और ऑर्डर वैल्यू में विभाजित किया जाता है, और क्वेरी द्वारा ऑर्डर जोड़ने से पहले प्रत्येक वैल्यू की जांच की जाती है।

अब आप इसे मान्य करने के लिए कई URL कमांड चला सकते हैं। यहाँ कुछ उदाहरण दिए गए हैं:

 # use default sort (last_name asc) curl "http://localhost:3000/api/employees" # sort by id and use default direction (asc) curl "http://localhost:3000/api/employees?sort=id" # sort by hire_date desc curl "http://localhost:3000/api/employees?sort=hire_date:desc" # use sort with limit and skip together curl "http://localhost:3000/api/employees?limit=5&skip=5&sort=salary:desc" # should throw an error because first_name is not whitelisted curl "http://localhost:3000/api/employees?sort=first_name:desc" # should throw an error because 'other' is not a valid order curl "http://localhost:3000/api/employees?sort=last_name:other" 

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

छानने

डेटा को फ़िल्टर करने की क्षमता एक महत्वपूर्ण विशेषता है जो सभी REST API को प्रदान करनी चाहिए। छँटाई के साथ, जो आप समर्थन करना चाहते हैं, उसके आधार पर कार्यान्वयन सरल या जटिल हो सकता है। सबसे आसान तरीका पूर्ण मिलान फ़िल्टर (उदाहरण के लिए, last_name = Doe) के लिए समर्थन जोड़ना है। अधिक जटिल कार्यान्वयन बुनियादी ऑपरेटरों (उदाहरण के लिए, <,>, instr, आदि) और जटिल तार्किक ऑपरेटरों (उदाहरण के लिए, और / या) के लिए समर्थन जोड़ सकते हैं जो एक साथ कई फ़िल्टर समूह कर सकते हैं।

इस पोस्ट में मैं स्थिति को सरल बनाने का प्रयास करूंगा और केवल दो कॉलमों के लिए फ़िल्टर समर्थन जोड़ूंगा: Department_id और manager_id। प्रत्येक कॉलम के लिए, मैं क्वेरी स्ट्रिंग में संबंधित पैरामीटर को सक्षम करूंगा। डेटाबेस तर्क जिसमें GET के अनुरोध को एक कर्मचारी के साथ अंतिम बिंदु पर भेजा जाता है, जहां क्लॉज जोड़ता है, इन नए फिल्टर को ध्यान में रखने के लिए अद्यतन करने की आवश्यकता है।

नियंत्रकों / कर्मचारी खोलें ।js और पंक्ति के नीचे निम्नलिखित पंक्तियों को जोड़ें जो कि फ़ंक्शन में req.query.sort मान को पार्स करता है।

 // *** line that parses req.query.sort is here *** context.department_id = parseInt(req.query.department_id, 10); context.manager_id = parseInt(req.query.manager_id, 10); 

फिर आधार क्वेरी में 1 = 1 वाक्य जोड़ने के लिए db_apis / कर्मचारी.js को संपादित करें, जैसा कि नीचे दिखाया गया है।

 const baseQuery = `select employee_id "id", first_name "first_name", last_name "last_name", email "email", phone_number "phone_number", hire_date "hire_date", job_id "job_id", salary "salary", commission_pct "commission_pct", manager_id "manager_id", department_id "department_id" from employees where 1 = 1`; 

बेशक, 1 = 1 हमेशा सच होगा, इसलिए अनुकूलक केवल इसे अनदेखा करेगा। हालांकि, यह विधि भविष्य में अतिरिक्त विधेय के अतिरिक्त को सरल बनाएगी।

खोज फ़ंक्शन में, यदि निम्न संदर्भों के साथ, संदर्भ खंड को पार करते समय, जहां खंड जोड़ता है, तो उस ब्लॉक को प्रतिस्थापित करें।

 // *** line that declares 'binds' is here *** if (context.id) { binds.employee_id = context.id; query += '\nand employee_id = :employee_id'; } if (context.department_id) { binds.department_id = context.department_id; query += '\nand department_id = :department_id'; } if (context.manager_id) { binds.manager_id = context.manager_id; query += '\nand manager_id = :manager_id'; } 

जैसा कि आप देख सकते हैं, प्रत्येक यदि ब्लॉक केवल बाइंड ऑब्जेक्ट के लिए दिए गए मान को जोड़ता है, और फिर उसी खंड को संबंधित विधेय को जोड़ता है जहां। परिवर्तनों को सहेजें और API को पुनरारंभ करें। फिर इसे सत्यापित करने के लिए इन URL कमांड का उपयोग करें:

 # filter where department_id = 90 (returns 3 employees) curl "http://localhost:3000/api/employees?department_id=90" # filter where manager_id = 100 (returns 14 employees) curl "http://localhost:3000/api/employees?manager_id=100" # filter where department_id = 90 and manager_id = 100 (returns 2 employees) curl "http://localhost:3000/api/employees?department_id=90&manager_id=100" 

यह बात है - एपीआई अब पृष्ठांकन, छँटाई और छानने का समर्थन करता है! एक मैनुअल दृष्टिकोण बहुत नियंत्रण प्रदान करता है, लेकिन बहुत सारे कोड की आवश्यकता होती है। खोज फ़ंक्शन में अब 58 लाइनें हैं और केवल सीमित छंटाई और फ़िल्टरिंग क्षमताओं का समर्थन करता है। आप इन कार्यों को सरल बनाने के लिए Knex.js क्वेरी बिल्डर जैसे किसी मॉड्यूल का उपयोग करने पर विचार कर सकते हैं।