SPFx un Copilot: pieci aģentu integrācijas scenāriji

Ievads

SPFx un Copilot kļūst aktuāli brīdī, kad ar standarta SharePoint komponentēm vairs nepietiek, lai lietotājam dotu kontekstuālu atbildi, darbību ieteikumu vai kontrolētu piekļuvi uzņēmuma datiem. M365 izstrādātājiem jautājums nav tikai par to, vai Copilot spēj sarunāties ar lietotāju, bet gan par to, kur šī saruna dzīvo, kā tā pieslēdzas SharePoint saturam, un kurā brīdī SPFx slānis nodod datus aģentam vai saņem atpakaļ strukturētu rezultātu. Tieši te parādās praktiskā vērtība: SPFx kļūst par drošu lietotāja virsmas un biznesa konteksta punktu, bet Copilot vai aģents — par spriešanas un darbību koordinācijas slāni.

Raksta plāns balstās uz pieciem integrācijas scenārijiem: no SharePoint lapas konteksta nodošanas līdz aģenta aktivizētām darbībām sarakstos, dokumentu bibliotēkās un pielāgotās komandās. Katrs scenārijs ir noformēts tā, lai izstrādātājs saprot konkrēto arhitektūras soli, nepieciešamo Microsoft 365 objektu un robežu, ko nedrīkst pārkāpt ar pārlieku brīvu datu pieeju. Plāns arī atbild uz biežajiem PAA jautājumiem par drošību, autentifikāciju, datu izmantošanu un to, vai SPFx šādā arhitektūrā kalpo kā lietotāja saskarne, integrācijas adapteris vai abi vienlaikus.

Kāpēc SPFx kļūst par Copilot aģenta ieejas punktu SharePoint vidē

Problēma SharePoint vidē sākas brīdī, kad lietotājs atver lapu, bet aģentam nav skaidra punkta, no kura nolasīt lapas kontekstu, lietotāja darbību vai konkrētā risinājuma domēnu. Standarta web parts rāda saturu, bet tie nepasaka, kurš saraksts ir autoritatīvs, kura bibliotēka satur darba failus un kādā secībā lietotājam jāsaņem nākamā darbība. Tieši te SPFx kļūst par ieejas punktu: web part, Application Customizer vai Command Set iestiprina aģenta saskarni tajā pašā SharePoint vietā, kur jau dzīvo dati un piekļuve. Microsoft Copilot APIs Explorer paraugs Microsoft sample solution gallery demonstrē SPFx React web part pieeju Copilot API izsaukumiem, un tas precīzi rāda mehānismu, kur UI un aģenta darbība atrodas vienā lapas kontekstā.

Cēlonis ir vienkāršs: Copilot bez lokālā SharePoint enkura redz tikai vispārīgu dialogu, bet ne lapas biznesa nozīmi. Ja SPFx komponents nolasa lapas URL, listes ID, bibliotēkas izvēlēto vienumu vai lietotāja atlasīto rindu, aģents saņem precīzu ievades signālu, nevis miglainu pieprasījumu. Praktiskā konfigurācija sākas ar risinājuma modeli: izveido SPFx projektu, pievieno web part vai Command Set, un priekšpusē nodod identifikatorus uz aģenta slāni. Pēc tam validē, ka komponents strādā tikai konkrētajā site vai konkrētajā saturā, nevis vispārīgi visā tenant vidē.

• Atver SharePoint page un ievieto SPFx web part tajā zonā, kur lietotājs jau pieņem lēmumu.
• Izmanto page context, lai nolasītu site, list vai library identifikatorus.
• Nodod šos datus aģenta izsaukumam kā skaidru darba kontekstu.
• Pārbaudi, vai aģents reaģē citādi dažādās lapās, nevis atkārto vienu un to pašu atbildi.

Rezultāts praksē ir tāds, ka aģents vairs nerīkojas akli. Tas atbild ar konkrēto sarakstu, konkrēto dokumentu kopu vai konkrēto lapu, kur lietotājs atrodas, un šī saite starp SharePoint interfeisu un Copilot loģiku kļūst pārbaudāma. Kad šis pamats ir izveidots, nākamais solis ir precīzi definēt, kā no lapas, bibliotēkas un saraksta tiek nodots konteksts, lai aģents nesajauktu vienu datu avotu ar citu.

SPFx un Copilot konteksta nodošana no lapas, bibliotēkas un saraksta

Tipiskākā kļūda praksē ir censties aģentam iedot tikai vispārīgu vietnes adresi un cerēt, ka tas pats sapratīs, no kura saraksta vai bibliotēkas jāņem dati. Tas nestrādā konsekventi, jo SharePoint lapā bieži vien vienlaikus atrodas vairākas informācijas vienības: dokuments, saistīts saraksts, uzdevumu skats un darbību panelis. Ja SPFx komponents nenorāda, vai avots ir page context, selected list item vai document library folder, Copilot sāk interpretēt nepareizo objektu. Microsoft dokumentācija Copilot APIs Explorer paraugā parāda, ka web part tiek veidots React risinājumā un tieši no SPFx slāņa tiek organizēta API datu plūsma, kas nozīmē: konteksts jāizveido pirms aģenta pieprasījuma, nevis pēc tam.

Šī kļūda rodas tāpēc, ka izstrādātājs sajauc vizuālo komponenti ar datu līgumu. Lietotājs redz vienu kartīti vai vienu rīkjoslu, bet aģentam vajadzīgs precīzs objekta tips: lapas metadata, bibliotēkas vienuma ID, saraksta kolonnas vai atlasītā faila ceļš. Pareizā konfigurācija sākas ar to, ka SPFx komponentam ir skaidrs avots katram scenārijam:

1. Page līmenī nolasi site, page un authoring context, ja aģents sniedz palīdzību pašai lapai.
2. Library līmenī nodod selected file, folder vai view metadata, ja aģents strādā ar dokumentu kopu.
3. List līmenī nodod selected item ID, kolonnas un lietotāja izvēlēto darbību, ja aģents atbalsta procesu izpildi.
4. SPFx pusē nošķir display state no agent payload, lai lietotāja interfeiss nesajauktos ar datu parametriem.

Ja šo neizlabo, sekas ir prognozējamas: aģents atsaucas uz nepareizu dokumentu, atgriež atbildi no cita saraksta vai piedāvā darbību, kas neatbilst lietotāja pašreizējam skatam. Praksē tas bojā uzticību daudz ātrāk nekā tehniska kļūda, jo lietotājs redz, ka atbilde nav sasaistīta ar ekrānā redzamo saturu. Tāpēc SPFx un Copilot integrācijā konteksts nav papildfunkcija, bet pamata līgums starp UI un aģentu. Kad šis līgums ir skaidrs, nākamais jautājums ir darbības: ko aģents drīkst nolasīt un ko tas drīkst atjaunināt SharePoint datos.

Aģenta aktivizētas darbības, kas lasa un atjaunina SharePoint datus

SPFx un Copilot integrācijā jānošķir divas pieejas: aģents, kas tikai lasa datus un sagatavo ieteikumu, un aģents, kas pēc lietotāja apstiprinājuma veic izmaiņas SharePoint saturā. Pirmā pieeja der situācijās, kur nepieciešams ātrs konteksts, piemēram, dokumenta kopsavilkums, statusa noteikšana vai nākamās darbības izklāsts. Otrā pieeja der tikai tad, ja darbībai ir skaidrs biznesa noteikums, piemēram, atjaunināt saraksta kolonnas, pārvietot dokumentu uz citu mapes struktūru vai pievienot metadatu tagu. Microsoft sample solution gallery par Copilot APIs Explorer uzsver integrāciju ar React SPFx web part, kas ir labs signāls tieši šai arhitektūrai: vispirms tiek savākts konteksts, pēc tam tiek izsaukta konkrēta darbība.

Salīdzinājums praksē izskatās šādi. Lasīšanas scenārijā SPFx komponents apstrādā lietotāja izvēlēto saraksta rindu vai dokumentu, nosūta to aģentam un saņem strukturētu atbildi. Tas samazina risku, jo SharePoint dati netiek pārrakstīti. Atjaunināšanas scenārijā aģents darbojas kā palīgs, nevis autonoms izpildītājs: lietotājs apstiprina darbību, un tikai tad SPFx slānis nosūta write operāciju uz SharePoint REST vai citu izvēlēto Microsoft 365 mehānismu. Šeit kritiska ir transakcijas robeža: vienā solī nedrīkst sajaukt lēmumu, validāciju un izmaiņu izpildi, jo tad kļūst grūti saprast, kas tieši tika nolasīts un kas tika uzrakstīts.

• Ja uzdevums ir kopsavilkums, prioritātes vai ieteikums, paliec pie read-only pieejas.
• Ja vajadzīgs datu labojums, pievieno lietotāja apstiprinājumu pirms write darbības.
• Ja risinājums skar statusa kolonnas, validē kolonnas tipu un atļautās vērtības pirms nosūtīšanas.
• Ja tiek apstrādāti dokumenti, skaidri norādi, vai aģents strādā ar failu saturu, metadata vai mapes ceļu.

Ieteikums ir vienkāršs: lasīšanai izmanto aģenta ieteikumu slāni, rakstīšanai pievieno apstiprinājuma slieksni un audita pēdu. Tas saglabā kontroli pār SharePoint datiem un ļauj SPFx interfeisā precīzi parādīt, kas tiks mainīts pirms izpildes. Kad darbības ir nodalītas, jānoslēdz vēl svarīgāks slānis — drošība, identitāte un datu minimizācija, lai aģents redz tikai tik daudz, cik nepieciešams konkrētajai lomai.

Drošības robežas: piekļuve, lietotāja identitāte un datu minimizācija

Drošības problēma SPFx un Copilot scenārijos parādās tad, kad aģents saņem vairāk datu nekā nepieciešams vai izmanto nepareizu identitātes kontekstu. SharePoint vidē tas nozīmē, ka lietotājs ar ierobežotu piekļuvi nedrīkst redzēt saturu, ko viņa tiesības neaizsedz, un SPFx komponents nedrīkst pārsūtīt aģentam pilnu saraksta vienumu, ja darbībai pietiek ar ID un dažām kolonnām. Microsoft dokumentācija par SPFx risinājumu paraugu Copilot APIs Explorer parāda ieviešanu React web part formā, un tas ir labs atgādinājums: drošības slānis dzīvo gan komponenta kodā, gan SharePoint permission modelī.

Praktiskais ceļš sākas ar tiesību pārbaudi. Atver SharePoint site, pēc tam pārej uz Document Library → Settings → Library settings vai List → Settings → List settings, un pārskati, kādas kolonnas un vienumu tiesības faktiski ir pieejamas konkrētajam risinājumam. Ja SPFx komponents lasa datus, atlasī tikai to lauku kopu, kas nepieciešama aģenta uzdevumam. Ja komponents izmanto Custom Action vai Command Set, piesaisti darbību konkrētam skata vai vienuma kontekstam, nevis visam kataloga saturam. Lietotāja identitāte jānodod tādā pašā autentifikācijas plūsmā, kādu pieprasa uzņēmuma Microsoft 365 drošības politika, un pieprasījums jāizpilda tikai ar lietotāja deleģētajām tiesībām, nevis ar vispārēju servisa skatu.

1. Pārbaudi, kurš SharePoint objekts ir sākumpunkts: page, list item vai library file.
2. Samazini nododamo payload līdz identifikatoram, statusam un nepieciešamajām kolonnām.
3. Nodrošini, ka aģents saņem tikai lietotāja sesijas kontekstu, nevis plašu datu kopu.
4. Testē ar lietotāju, kam ir zemākas tiesības, lai redzētu, ka tiek rādīts tikai atļautais saturs.

Biežākā kļūme pirmajā solī ir nepareizs avots, otrajā solī — pārlieku plašs payload, trešajā solī — identitātes sajaukšana starp lietotāju un servisu, bet ceturtajā solī — testēšana tikai ar administratora kontu. Ja šo disciplīnu ievēro, SPFx kļūst par drošu robežu starp SharePoint datiem un Copilot darbību: lietotājs saņem precīzu atbildi, bet sistēma neatklāj vairāk, nekā vajadzīgs. Tieši tāpēc nākamajā sadaļā šo modeļu pārbaudām pret praktiskajiem integrācijas scenārijiem kopējā arhitektūrā.

Scenārijs: dokumentu kopsavilkums ar SPFx paneļa un Copilot dialoga sasaiti

Dokumentu kopsavilkuma scenārijā SPFx un Copilot strādā kopā tad, kad SharePoint lapā blakus dokumentam ir redzams īss konteksts, bet pilnais skaidrojums tiek nodots aģenta dialogam. Jēga nav “uztaisīt čatu pie faila”, bet noformēt skaidru ieejas punktu: lietotājs izlasa dokumenta virsrakstu, redz metadatus, atver SPFx paneli un ar vienu darbību nodod aģentam konkrēto dokumentu, tā versiju vai saistīto bibliotēku. Tas novērš situāciju, kur Copilot saņem tikai vispārīgu vietnes adresi un sāk atbildēt bez sašaurināta konteksta.

Praksē šis darbojas labi dokumentu bibliotēkā, kur ir daudz līdzīgu failu. SPFx panelis uz lapas izlasa dokumenta ID, nosaukumu, statusu un autoru no konteksta, pēc tam izsauc aģenta dialogu ar precīzu norādi, uz kuru vienumu jābalstās. Ja dokumentam ir versiju kontrole, panelis rāda pēdējo aktīvo versiju un ļauj nodot tieši to, nevis nejaušu faila kopiju. Microsoft sample solution gallery SPFx Copilot APIs Explorer demonstrē tieši šādu pieeju — SPFx tīmekļa daļa darbojas kā konteksta savācējs, bet Copilot puse kā sarunā balstīts izskaidrotājs un darbības slānis.

Avots: Microsoft Adoption sample solution gallery, “PnP SP Dev SPFx Web Parts React Copilot APIs Explorer”.

Ko ar to iesākt SharePoint vidē: vispirms Document Library → Settings → Versioning settings ieslēdz versiju kontroli, lai aģents var atsaukties uz stabilu dokumenta stāvokli. Tālāk SPFx panelī definē skaidru darbību: Open in Copilot, Summarize selected document vai Explain changes since last version. Pēc tam Web part vai Application Customizer saista izvēlēto failu ar dialogu, nevis ar vispārēju vietni. Ja datu avots ir saraksts ar dokumentiem, panelī ieliec filtru pēc dokumenta tipa, statusa un pēdējās izmaiņas autora, lai Copilot saņem tieši to objektu, kas lietotājam ir priekšā.

Rezultāts praksē ir skaidrāka atbilde bez manuālas dokumentu meklēšanas, jo lietotājs sāk sarunu no konkrēta SharePoint objekta, nevis no abstrakta jautājuma. Tas samazina interpretācijas kļūdas un ļauj aģentam balstīties uz vienu failu vai vienu versiju, nevis uz visu bibliotēku uzreiz. Nākamais loģiskais solis ir skatīt, kā šādu kontekstu lieto tad, kad nav dokumenta, bet ir jāšķiro ieraksti pēc biznesa noteikumiem.

Scenārijs: saraksta ierakstu triāža un biznesa noteikumu pārbaude

Praksē šis scenārijs sākas ar vienkāršu situāciju: SharePoint sarakstā ienāk vairāki pieteikumi, bet katrs ir jānovērtē pēc atšķirīgiem biznesa noteikumiem. Vienam jāskatās prioritāte, citam termiņš, trešajam atbildīgā persona. SPFx un Copilot šeit strādā kā triāžas pāris: SPFx komponents nolasa ierakstu un ielādē noteikumus, bet Copilot izskaidro, kāpēc ieraksts jāmarķē kā steidzams, jāatgriež labojumiem vai jānosūta apstiprināšanai. Lielākā kļūda ir cerēt, ka aģents pats nolasīs lietišķo loģiku no saraksta kolonnu nosaukumiem.

Kas tika mainīts tehniski: SPFx komandpaneļī vai panelī tiek pievienots skats uz izvēlēto saraksta vienumu, biznesa noteikumu kopums un komanda, kas palaidīs analīzi. SharePoint sarakstā vispirms sakārto kolonnas, lai tajās būtu skaidri atšķirami lauki: statuss, datums, atbildīgais, kategorija, ietekme. Tad SPFx tīmekļa daļa nolasa ne tikai redzamos laukus, bet arī paslēpto tehnisko identifikatoru, lai Copilot analizē vienu konkrētu ierakstu. Ja noteikumi ir stingri, tie jādefinē ārpus vizuālā teksta, piemēram, konfigurācijas objektā vai JSON struktūrā, ko panelis nodod aģentam kā vienotu ievades bloku.

Tipiska īstenošanas secība:

1. Atver SharePoint list un pārskati kolonnu nosaukumus, lai tie atbilst biznesa terminoloģijai.
2. SPFx komandpaneļī pievieno darbību Check rules vai Triaging assistant.
3. No saraksta vienuma nolasī tikai nepieciešamos laukus: statusu, termiņu, kategoriju, atbildīgo, prioritāti.
4. Nodod aģentam noteikumu kopu un vienuma ID, nevis visu sarakstu.
5. Rādījuma tekstā parādi, kurš noteikums nostrādāja un kāpēc ieraksts saņēma konkrēto statusu.

Microsoft sample solution gallery SPFx Copilot APIs Explorer šeit ir noderīgs kā modelis, jo tas parāda, kā SPFx komponents piesaista Copilot noteiktam objektam un kontrolē dialogā nododamo kontekstu.

Avots: Microsoft Adoption sample solution gallery, “PnP SP Dev SPFx Web Parts React Copilot APIs Explorer”.

Rezultāts praktiskajā darbā ir konsekventa triāža: vienumi nonāk pareizajā atbildes plūsmā, un lietotājam nav jāmin, kurš lauks nozīmē “steidzams” vai “jāizskata šodien”. Biznesa noteikumu pārbaude kļūst caurspīdīga arī auditam, jo SPFx panelis rāda, kādi lauki tika izmantoti un kādu lēmumu aģents balstīja. No šejienes ir viegli pāriet uz nākamo scenāriju, kur svarīgākais nav triāža, bet zināšanu bāzes navigācija.

Scenārijs: zināšanu bāzes navigācija ar SharePoint saturu un aģentu atbildēm

Problēma zināšanu bāzes scenārijā parādās tad, kad darbinieks atver SharePoint vietni, redz daudz lapu, bibliotēku un saistīto failu, bet nezina, kurā vietā ir īstā atbilde. Šī nav tikai meklēšanas problēma. Tā ir navigācijas problēma: cilvēks saprot biznesa jautājumu, bet SharePoint saturs ir sadalīts vairākās vietnēs, sadaļās un dokumentu krātuvēs. SPFx un Copilot šeit risina atšķirīgas daļas — SPFx parāda struktūru un izvēlēto kontekstu, bet aģents atbild ar saturu, kas balstīts konkrētajā vietnē vai bibliotēkā.

Cēlonis parasti ir nesakārtots satura modelis. Ja lapas, dokumenti un saraksti izmanto atšķirīgus nosaukumus vienam un tam pašam procesam, Copilot saņem pārāk plašu ieejas punktu. Risinājums sākas ar navigācijas slāni: SPFx web part vai panelis attēlo tēmu karti, saistītās lapas un “biežāk uzdotos jautājumus” no SharePoint satura. Lietotājs izvēlas konkrētu jomu, piemēram, iekšējo iepirkumu, personāla procesu vai projektu uzsākšanu, un tikai tad aģents sāk meklēt atbildi šajā sadaļā. Šī pieeja darbojas labāk nekā universāls čats, jo aģents saņem jau sašaurinātu saturu.

Risinājuma soļi Microsoft 365 vidē:

• SharePoint vietnē saskaņo lapu nosaukumus, sadaļu virsrakstus un dokumentu bibliotēku nosaukumus ar vienu procesu karti.
• SPFx tīmekļa daļā izveido navigācijas paneli ar skaidriem tēmu punktiem un saistītajiem dokumentiem.
• Pievieno darbību Ask Copilot about this topic, kas nodod aģentam atlasīto tēmu, lapas ID un saistītos dokumentus.
• Ja saturs atrodas dokumentu bibliotēkā, izmanto metadatus, lai aģents nesaņemtu tikai failu sarakstu, bet arī tēmas nosaukumu un statusu.
• Testē ar jautājumu, kuram jāatrod atbilde vienā precīzā procesu grupā, nevis visā vietnē.

Microsoft dokumentācijas sample solution gallery par SPFx Copilot APIs Explorer rāda, kā konteksts tiek piesaistīts tieši noteiktam SharePoint objektam un kā dialoga atbilde kļūst saistīta ar šo objektu, nevis ar nejaušu saturu plašākā vietnē.

Avots: Microsoft Adoption sample solution gallery, “PnP SP Dev SPFx Web Parts React Copilot APIs Explorer”.

Ja konfigurācija ir pareiza, pārbaude ir vienkārša: lietotājs izvēlas tēmu, Copilot atbild tikai no šīs tēmas satura, un SPFx panelis parāda avota lapu vai dokumentu saites. Ja atbilde sāk klīst starp citām vietnēm, tas nozīmē, ka konteksts ir pārāk plašs vai metadati nav pietiekami skaidri. Tālāk loģiski ir skatīt, kā šo pašu principu izmantot komandu paneļos un Copilot plūsmās, kur svarīgas ir darbības, nevis tikai atbildes.

Scenārijs: pielāgoti komandu paneļi un SPFx darbības Copilot plūsmās

Tipiska kļūda praksē ir salikt SPFx pogas vai komandu paneļus tikai vizuālam ērtumam, bet nepadarīt tos par daļu no Copilot plūsmas. Tad lietotājs redz modernu paneli ar darbībām, taču katra poga dzīvo atsevišķi no aģenta dialoga, un rezultāts ir divi paralēli ceļi: viens SharePoint lietotājam, otrs Copilot sarunai. SPFx un Copilot šādā gadījumā nesatiekas darbības līmenī. Poga “Approve”, “Escalate” vai “Create follow-up” joprojām ir tikai UI elements, nevis komanda, ko aģents saprot un prot izmantot savā plūsmā.

Šī kļūda rodas tad, kad izstrādātājs vispirms uzbūvē interfeisu un tikai pēc tam mēģina pieslēgt AI slāni. Pareizā pieeja ir pretēja: vispirms definē komandu semantiku, pēc tam izveido SPFx UI kā šo komandu ievades vietu. Komandu paneļī katrai darbībai piešķir skaidru nosaukumu, atļautos laukus un izpildes mērķi. Copilot pusē darbībai jāsaņem strukturēts konteksts, piemēram, vienuma ID, lietotāja loma, pašreizējais statuss un darbības mērķis. Ja paneļa poga tikai atver ārēju lapu vai nosūta nesaskaņotu tekstu, plūsma sabrūk, jo aģents nesaprot, ko tieši darīt ar SharePoint objektu.

Pareizā konfigurācija:

1. SPFx komandpaneļī katrai darbībai definē vienu konkrētu biznesa komandu, nevis vispārīgu “apstrādāt”.
2. SharePoint vienuma datiem pievieno minimālo kontekstu, kas vajadzīgs darbības izpildei: ID, tipu, statusu un atbildīgo.
3. Aģenta plūsmā nodalī lasīšanu no izpildes, lai Copilot vispirms sagatavo secinājumu un pēc tam izsauc darbību.
4. Ja darbība maina datus, rādi apstiprinājuma soli pirms izpildes un piesaisti to lietotāja identitātei.
5. SPFx panelī uzturi vienotu atgriezenisko saiti: kas tika pieņemts, kas noraidīts, kas nosūtīts tālāk.

Microsoft sample solution gallery SPFx Copilot APIs Explorer šo modeli atbalsta ar skaidru konteksta nodošanas principu un parāda, kā UI darbība kļūst par strukturētu ievadi aģenta pusē.

Avots: Microsoft Adoption sample solution gallery, “PnP SP Dev SPFx Web Parts React Copilot APIs Explorer”.

Ja šo neizlabo, sekas ir paredzamas: lietotājs redz daudz pogu, bet aģenta atbildes paliek vispārīgas, jo Copilot nesaņem vienu skaidru komandu un vienu datu kopu. Pareizi sakārtots komandu panelis maina to, ka SharePoint kļūst par darbību vadītu vidi, nevis tikai atskaites lapu. No šī punkta ir dabiski pāriet uz kopsavilkumu par to, kā šie četri scenāriji veido vienu integrācijas modeli visā SharePoint vidē.

Avoti

Kā KSJ var palīdzēt