Kā filtrēt, izmantojot CAML pakalpojumā SharePoint, soli pa solim

Kad sākat nopietni strādāt ar SharePoint sarakstiem un bibliotēkām , agrāk vai vēlāk rodas tā pati problēma: saskarnes filtri neizdodas . Filtrēšana pēc vairākām kolonnām, UN un VAI nosacījumu apvienošana, darbs ar relatīviem datumiem vai lietotājiem… tas viss ir iespējams, taču grafiskā saskarne ne vienmēr piedāvā pietiekami daudz. Šeit noder CAML.

CAML (Collaborative Application Markup Language — sadarbības lietojumprogrammu iezīmēšanas valoda) ir uz XML balstīta valoda, ko SharePoint izmanto, lai definētu vaicājumus, skatus, kārtošanu un daudzas citas iekšējās darbības. Izpratne par to, kā veidot un filtrēt, izmantojot CAML pakalpojumā SharePoint, ļauj maksimāli izmantot sarakstus neatkarīgi no tā, vai tie ir pieejami PowerShell, C#, JavaScript, CSOM, REST vai pat izstrādājot paplašinātus skatus.

Kas ir CAML un kāpēc tas ir galvenais filtrēšanai pakalpojumā SharePoint?

CAML ir SharePoint specifiska iezīmēšanas valoda, ko izmanto, lai aprakstītu, kādus datus vēlaties izgūt un kā vēlaties tos atgriezt. Tā nav programmēšanas valoda, bet gan strukturēts veids, kā pateikt SharePoint: "Dodiet man šos vienumus ar šiem nosacījumiem un šādā secībā."

Izstrādātāju un administratoru visbiežāk izmantotā daļa ir CAML vaicājuma bloks `<Where>` , kurā tiek definēti filtri. Tos var arī kombinēt ar tādiem mezgliem kā `<OrderBy>`, `<GroupBy>` vai `<RowLimit>`, lai vēl vairāk precizētu, kurus ierakstus saraksts atgriež.

Būtībā tipiskam CAML vaicājumam, kas filtrē datus SharePoint sarakstā, ir šāda vispārīga (vienkāršota) struktūra: <Query> <Where>…filters…</Where> <OrderBy>…</OrderBy> </Query> . Dažādie kolonnu nosacījumi ir savienoti kopā <Where> klauzulā.

SharePoint izmanto CAML fonā daudzās platformas funkcijās: sarakstu skatos, iekšējās meklēšanā, satura tīmekļa daļās, pielāgotās veidlapās un servera/klienta kodā . Citiem vārdiem sakot, pat ja jūs to neredzat, CAML vienmēr darbojas fonā.

Kad nepieciešams pārsniegt pamata saskarnes filtrus vai strādāt ar kodu, CAML zināšanas ir ļoti svarīgas, jo tās ļauj veidot sarežģītus un ļoti precīzus vaicājumus , kurus nebūtu iespējams definēt, vienkārši noklikšķinot uz lietotāja saskarnes.

CAML vaicājuma pamatstruktūra filtrēšanai pakalpojumā SharePoint

Lai efektīvi filtrētu ar CAML, ir jāsaprot tā pamatstruktūra. Uz filtru vērsts vaicājums parasti sastāv no trim galvenajām sadaļām: <Query>, <Where> un <OrderBy> . Dažreiz tiek izmantoti arī <ViewFields> vai <RowLimit>, taču svarīgākais filtrēšanas elements ir atrodams <Where>.

Visizplatītākais veids, kā izmantot CAML kodā, ir tādas metodes kā SPList.GetItems(SPQuery) servera puses modelī vai CSOM/JSOM vaicājumi, kur vaicājuma objekta Query īpašībai tiek piešķirta XML virkne. Šī virkne satur XML mezglus, kas norāda, kā filtrēt sarakstu.

Ļoti vienkāršs CAML vaicājuma piemērs, kas filtrē sarakstu pēc precīzas teksta kolonnas vērtības, varētu izskatīties šādi: <Query><Where><Eq><FieldRef Name='Title' /><Value Type='Text'>1. uzdevums</Value></Eq></Where></Query> . Lai gan sākumā sintakse var šķist stingra, tiklīdz izprotat modeli, mērogošana līdz sarežģītākiem nosacījumiem ir diezgan vienkārša.

Svarīgi ir saprast, ka katrs nosacījums tiek izteikts, izmantojot XML operatorus (Eq, Neq, Lt, Gt, Contains utt.) , vienmēr starp <FieldRef> (kolonnu) un <Value> (vērtību, ko meklējam). Pēc tam šos nosacījumus var ligzdot un kombinēt tik daudz, cik nepieciešams.

Daudzās CAML rokasgrāmatās jūs redzēsiet arī sadaļu <View>, kurā ietilpst <Query>, <ViewFields> un <RowLimit>. Filtrēšanai kritiski svarīgs ir tas, ko ievietojat <Where> iekšpusē , lai gan ir svarīgi paturēt prātā, ka <OrderBy> un <GroupBy> ietekmē arī rezultātu, ko redzat vai saņemat savā kodā.

Visbiežāk izmantotie filtrēšanas operatori CAML valodā

Runājot par filtrēšanu ar CAML pakalpojumā SharePoint, viss ir atkarīgs no pareizā operatora izvēles nosacījumam, kuru vēlaties lietot . CAML piedāvā diezgan lielu operatoru kopu, lai gan praksē ir neliela grupa, kas tiek konsekventi izmantota reālos projektos.

Visizplatītākie salīdzināšanas operatori ir: <Eq> (vienāds ar), <Neq> (nav vienāds ar), <Lt> (mazāks par), <Gt> (lielāks par), <Leq> (mazāks vai vienāds ar) un <Geq> (lielāks vai vienāds ar) . Tos galvenokārt izmanto ar skaitļiem, datumiem un dažiem teksta laukiem.

Ja tekstā ir jāmeklē virknes vai modeļi, tiek izmantoti tādi operatori kā <Contains> un <BeginsWith> . Pirmais pārbauda, ​​vai teksts kolonnā satur norādīto fragmentu, bet otrais apstiprina, vai kolonnas vērtība sākas ar noteiktu virkni. Tie ir ļoti noderīgi "meklēšanas tipa" filtriem teksta kolonnās.

Ir arī sarežģītāki operatori: <IsNull> un <IsNotNull>, lai noteiktu, vai kolonna ir tukša vai satur vērtību; <In>, lai pārbaudītu, vai lauka vērtība atrodas noteiktā vērtību sarakstā; un lietotājam un atļaujai specifiski operatori, piemēram, <Dalība>, ja nepieciešams filtrēt pēc grupas dalības.

Būla laukos parasti tiek izmantots `<Eq>` ar vērtībām patiess/aplams (vai to skaitlisko ekvivalentu 1/0 atkarībā no veida), savukārt meklēšanas, lietotāja vai pārvaldītajiem meklēšanas laukiem operatori ir jāapvieno ar konkrētiem vērtību tipiem (meklēšana, lietotājs utt.). Galu galā liela daļa CAML jaudas slēpjas precīzā operatora izvēlē, kas vislabāk atbilst katram kolonnas tipam.

Nosacījumu apvienošana: UN, VAI un filtru ligzdošana

Gandrīz jebkurā reālās pasaules scenārijā saraksta filtrēšana ietver vairāku nosacījumu izmantošanu vienlaikus . Piemēram, tiek atlasīti uzdevumi, kas piešķirti konkrētam lietotājam, kurš ir arī aktīvs un kam ir nākotnes izpildes datums. CAML ļauj apvienot nosacījumus, izmantojot divus loģiskos operatorus: UN un VAI.

Svarīgākais ir tas, ka <And> un <Or> tiek izmantoti kā mezgli, kas aptver divus iekšējos nosacījumus. Tas ir, katram <And> vai <Or> var būt tikai divi bērni , kas var būt vienkārši nosacījumi (Eq, Lt utt.) vai, savukārt, citi ligzdoti <And> un <Or>. Tādā veidā var ģenerēt jebkuras sarežģītības nosacījumu kokus.

Piemēram, lai filtrētu elementus, kuru stāvoklis ir “Aktīvs” un kuru prioritātes lauks ir “Augsts”, jums jāveido kaut kas līdzīgs šim: <Where><And>…stāvokļa nosacījums… …prioritātes nosacījums…</And></Where> . Un, ja jums ir jāapvieno UN un VAI, jūs ligzdotu vairākus šo loģisko operatoru slāņus.

Svarīgs apsvērums, apvienojot daudzus nosacījumus, ir novērtēšanas secība. Šo secību nosaka XML struktūra , nevis tipiskā UN/VAI prioritāte, kas atrodama citās valodās. Tāpēc ieteicams garīgi (vai uz papīra) vizualizēt, kā vēlaties grupēt katru filtru kopu, pirms to tulkot CAML formātā.

Sarežģītākos scenārijos, piemēram, filtrējot pēc vairākām kategorijām vai kombinētiem datumu diapazoniem, bieži vien rodas <AND> un <OR> struktūras ar trim vai četriem ligzdošanas līmeņiem. Šādos gadījumos ir ļoti svarīgi uzturēt XML pareizu formatējumu un dokumentāciju , lai izvairītos no pārslodzes, uzturot vaicājumu laika gaitā.

Kolonnu veidi un specifiska apstrāde CAML valodā

Viena no visbiežāk pieļautajām kļūdām, veidojot CAML filtrus, ir faktiskā kolonnu tipa neievērošana . Lai gan daudzas kolonnas vizuāli var šķist kā “teksta” kolonnas, SharePoint tās iekšēji apstrādā atšķirīgi, un CAML pieprasa norādīt pareizo tipu <Value> mezglā.

Viena teksta vai vairāku rindu kolonnās standarta variants ir Type='Text' vai Type='Note' apvienojumā ar tādiem operatoriem kā Eq, Neq, Contains vai BeginsWith. Tomēr skaitļu kolonnai ir nepieciešams Type='Number', un valūtas kolonnai parasti tiek izmantots Type='Currency'. Ja izmantosiet nepareizu tipu, filtrs neatgriezīs neko vai, vēl ļaunāk, neprecīzus rezultātus.

Datuma un laika kolonnas ir īpaši sensitīvas. CAML valodā tās tiek apstrādātas kā Type='DateTime' un tām ir jānodod vērtība ISO formātā (piemēram, 2026-03-29T00:00:00Z). Turklāt atribūtu IncludeTimeValue var izmantot, lai norādītu, vai ņemt vērā laiku vai tikai datumu.

Meklēšanas, lietotāja, vairāku izvēļu vai pārvaldītās meklēšanas laukos apstrāde atšķiras. Lietotāja laukam parasti tiek izmantots Type='User' vai 'Integer' ar lietotāja iekšējo ID , savukārt meklēšanas lauki darbojas ar Type='Lookup' un bieži vien ar avota sarakstā esošā elementa ID.

Vēl viena īpaša grupa ir Būla kolonnas, kuras parasti apstrādā ar tipu Type='Integer' (0 vai 1) vai tipu Type='Boolean' (TRUE/FALSE) atkarībā no tā, kā kolonna ir iekšēji definēta. Filtrējot ir ļoti svarīgi pārbaudīt Microsoft dokumentāciju vai piemēru rīkus, lai redzētu, kādu tipa un vērtības kombināciju CAML sagaida katrā konkrētajā gadījumā.

Filtrēšana pēc datumiem CAML: diapazoni, šodiena un relatīvie datumi

Daudzi sarežģīti SharePoint sarakstu vaicājumi ir saistīti ar laiku: nesen izveidotie vienumi, gaidāmie izpildes datumi, nokavētie uzdevumi utt. CAML piedāvā dažādas filtrēšanas iespējas pēc datumiem, taču jums ir jāpārzina sintakse un formatējums.

Precīzam datumam mezglā tiek izmantota noteikta DateTime vērtība. Tomēr visizplatītākā pieeja ir filtrēšana pēc diapazoniem, apvienojot tādus operatorus kā un tajā pašā kolonnā. Tas ļauj iegūt, piemēram, visus elementus starp diviem konkrētiem datumiem.

SharePoint arī ļauj izmantot īpašus marķierus dažās skata izteiksmēs un noteiktos vaicājumos, īpaši strādājot ar uzlaboto filtrēšanas saskarni vai automātiski ģenerētu CAML. Šie marķieri apzīmē pašreizējo datumu (ar laiku vai bez tā) vaicājuma izpildes brīdī.

Papildus tam ir veidi, kā izmantot relatīvos datumus, izmantojot nobīdes , piemēram, lai iegūtu vienumus no pēdējām 7 dienām vai nākamajām 30 dienām. Iekšēji šīs izteiksmes tiek tulkotas kā salīdzinājumi ar modificēto pašreizējo datumu, taču precīzas sintakses detaļas var atšķirties atkarībā no tā, vai tās tiek izmantotas skatos, servera puses kodā vai REST.

Ir svarīgi arī ņemt vērā laika joslu un to, kā datumi tiek glabāti iekšēji. SharePoint iekšēji saglabā datuma/laika vērtības UTC formātā un pēc tam prezentācijā piemēro laika joslas korekcijas . Ja manuāli veidojat datumus CAML no koda, ieteicams ievērot konsekventu pieeju un vienmēr strādāt ar UTC, lai izvairītos no novecojušiem rezultātiem.

Filtrēšana pēc lietotāja un atļaujām CAML

Vēl viena izplatīta vajadzība ir ierobežot saraksta rezultātus līdz vienumiem, kas saistīti ar pašreizējo lietotāju vai noteiktas grupas dalībniekiem. CAML ietver īpašus operatorus lietotāju lauku un uz dalību balstītu kritēriju apstrādei.

Lai filtrētu pēc konkrēta lietotāja kolonnā Persona vai Grupa, parasti tiek izmantots `<Eq>` ar `Type='Integer'` vai `Type='User'` un lietotāja iekšējais SharePoint ID tiek nodots `<Value>` mezglā. Šis ID parasti tiek iegūts no lietotāja konteksta vai izmantojot iepriekšēju vaicājumu kodā.

Turklāt operators `<Dalība>` ļauj izveidot filtrus, pamatojoties uz pašreizējā lietotāja dalību grupās, vietnēs vai auditorijās. Piemēram, varat izveidot nosacījumu, kas atlasa vienumus, kuros lietotāja kolonnā ir tās pašas SharePoint grupas dalībnieki kā lietotājam, kurš izpilda vaicājumu.

Apvienojot ar tādiem operatoriem kā un Tādi scenāriji kā "man vai manai komandai piešķirtie vienumi", "vienumi no manas nodaļas" utt. tiek sasniegti bez nepieciešamības stingri iekodēt konkrētus lietotājus vaicājuma XML failā.

Tas viss padara CAML par ļoti spēcīgu rīku datu līmeņa drošības ieviešanai neatkarīgi no tā, vai tiek filtrēti skati, tīmekļa daļas vai kods. Lai gan patiesa drošība ir atkarīga no atļaujām, filtrēšana pēc lietotāja palīdz parādīt tikai atbilstošo informāciju un uzlabot lietotāja pieredzi.

CAML izmantošana kodā: serverī, klientā un REST

Filtrēšana ar CAML pakalpojumā SharePoint neaprobežojas tikai ar skatiem, kas konfigurēti no saskarnes. Patiesībā vismodernākā izmantošana notiek, kad CAML ir integrēts kodā , neatkarīgi no tā, vai tas ir no servera objekta modeļa, no CSOM/JSOM vai pat REST izsaukumos.

Klasiskajā servera modelī (SharePoint lokālajā vidē) tiek izveidots SPQuery objekts, un tā rekvizītam Query tiek piešķirta CAML virkne. Pēc tam tiek izsauktas tādas metodes kā SPList.GetItems(SPQuery) , lai izgūtu tikai tos vienumus, kas atbilst filtriem. Šeit papildus sadaļai <Where> var konfigurēt arī <RowLimit> un lappušu numerācijas opcijas.

Ar CSOM (klienta puses objektu modeli) un JSOM (JavaScript objektu modeli) pieeja ir līdzīga, bet tiek izpildīta no klienta lietojumprogrammām vai skriptiem. Tiek definēts vaicājuma objekts, piešķirts CAML fragments un elementa augšupielāde tiek veikta SharePoint serverī, kas apstrādā vaicājumu fonā.

Strādājot ar SharePoint REST API, filtrēšana parasti tiek veikta, izmantojot OData parametrus, piemēram, `$filter`, taču daudzos iekšējos SharePoint scenārijos šie filtri tiek tulkoti CAML valodā , lai izpildītu faktisko vaicājumu. Turklāt ir galapunkti un funkcijas, kas ļauj tieši iekļaut CAML blokus pieprasījuma pamattekstā.

Jebkurā gadījumā, neatkarīgi no izmantotā modeļa, princips ir viens un tas pats: pareizi jāveido CAML vaicājums un jānodrošina, ka XML ir derīgs . Daudzas tipiskas kļūdas (nepareizi aizvērtas iekavas, nesakārtoti tagi, nepareizi datu tipi) rada tukšus rezultātus vai izpildlaika izņēmumus.

Rīki un labākā prakse CAML vaicājumu rakstīšanai

CAML sintakse ir ļoti stingra, un, ja to rakstāt manuāli neapstrādātā veidā, ir viegli pieļaut kļūdas. Tāpēc, veidojot un uzturot sarežģītus vaicājumus, ieteicams izmantot rīkus un ievērot noteiktu labāko praksi .

Klasisks ieteikums ir izmantot CAML ģeneratorus jeb "veidotājus", kas ļauj veidot vaicājumus ar lietotājam draudzīgāku saskarni un pēc tam iegūt XML . Daudzi administratori un izstrādātāji izmanto arī Microsoft dokumentētus piemērus un iepriekšējos projektos pārbaudītus koda fragmentus.

Vēl viena laba prakse ir XML validēšana pirms tā izmantošanas ražošanas vidē. Tas nozīmē ne tikai nodrošināt, lai XML būtu pareizi veidots, bet arī pārliecināties, ka kolonnu nosaukumi (FieldRef Name) ir pareizi , datu tipi atbilst sarakstā norādītajiem un izmantotie operatori ir saderīgi ar šo lauka tipu.

Plašās konsultācijās ar daudziem un Ļoti palīdz XML formatēšana ar skaidru atkāpi un, ja iespējams, komentāru atstāšana pašā kodā, kas paskaidro katra bloka darbību. Tas novērš situāciju, ka mēnešiem vēlāk kļūst neiespējami saprast, kāpēc tika izveidota konkrēta filtra struktūra.

Visbeidzot, pirms vaicājumu lietošanas lieliem sarakstiem ieteicams tos pārbaudīt ar dažiem elementiem . Tas ļauj precīzi noregulēt filtrēšanas loģiku, neietekmējot veiktspēju un nepārslogojot serveri ar slikti formulētiem vaicājumiem.

CAML apgūšana filtrēšanai pakalpojumā SharePoint prasa laiku, taču pūles ir tā vērtas: galu galā jūs iegūstat ļoti precīzu kontroli pār to, kādi dati tiek izgūti, kā kritēriji tiek apvienoti un kā tie tiek attēloti , kas ir praktiski svarīgi korporatīvā vidē ar lielu informācijas apjomu.