Maj je stigao, a Microsoft 365 E7 i Agent 365 su sada životna činjenica. Naš prvi pogled na API-je agenta 365 na grafikonu smo prošli mjesec, a “GA” donosi neke dobre vijesti i neke loše vijesti. Dobra vijest je da sada imamo pristup metodama PATCH i POST, koje nam omogućavaju da izvodimo operacije kao što je blokiranje ili dodjeljivanje određenog agenta. Loša vijest je da nam je potrebna licenca Agenta 365 za korištenje bilo koje krajnje tačke, uključujući GET/LIST metode. Nijedna od krajnjih tačaka API-ja trenutno ne podržava dozvole aplikacije, što je korak unazad u odnosu na prije mjesec dana.
Nedostatak podrške za dozvole aplikacija znači da je automatizacija izazovna, iako još uvijek možemo istražiti neke osnovne paketne operacije putem dozvola za delegiranje. Više volim Graph SDK za PowerShell za takve scenarije, iako to ne čini veliku razliku u ovom slučaju jer nijedno od dostupnih izdanja još uvijek ne nudi cmdletove za te nove krajnje tačke. Stoga se oslanjamo na Invoke-MgGraphRequest umjesto toga cmdlet, za bilo koji od primjera koje pokrivamo u nastavku.
Omogućite ili onemogućite agente masovno
S obzirom na mnoge neizvjesnosti oko integracije AI/agenta u Microsoft 365 svojstvo organizacije, razumno je očekivati da će neki korisnici potpuno blokirati (neke) agente. Srećom, ovo se sada može lako uraditi u velikom broju putem blok metode. U primjeru ispod, koristimo ga da blokiramo sve agente koji nisu Microsoft (tj. agente koje su izdali dobavljači treće strane).
Za početak nam je, naravno, potreban pristupni token sa dovoljnim dozvolama, tj CopilotPackages.ReadWrite.All. Uloga administratora također mora biti dodijeljena korisniku na kojeg ste prijavljeni, na primjer Admin AI jedan. U našem scenariju koristimo SDK-ove Connect-MgGraph cmdlet za rukovanje zahtjevima za dozvolu:
Connect-MgGraph -Scopes CopilotPackages.ReadWrite.All
Tada možemo dohvatiti listu svih agenata (“kopilot paketi”):
$packages = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages?`$filter=supportedHosts/any(x:x eq 'Copilot')" -OutputType PSObject
Postoji nekoliko načina na koje možemo filtrirati: na koje se možemo osloniti Izdavač polje, ili još bolje, filtriranje prema tipu svojstva ia prva stranica vrijednost. Čini se da nijedno svojstvo nije podržano za filtriranje na strani servera, tako da moramo raditi stvari na glup način:
#Filter third-party agents $3p = $packages.value | ? $_.Type -eq "thirdParty"
Kada dobijemo listu, možemo koristiti metodu blokiranja za svakog agenta/paketa:
#Block all third-party packages
foreach ($package in ($3p | ? !$_.isBlocked))
Write-Verbose "Blocking package: $($package.Id) ($($package.DisplayName))"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/block" -Verbose:$false
Da poništite radnju i deblokirate sve agente trećih strana, možemo koristiti sljedeće:
#Unblock all third-party packages
foreach ($package in ($3p | ? $_.isBlocked))
Write-Verbose "Unblocking package: $($package.Id) ($($package.DisplayName))"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/unblock" -Verbose:$false
Grupno dodjeljivanje/raspoređivanje agenata
Drugi scenario koji želimo da pokrijemo je proces masovnog dodeljivanja (činjenja dostupnim) ili postavljanja (instaliranja) agenata grupi korisnika. Da bismo to postigli, prvo nam je potreban skup korisnika i skup agenata s kojima ćemo raditi u skladu s tim. Za korisnike možemo iskoristiti prednosti robusnih mogućnosti filtriranja na strani servera, koje bi trebale pokriti većinu osnovnih scenarija. Na primjer, uzmite skup (omogućenih) korisnika unutar odjeljenja:
$users = Get-MgUser -All -Filter "accountEnabled eq true and userType eq 'Member' and department eq 'sales'" -Property Id,DisplayName | select Id,DisplayName
Trebat će nam samo korisnik Iddakle displayName Svojstvo iznad je isključivo opciono i korisno samo ako želite da pregledate listu pre izvršavanja koda. Naravno, po potrebi možete prilagoditi filter i skup svojstava, na primjer da navedete samo korisnike s dodijeljenom licencom Agent 365.
Kada se skup korisnika dobije, moramo pripremiti JSON formatiran sadržaj predstavljen objektom packageAccessEntity. Kao što je objašnjeno u našem prethodnom članku, četiri svojstva kontrolišu pristup agentu. Kontrolira da li je agent dostupan availableTo i dozvoljenim korisnicima Grupe svojstva, doc distributedTo i nabavite UsersIGroup kontrolišu raspoređivanje agenata. Na primjer, sljedeći kod će pripremiti teret za scenarij implementacije agenta za skup korisnika koji smo definirali gore:
#Set the allowedUsersAndGroups property accordingly
$hash = @
deployedTo = "acquiredForSome"
acquireUsersAndGroups = @(
foreach ($user in $users)
@
resourceType = "user"
resourceId = $user.Id
)
Osim toga, trebat će nam i set agenata za dodjelu/razmještanje. Kao što je već spomenuto, opcije filtriranja su malo ograničene, pa koristite filtere na strani klijenta za najbolje rezultate (ili definirajte listu ručno). Kao i gore, samo nam je potrebno Id agenta, ali se mogu pojaviti dodatne informacije koje će vam pomoći da omogućite/onemogućite agente po potrebi. Na primjer, evo kako objaviti sve agente od strane određenog dobavljača treće strane:
$packages1 = $packages.value | ? $_.Publisher -eq "Atlassian.com"
Osim toga, spremni smo masovno implementirati skup agenata na našu korisničku listu. Za ovu operaciju se koristi metoda PATCH, sa jednim zahtjevom po agentu. Kako svakog agenta implementiramo na isti skup korisnika, možemo ponovo koristiti korisni teret za svako izvršenje:
foreach ($package in $packages1) ConvertTo-Json) -Verbose:$false
Čini se da trenutno postoje problemi s replikacijom s Graph API-jem kada su u pitanju četiri svojstva koja koristimo za kontrolu dodjele/pokretanja agenata. Iako bi gore navedeni zahtjevi trebali rezultirati a 204 Nema sadržaja odgovora, u narednim GET pozivima se ne primjećuju promjene u vrijednostima navedenih svojstava. Nasuprot tome, korisničko sučelje Agenta 365 unutar M365 centra za administraciju savršeno odražava promjene:
Kao napomena, pored navedenog 403 Zabranjeno greška zbog nedostatka SKU agenta 365 (“Korisnik mora imati Agent 365 licencu za korištenje Agent 365 Graph API-ja”), možete naići na a 405 Metoda nije dozvoljena greška u scenarijima u kojima je potrebna saglasnost. na primjer:
"error":
"code": "UnknownError",
"message": "\"StatusCode\":405,\"Message\":\"Admin consent has not been granted for AAD application bdc49611-ba72-43b9-a868-652243121c10. The following permissions are missing: email, offline_access, openid, profile\"",
"innerError":
"date": "2026-05-08T09:23:43",
"request-id": "8e23a844-11f2-4742-a1ad-c41d59d3cfaf",
"client-request-id": "6f7e3445-e1b8-f2a6-95f7-8287c87ea871"
API-ji agenta 365 trenutno ne nude nikakav način da se ovo zaobiđe, tako da biste trebali koristiti standard Oauth2PermissionGrant metode (pogledajte na primjer ovaj članak) ili UI umjesto toga. S jedne strane, ovo predstavlja izazov za automatizirane scenarije, ali s druge strane, to je zgodna prepreka koja može dovesti do potrebe za dodatnim odobrenjima i time spriječiti nenamjernu zloupotrebu funkcionalnosti.
Gornji primjer se lako može generalizirati na druge scenarije. Da bi skup agenata bio dostupan za korištenje, umjesto da ih direktno instalirate, ažurirajte korisni teret na:
$hash = @
availableTo = "allowedForSome"
allowedUsersAndGroups = @(
foreach ($user in $users)
@
resourceType = "user"
resourceId = $user.Id
)
Neki drugi primjeri su sažeti u nastavku:
- Da bi agent bio dostupan svim korisnicima, ažurirajte vrijednost availableTo to dozvoljeno za sve.
- Za implementaciju agenta svim korisnicima, ažurirajte vrijednost distributedTo to nabavljenoForAll.
- Da poništite promjene statusa dostupnosti, ažurirajte vrijednost availableTo to dozvoljeno.
- Da deinstalirate agenta za sve korisnike, ažurirajte vrijednost distributedTo to nabavljenoForNobody.
Za sve/nijedno scenarije, ne morate dati listu dozvoljenim korisnicima Grupe.
Grupno dodijelite vlasnika agenta
Posljednji scenario koji želimo pokriti odnosi se na masovnu preraspodjelu vlasništva za određenog agenta. Ovo je relevantno samo kada agenta kreira korisnik u vašoj organizaciji u različitim iskustvima u SharePointu, PowerApps-u i tako dalje (agent tip je podijeljeno). Ako korisnik napusti kompaniju/njihov nalog je uklonjen, agent je sada bez vlasnika.
Da bismo dobili listu svih agenata bez vlasnika, možemo koristiti sljedeće (opet, nema podrške za filtriranje na strani servera):
$packages = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages?`$filter=supportedHosts/any(x:x eq 'Copilot')" -OutputType PSObject $OwnerlessPackages = $packages.value | ? $_.type -eq 'shared' -and !$_.OwnerId
Možda imate i neke agente sa “null” ownerId vrijednost od 00000000-0000-0000-0000-000000000000slobodno prilagodite gornji filter da ih također uključite.
Da biste dodijelili novog vlasnika, koristite metodu ponovnog dodjeljivanja, što je POST zahtjev protiv /packages/id/reassign krajnja tačka. Mora se navesti JSON sadržaj koji ukazuje na novog vlasnika. Podržan je samo jedan vlasnik po agentu i grupe nisu dozvoljene. Evo primjera zahtjeva:
#Assigning owner to ownerless packages
foreach ($package in $OwnerlessPackages)
Write-Verbose "Assigning owner to package $($package.DisplayName)"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/reassign" -Body (@userId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" Uspješno izvršenje treba biti označeno a 204 Nema sadržaja odgovor, iako mi se čini da proces nije uspio ni u API-ju ni u korisničkom sučelju… tako da ne zadržavajte dah na ovome za sada 🙂
I time možemo zatvoriti trenutni članak. Kada Microsoft uvede podršku za dozvole aplikacija, možemo se vratiti na Agent API i istražiti neka robusnija rješenja, prikladna za automatizaciju.