Ֆիլտրում
Հավաքածուները ռեսուրսների ցուցակներ են։ Decoupled կայքերում դրանք են, որոնք օգտագործվում են, օրինակ, «Նոր բովանդակություն» ցուցակ կամ «Իմ բովանդակությունը» բաժին ստեղծելու համար հաճախորդի կողմում։
Սակայն, երբ առանց զտիչների հարցում եք անում հավաքածուի վերջնակետին, օրինակ՝ /jsonapi/node/article, պարզապես կստանաք բոլոր հոդվածները, որոնք կարող եք տեսնել։
Առանց զտիչների, հնարավոր չէ ստանալ միայն ձեր հոդվածները կամ միայն հոդվածներ լամաների մասին։
Այս ուղեցույցը ձեզ կսովորեցնի պրոֆեսիոնալ զտիչներ ստեղծել։
Արագ մեկնարկ
Ամենապարզ և ամենատարածված զտիչը բանալի-արժեք զտիչն է՝
?filter[field_name]=value&filter[field_other]=value
Սա համընկնում է բոլոր ռեսուրսների հետ, որտեղ "field_name"-ը հավասար է "value"-ին և "field_other"-ը հավասար է "value"-ին։
Մնացածի համար՝ շարունակեք կարդալ։
Ամփոփում
JSON:API մոդուլն ունի զտման ամենաառաջադեմ և բազմաֆունկցիոնալ հնարավորություններից մեկը։ Այս հզորությունը, սակայն, ունի որոշակի ուսուցման կոր։
Այս հոդվածի ավարտին կկարողանաք կատարել բարդ հարցումներ և լուծել խնդիրներ, օրինակ՝ «ինչպե՞ս ստանալ հեղինակի բոլոր հոդվածները լամաների կամ կենդանական աշխարհի ամենաարագ անդամի՝ ճայասարուկի մասին»։
Սկսելու ենք ամենահիմնականից։ Դրանից հետո կցույց տանք մի քանի հարմարեցումներ, որոնք կօգնեն արագ և հակիրճ գրել զտիչներ։ Վերջում կներկայացնենք զտիչների մի շարք իրական օրինակներ։
Եթե արդեն ծանոթ եք Drupal-ին, հավանաբար արդեն օգտագործել եք Views մոդուլը այս նպատակների համար։ Ի տարբերություն Drupal Core-ի REST մոդուլի, JSON:API-ն չի արտահանում Views-ի արդյունքները։ Հավաքածուները JSON:API-ի API-First այլընտրանքն են Views-ում արտահանվող «REST ցուցադրման» համար։
Զտիչների կառուցում
JSON:API-ի զտիչների հիմնական բաղադրիչներն են պայմանները և խմբերը։ Պայմանները հաստատում են ճշմարիտ կամ կեղծ լինելը, խմբերը թույլ են տալիս այդ հաստատումները համադրել տրամաբանական խմբերում՝ ստանալու ավելի մեծ պայմանների խումբ։ Այդ խմբերը կարող են ներդրված լինել՝ կազմելով ծառանման կառուցվածք՝
Սովորական ներկայացում՝
a( b() && c( d() || e() ) )
Ծառի ներկայացում՝
a
/ \
b & c
/ \
d | e
Երկու դեպքում էլ՝
«d» և «e»-ն «c»-ի անդամներ են (OR խումբ),
«b»-ն և «c»-ն «a»-ի անդամներ են (AND խումբ)։
Իսկ ի՞նչ կա պայմանների ներսում։
Դիտարկենք տրամաբանությունը։ Պայմանը ճշմարիտ կամ կեղծ է ռեսուրսի համար՝ ըստ ձեր հայտարարած հայտարարության, օրինակ՝ «արդյո՞ք էակը ստեղծել է կոնկրետ օգտատերը»։ Եթե պայմանը կեղծ է, այդ ռեսուրսը հավաքածուում չի լինի։
Պայմանը ունի երեք հիմնական մաս՝ ճանապարհ (path), օպերատոր և արժեք։
- «path»-ը ռեսուրսի դաշտի նույնականացուցիչն է
- «օպերատոր»-ը համեմատության եղանակն է
- «արժեք»-ը՝ համեմատվողը
Պարզեցված տեսքով՝
($field !== 'space')
Որտեղ՝
$fieldդաշտի անունն է՝ ըստ «path»-ի- օպերատորը՝
!== - արժեքը՝
'space'
JSON:API-ում սա պետք է գրվի URL հարցման պարամետրում։ Յուրաքանչյուր պայման ներկայացվում է key/value զույգերով։
Օգտատիրոջ անունով զտիչը կարող է լինել՝
?filter[a-label][condition][path]=field_first_name
&filter[a-label][condition][operator]=%3D <- կոդավորված "="
&filter[a-label][condition][value]=Janis
Նկատեք, որ առաջին փակագծերի մեջ դրել ենք պիտակ։ Կարող էր լինել նաև b-label կամ this_is_my_super_awesome_label, կամ նույնիսկ 666 🤘😅։ Յուրաքանչյուր պայման կամ խումբ պետք է ունենա նույնականացուցիչ։
Իսկ եթե շատ Janis-ներ կան համակարգում՞։
Ավելացնենք մեկ այլ զտիչ՝ որպեսզի ստանանք միայն այն Janis-ները, որոնց ազգանունը սկսվում է «J»-ով՝
?filter[first-name-filter][condition][path]=field_first_name
&filter[first-name-filter][condition][operator]=%3D <- կոդավորված "="
&filter[first-name-filter][condition][value]=Janis
&filter[last-name-filter][condition][path]=field_last_name
&filter[last-name-filter][condition][operator]=STARTS_WITH
&filter[last-name-filter][condition][value]=J
Հնարավոր է Janis-ի հոտը «Janii» է 🤔...
Կա շատ ավելին, քան միայն = և STARTS_WITH օպերատորները։ Ահա ամբողջական ցուցակը՝ վերցված JSON:API կոդային հիմքից՝
\Drupal\jsonapi\Query\EntityCondition::$allowedOperators = [
'=', '<>',
'>', '>=', '<', '<=',
'STARTS_WITH', 'CONTAINS', 'ENDS_WITH',
'IN', 'NOT IN',
'BETWEEN', 'NOT BETWEEN',
'IS NULL', 'IS NOT NULL',
];
Սիմվոլ օպերատորները պետք է url-կոդավորվեն։ Օգտագործեք PHP-ի urlencode() ֆունկցիան։
Պայմանների խմբեր
Հիմա գիտենք՝ ինչպես կառուցել պայմաններ, բայց դեռ չգիտենք՝ ինչպես կառուցել պայմանների խմբեր։ Ինչպե՞ս կառուցել վերևում տեսած ծառը։
Դրա համար պետք է «խումբ»։ Խումբը պայմանների հավաքածու է՝ միացված «կոնյունկցիայով»։ Բոլոր խմբերն ունեն կոնյունկցիա՝ AND կամ OR։
Հիմա մեր զտիչը չափազանց հստակ է։ Եկեք գտնենք բոլոր օգտատերերին, որոնց ազգանունը սկսվում է «J»-ով, և առաջին անունը կա՛մ «Janis»-ն է, կա՛մ «Joan»-ը։
Ավելացնենք խումբ՝
?filter[rock-group][group][conjunction]=OR
Այնուհետ՝ մեր զտիչները հանձնարականենք այդ խմբին՝
Ավելացնենք memberOf բանալի։ Յուրաքանչյուր պայման և խումբ կարող է ունենալ memberOf բանալի։
Հուշում՝ խմբերն էլ կարող են ունենալ memberOf, այսինքն՝ կարող ենք ունենալ խմբերի խմբեր 🤯։
Նշում՝ յուրաքանչյուր զտիչ, որը չունի memberOf, համարվում է «արմատ» խմբի մաս՝ AND կոնյունկցիայով։
Ամբողջությամբ՝
?filter[rock-group][group][conjunction]=OR
&filter[janis-filter][condition][path]=field_first_name
&filter[janis-filter][condition][operator]=%3D
&filter[janis-filter][condition][value]=Janis
&filter[janis-filter][condition][memberOf]=rock-group
&filter[joan-filter][condition][path]=field_first_name
&filter[joan-filter][condition][operator]=%3D
&filter[joan-filter][condition][value]=Joan
&filter[joan-filter][condition][memberOf]=rock-group
&filter[last-name-filter][condition][path]=field_last_name
&filter[last-name-filter][condition][operator]=STARTS_WITH
&filter[last-name-filter][condition][value]=J
Ծանոթ է թվում՞։
Դա էլ հենց վերևում տեսած ծառն էր՝
a a = root-and-group
/ \
/ \ b = last-name-filter
b c c = rock-group
/ \
/ \ d = janis-filter
d e e = joan-filter
Կարող եք խմբերը ներդնել այնքան խոր, որքան ցանկանաք։
Ճանապարհներ (paths)
Պայմաններն ունեն ևս մեկ հատկություն՝ «ճանապարհներ» (paths)։
Ճանապարհները թույլ են տալիս զտել՝ հիմնվելով կապի արժեքների վրա։
Մինչ այս պահը զտում էինք միայն field_first_name և field_last_name դաշտերով։
Ենթադրենք՝ ուզում ենք զտել օգտատիրոջ կարիերայի անվամբ, որտեղ կարիերան առանձին ռեսուրս է։ Կարող ենք ավելացնել զտիչ՝
?filter[career][condition][path]=field_career.name
&filter[career][condition][operator]=%3D
&filter[career][condition][value]=Rockstar
Ճանապարհները օգտագործում են «կետային նշանագրություն»՝ կապերը անցնելու համար։
Եթե ռեսուրսն ունի կապ, կարող եք այդ կապի դաշտի անունը և կապի դաշտի անունը միացնել . (կետով)՝ զտման համար։
Կարող եք նույնիսկ զտել կապի կապերով (և այլն)՝ ավելացնելով ևս դաշտի անուններ և կետեր։
Հուշում՝ կարող եք զտել կոնկրետ ինդեքսով՝ ճանապարհում նշելով ոչ բացասական ամբողջ թիվ։ Այսպիսով՝ some_relationship.1.some_attribute ճանապարհը կզտի միայն երկրորդ կապված ռեսուրսով։
Հուշում՝ կարող եք զտել դաշտի ենթամասնաշերտերով։ Օրինակ՝ field_phone.country_code կաշխատի, նույնիսկ եթե field_phone կապ չէ։
Հուշում՝ Կոնֆիգուրացիոն հատկություններով զտելիս կարող եք օգտագործել աստղանիշ (*)՝ ճանապարհի ցանկացած մասի փոխարեն։ Օրինակ՝ /jsonapi/field_config/field_config?filter[dependencies.config.*]=comment.type.comment կգտնի բոլոր field config-ները, որոնց ["attributes"]["dependencies"]["config"] (զանգված) պարունակում է "comment.type.comment"։
Հարմարեցումներ (Shortcuts)
Սա շատ երկար է։ Շատ դեպքերում պետք չեն այսքան բարդ զտիչներ, ու JSON:API-ն առաջարկում է մի քանի հարմարեցում արագ գրելու համար։
Երբ օպերատորը = է, կարող եք այն բաց թողնել։ Այսպիսով՝
?filter[a-label][condition][path]=field_first_name
&filter[a-label][condition][operator]=%3D <- կոդավորված "="
&filter[a-label][condition][value]=Janis
դառնում է
?filter[janis-filter][condition][path]=field_first_name
&filter[janis-filter][condition][value]=Janis
Բացի այդ, հազվադեպ եք պետք նույն դաշտով զտել երկու անգամ։ Այսպիսով՝ եթե օպերատորը = է և կրկնվող զտում պետք չէ, կարող եք օգտագործել դաշտի անունը որպես նույնականացուցիչ։ Այսպես՝
?filter[janis-filter][condition][path]=field_first_name
&filter[janis-filter][condition][value]=Janis
դառնում է
?filter[field_first_name][value]=Janis
Այդ ավելորդ value-ը էլ կարելի է կրճատել՝ ամենապարզ համեմատությունը գրելով այսպես՝
?filter[field_first_name]=Janis
Զտիչներ և հասանելիության վերահսկում
Նախ՝ զգուշացում․ մի շփոթեք զտիչները հասանելիության վերահսկման հետ։ Եթե զտիչ եք գրել ինչ-որ բանից ազատվելու համար, դա չի նշանակում, որ տվյալը անհասանելի է։ Մուտքի ստուգումներն անեք սերվերի վրա։
Այժմ՝ զտիչները օգտագործելու մասին՝ հասանելիության վերահսկումը լրացնելու համար։ Արտադրողականության համար պետք է զտել այն, ինչ օգտվողները չպետք է տեսնեն։ JSON:API-ի խնդրագումարներում ամենահաճախ հանդիպող հարցը կարելի է լուծել այս պարզ հնարքով։
Եթե գիտեք, որ օգտվողները չեն տեսնի չհրապարակված բովանդակություն, ավելացրեք այս զտիչը՝
?filter[status][value]=1
Այսպես նվազեցնում եք ավելորդ հարցումները, քանի որ JSON:API-ն չի վերադարձնում տվյալներ այն ռեսուրսների համար, որոնց օգտվողը մուտք չունի։ Կարող եք տեսնել, թե որ ռեսուրսներն են ազդել՝ ուսումնասիրելով JSON:API փաստաթղթի meta.errors բաժինը։
Այսպիսով, ձեզնից կախված ամեն ինչ արեք, որ նախապես զտեք անհասանելի ռեսուրսները։
Զտիչների օրինակներ
1. Ստանալ միայն հրապարակված node-երը
Շատ տարածված դեպք է՝ բեռնել միայն հրապարակված node-երը։ Սա շատ հեշտ է ավելացնել։
ԿԱՐՏ
filter[status][value]=1
ՍՏԱՆԴԱՐՏ
filter[status-filter][condition][path]=status
filter[status-filter][condition][value]=1
2. Ստանալ node-եր ըստ էակի հղման արժեքի
Հաճախորդի պարունակությունը էակի հղման արժեքով զտելու տարածված տարբերակ։
ԿԱՐՏ
filter[uid.id][value]=BB09E2CD-9487-44BC-B219-3DC03D6820CD
ՍՏԱՆԴԱՐՏ
filter[author-filter][condition][path]=uid.id
filter[author-filter][condition][value]=BB09E2CD-9487-44BC