Onboarding in massa di Agent 365 con PowerShell

Usa l'onboarding in massa di Agent 365 per ridurre la ripetitività durante l'onboarding di più agenti. Definire le identità degli agenti, gli sponsor, i proprietari e le registrazioni in un unico CSV esaminabile, validare le loro relazioni prima del provisioning delle risorse ed esaminare i risultati in un unico report consolidato. Gli script convalidano il file completo, calcolano l'ordine delle dipendenze e poi creano ogni oggetto usando Microsoft Graph.

Usa questo flusso di lavoro dopo aver capito come effettuare l’onboarding di un singolo agente con la CLI di Agent 365. Quando devi integrare molti agenti contemporaneamente o ripetere l'onboarding del tenant, definisci gli oggetti e le loro relazioni in un unico file CSV invece di eseguire separatamente il flusso di lavoro di onboarding della CLI per ogni agente.

Questo articolo fornisce le istruzioni complete per l'onboarding in blocco, dalla configurazione dell'applicazione di automazione e i requisiti CSV fino alla validazione, esecuzione e risoluzione dei problemi.

Important

Gli script di onboarding in massa sono automazione PowerShell nel repository DevTools di Agent 365. Sono separate dall'interfaccia a365 in linea di comando. L'applicazione di automazione descritta in questo articolo è anche separata dall'applicazione client interattiva descritta in Registrazione personalizzata dell'app client per Agent 365 CLI.

Cosa crea il flusso di lavoro

Ogni riga CSV rappresenta un oggetto. Le relazioni supportate sono:

Blueprint
  |
  +-- AgentIdentity
        |-- AgentUser
        +-- AgentRegistration
Object Purpose
Progetto di identità dell'agente Modello di identità e permessi riutilizzabili per uno o più agenti.
L'identità dell'agente Identità Microsoft Entra utilizzata da un singolo agente.
Agente utente Account utente Microsoft Entra opzionale per un agente che necessita di risorse Microsoft 365 con licenza, come una casella di posta.
Registrazione dell'agente Registro dell'inventario che rende l'agente individuabile nelle esperienze amministrative di Agent 365.

Un utente dell'agente e una registrazione dell'agente sono elementi figli indipendenti di un'identità dell'agente. Un fallimento in uno non impedisce che si tenti anche l'altro.

Important

Creare un'identità di agente di per sé non crea un record di inventario Agent 365. Includi una riga AgentRegistration per ogni identità che deve apparire nelle esperienze amministrative di Agent 365. Un AgentUser è opzionale e non è un prerequisito per la registrazione.

Per maggiori informazioni su questi oggetti, vedi Agent 365 identity.

Prerequisites

Prima di iniziare, assicurati di avere:

  • Tenant in cui è disponibile Microsoft Agent 365.
  • PowerShell 7 o versione successiva.
  • Git per clonare il repository DevTools.
  • Il Microsoft.Graph.Authentication modulo PowerShell versione 2.x.
  • Un Amministratore ruolo con privilegi o superiore per il consenso una tantum per le autorizzazioni dell'app di automazione.
  • Uno sponsor per ogni nuovo blueprint e identità di agente.
  • Proprietari, manager e proprietari di registrazione che già esistono in Microsoft Entra ID.
  • Un dominio tenant verificato per ogni nuovo nome principale utente (UPN) di un nuovo agente.
  • Una licenza appropriata e una località di utilizzo di due lettere se il CSV assegna una licenza a un utente agente.

Gli utenti degli agenti sono disponibili solo per i tenant che partecipano al programma di anteprima Frontier.

Installa il modulo Microsoft Graph richiesto:

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

Ottenere gli script

Clona il repository DevTools di Agent 365, poi passa alla directory di registrazione in massa:

git clone https://github.com/microsoft/Agent365-devTools.git
Set-Location .\Agent365-devTools\scripts\bulk-agent-registration

Mantieni insieme gli script in questa directory. A365-BulkOnboarding.ps1 invoca A365-AutomationOrchestrator.ps1, che invoca gli script di provisioning specifici dell'oggetto.

Configurare l'autenticazione

L'onboarding di massa può essere eseguito senza supervisione utilizzando un'applicazione di automazione di proprietà del tenant o un'identità gestita assegnata dal sistema. Può anche essere eseguito in modo interattivo con l'autenticazione delegata.

Completa la configurazione dell'applicazione, il consenso dei permessi e la configurazione dell'autenticazione prima del primo lotto. Per ogni lotto successivo, prepara il CSV, convalida il piano, esegui l'onboarding e ripassa i risultati.

Le esecuzioni solo tramite app utilizzano ruoli applicativi assegnati al service principal dell'applicazione di automazione o dell'identità gestita, non il ruolo amministrativo dell'operatore.

Le concessioni di permessi per l'identità del runner sono separate dall'impostazione del GrantAdminConsent CSV, che richiede il consenso per i permessi dichiarati da un blueprint o dall'identità dell'agente. Rivedi eventuali azioni relative al consenso in sospeso nel report di esecuzione.

Important

Non usare l'applicazione CLI Agent 365 gestita da Microsoft perf54280f4-395e-4ea8-9e48-bf2d4952aa14 questo flusso di lavoro. Quella applicazione serve per l'autenticazione interattiva della CLI e non deve essere modificata.

L'onboarding di massa supporta questi metodi di autenticazione dei runner:

Method Parameters Uso consigliato
Segreto del cliente -TenantId -ClientId -ClientSecret Test o automazione di breve durata
Certificate -TenantId, -ClientId, e esattamente uno di -CertificateThumbprint, -Certificate, o -CertificatePath Automazione della produzione non presidiata
Identità gestita assegnata dal sistema -TenantId -UseManagedIdentity Automazione ospitata su una risorsa Azure
Accesso delegato interattivo -TenantId -Interactive; include -ClientId anche, per un lotto che contiene righe AgentUser Onboarding guidato dall'operatore

Le credenziali di identità federate e la selezione di identità gestita assegnata dall'utente non sono supportate come metodi di autenticazione tramite runner.

Crea l'applicazione di automazione

Accedi interattivamente come Amministratore Globale o Amministratore di Ruoli Privilegiati e crea un'applicazione di automazione per tutti i tipi di oggetti supportati. Crea l'applicazione senza un client secret o certificato così da poter aggiungere e gestire le sue credenziali separatamente nel Interfaccia di amministrazione di Microsoft Entra:

.\New-A365AutomationApp.ps1 `
    -TenantId <tenant-id> `
    -Interactive `
    -DisplayName 'A365 Provisioning Automation' `
    -Scenario All `
    -SkipGrant

Lo script crea o riutilizza l'applicazione e l'entità servizio e dichiara le autorizzazioni dell'applicazione Microsoft Graph richieste e gli ambiti delegati. L'avvertimento che non è stata aggiunta alcuna credenziale è previsto; l'applicazione non può autenticarsi finché non aggiungi un client secret o un certificato. Poiché il comando usa -SkipGrant, non concede il consenso dell'amministratore.

Dopo la fine del comando, chiedi a un amministratore di aprire l'URL Portal stampato dallo script. Nel Interfaccia di amministrazione di Microsoft Entra, seleziona Concedi il consenso dell'amministratore per i permessi dichiarati. Non iniziare l'onboarding in massa finché il consenso amministrativo non è completo. Puoi eseguire di nuovo lo script per riconciliare l'applicazione e le dichiarazioni di autorizzazione mancanti.

Registra l'ID applicazione (client) dell'app di automazione. Non usare il suo ID oggetto dell'entità servizio quando un comando richiede -ClientId.

Rivedi i permessi dell'applicazione

-Scenario All dichiara l'insieme di questi permessi dell'applicazione Microsoft Graph:

Capability Autorizzazioni dell’applicazione
Progetto AgentIdentityBlueprint.Create
AgentIdentityBlueprint.Read.All
AgentIdentityBlueprint.ReadWrite.All
AgentIdentityBlueprint.AddRemoveCreds.All
AgentIdentityBlueprintPrincipal.Create
AgentIdentityBlueprintPrincipal.Read.All
AgentIdentityBlueprintPrincipal.ReadWrite.All
L'identità dell'agente AgentIdentity.Create.All
AgentIdentity.Read.All
AgentIdentity.ReadWrite.All
CustomSecAttributeAssignment.ReadWrite.All
CustomSecAttributeDefinition.Read.All
Registration AgentRegistration.ReadWrite.All
AgentInstance.ReadWrite.All
Agente utente AgentIdUser.ReadWrite.All
User.ReadWrite.All
Organization.Read.All
Ricerca di directory condivise e proprietà Application.Read.All
Application.ReadWrite.All
Directory.Read.All
User.Read.All
Group.Read.All

Gli AgentUserscenari , AgentIdentity, Registration, e All dichiarano anche scope delegati per le loro operazioni interattive selezionate. Gli ambiti di registrazione sono dichiarati di default e possono essere soppressi. Una run unattended che usa Auth=Same si basa sui permessi dell'applicazione nella tabella precedente.

Configura i campi di autenticazione

Definisci un solo hashtable di autenticazione e riutilizzalo per la validazione e l'esecuzione.

Segreto del cliente

Nel Interfaccia di amministrazione di Microsoft Entra, vai su Identity>Applications>Registrazioni app e seleziona l'applicazione di automazione. Seleziona Certificati & segreti>Segreti client>Nuovo segreto client, inserisci una descrizione e una scadenza, poi seleziona Aggiungi. Copia subito il valore segreto e conservalo in modo sicuro; non viene più mostrato dopo aver lasciato la pagina. Per maggiori informazioni, vedi Aggiungi credenziali alla tua applicazione.

Leggi il client secret come un SecureString invece di posizionarlo direttamente sulla riga di comando:

$clientSecret = Read-Host -Prompt 'Automation application client secret' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    ClientSecret = $clientSecret
}

I client secret sono meno sicuri dei certificati e dovrebbero essere limitati ai test o all'automazione di breve durata. Per l'automazione della produzione non supervisionata, utilizzare un certificato o un'identità gestita assegnata dal sistema.

Certificate

Per l'automazione in produzione, ottieni un certificato dall'autorità certificatrice della tua organizzazione. Per ambienti di test, vedi Crea un certificato pubblico autofirmato per autenticare la tua applicazione. Nella pagina Certificati e segreti dell'applicazione di automazione, seleziona Certificati>Carica certificato, carica il file pubblico .cer, .pem o .crt, quindi seleziona Aggiungi. Il runner ha bisogno di accedere alla chiave privata; l'applicazione di automazione memorizza solo il certificato pubblico. Per ulteriori informazioni sull'autenticazione dei certificati solo app, vedi Usa l'autenticazione solo app con il SDK PowerShell di Microsoft Graph.

Usa l'impronta digitale del certificato che contiene la chiave privata:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificateThumbprint = '<certificate-thumbprint>'
}

Per un batch che può contenere righe AgentUser, installa il certificato in Cert:\CurrentUser\My. Per utilizzare un certificato da Cert:\LocalMachine\My per tutti i tipi di oggetti, passalo come oggetto certificato invece di usare la sua impronta digitale.

In alternativa, fornire il certificato come un oggetto X509Certificate2:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Certificate = Get-Item 'Cert:\CurrentUser\My\<certificate-thumbprint>'
}

Oppure carichi la chiave privata da un PFX protetto da password:

$pfxPassword = Read-Host -Prompt 'PFX password' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificatePath = 'C:\secure\a365-automation.pfx'
    CertificatePassword = $pfxPassword
}

Fornisci solo un'origine del certificato. -CertificatePassword è valido solo con -CertificatePath.

Identità gestita assegnata dal sistema

Abilita un'identità gestita assegnata dal sistema sulla risorsa Azure che esegue gli script. Concedi i permessi dell'applicazione Microsoft Graph necessari dalla tabella precedente direttamente all'entità servizio dell'identità gestita. Per le istruzioni, vedi Concedere e revocare i permessi API alle identità gestite.

$authParameters = @{
    TenantId = '<tenant-id>'
    UseManagedIdentity = $true
}

Non includere ClientId con UseManagedIdentity. Gli script utilizzano l'identità assegnata dal sistema dell'host e non supportano la selezione di un'identità assegnata dall'utente.

Accesso delegato interattivo

Usa un ID client controllato dal chiamante affinché lo stesso esempio supporti anche file CSV che contengono righe AgentUser:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Interactive = $true
}

Quando fornisci ClientId, l'autorizzazione interattiva dipende dagli scope delegati consentiti da quell'applicazione e dai ruoli di directory dell'utente connesso. New-A365AutomationApp.ps1 -Scenario All dichiara gli ambiti delegati e abilita i flussi client pubblici. Segui l'URL del consenso dell'amministratore stampato dallo script di configurazione prima della prima esecuzione interattiva. Se un batch non contiene righe AgentUser, puoi omettere ClientId; gli script usano quindi il client PowerShell di Microsoft Graph e i suoi scope consentiti. Le operazioni AgentUser richiedono un ruolo adeguato, come Amministratore ID Agente. Per informazioni di base, vedi Usare i comandi di autenticazione di Microsoft Graph PowerShell.

Note

L'applicazione di automazione di proprietà del tenant può supportare sia l'autenticazione con certificato o segreto solo app sia l'accesso interattivo delegato. L'autorizzazione solo per app utilizza ruoli applicativi. L'autorizzazione interattiva utilizza ambiti delegati e i ruoli di directory dell'utente che ha effettuato l'accesso. Un'identità gestita invece utilizza l'entità servizio della risorsa Azure.

Preparare il file CSV

Avvio con sample-bulk-onboarding.csv. Tieni ogni header nel campione, anche quando una colonna non si applica a una riga. Lascia vuoti i valori non applicabili.

Il campione contiene righe rappresentative per ogni tipo di oggetto supportato. Sostituisci i suoi domini di esempio, identità, proprietari, sponsor, manager e valori delle licenze con valori del tuo tenant.

Definire le relazioni

Le prime quattro colonne definiscono il grafo oggetto:

Column Description
ObjectType Blueprint, AgentIdentity, AgentUser o AgentRegistration.
Key Un nome senza distinzione tra maiuscole e minuscole che identifica in modo univoco la riga all'interno del CSV. Non diventa l'ID oggetto Microsoft Entra.
ParentKey L'elemento Key della riga padre. Le identità degli agenti si riferiscono a un progetto. Gli utenti agente e le registrazioni degli agenti fanno riferimento all'identità dell'agente. Lascialo vuoto per un progetto.
ExistingId Fa riferimento a un ID applicazione blueprint o a un ID oggetto identità agente. Una riga con questo valore è un riferimento invariato per le righe figlie. È supportato solo per Blueprint e AgentIdentity; ParentKey e ogni colonna di impostazione degli oggetti deve essere vuota su quella riga.

Per creare identità di agente sotto un progetto esistente, aggiungi una riga Blueprint di ancoraggio il cui ExistingId è l'ID dell'applicazione di progetto. Assegna a ogni nuova riga AgentIdentity un ParentKey che corrisponda a quello della riga Key di ancoraggio.

Imposta valori per ogni tipo di oggetto

Columns Si applica a Requirements
DisplayName Tutti i tipi di oggetti Richiesto per nuovi progetti, identità degli agenti e registrazioni.
Description Blueprint, AgentRegistration Descrizione facoltativa.
Sponsor Blueprint, AgentIdentity Obbligatorio per la creazione. Usa un UPN, un indirizzo email, un nome visualizzato o un ID oggetto. Separa più valori con punto e virgola.
Owner Blueprint, AgentIdentity, AgentRegistration Usa un UPN, un indirizzo email, un nome visualizzato o un ID oggetto. Separa più valori con i punti e virgola. I proprietari del progetto dell'identità possono essere utenti o entità servizio. I proprietari della registrazione devono essere utenti e sono necessari per la registrazione solo tramite app.
RequireOwnerAssignment Blueprint, AgentIdentity Imposta su true per far fallire la riga se un proprietario non può essere assegnato.
RequiredPermissionJson, GrantAdminConsent Blueprint, AgentIdentity Dichiara i permessi dell'API e concedi opzionalmente il consenso.
SkipInheritablePermissions, NewClientSecret, KeyVaultName, KeyVaultSecretName, ManagedIdentityPrincipalId Blueprint Configura i permessi e le credenziali per i blueprint.
Tag, CustomSecurityAttributeJson, SkipCustomSecurityAttributeValidation AgentIdentity Separa i tag con punti e virgola. Gli attributi di sicurezza personalizzati richiedono i permessi Graph appropriati e il ruolo di directory.
PrincipalName, MailNickname AgentUser PrincipalName è obbligatorio e deve utilizzare un dominio tenant verificato.
ManagerUserId, ManagerUpn AgentUser Usa un solo campo manager, non entrambi.
AssignLicense, UsageLocation, LicenseSkuIdLicenseSkuPartNumber AgentUser Quando AssignLicense è true, fornisci una posizione di utilizzo di due lettere e un campo SKU della licenza.
OwnerId, Auth AgentRegistration OwnerId accetta un ID oggetto utente. Auth accetta Same o Interactive; usa Same per l'onboarding automatico solo app.
ParameterJson Tutti i tipi di oggetti Oggetto JSON opzionale per i parametri avanzati inseriti nell'elenco di elementi consentiti dello script. Sono necessari nomi completi dei parametri. Autenticazione, tenant, azione, parent, output e parametri di registrazione vengono rifiutati.

Important

Un valore in una colonna che non si applica al campo della riga ObjectType è un errore. Il validatore non ignora silenziosamente i valori inseriti in posizione errata.

Convalida il piano di onboarding

Prima di creare qualsiasi oggetto tenant, esegui il CSV completo tramite -WhatIf:

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -WhatIf

Lo script valida l'intero CSV prima che effettui una richiesta Microsoft Graph. Riporta tutti gli errori strutturali rilevati insieme, inclusi:

  • Intestazioni mancanti o sconosciute.
  • Mancano valori obbligatori.
  • Chiavi duplicate.
  • Tipi di oggetti non supportati.
  • Valori GUID, UPN, Booleani o JSON non validi.
  • Combinazioni non valide di ParentKey o ExistingId.
  • Un oggetto padre del tipo di oggetto sbagliato.
  • Cicli di dipendenza.
  • Valori nelle colonne che non si applicano al tipo oggetto della riga.

Se la validazione ha successo, il comando stampa il piano di dipendenza. In -WhatIf, lo script non invia alcuna riga di onboarding a Microsoft Graph.

Una validazione riuscita conferma che il CSV supera i controlli strutturali. Non conferma che gli oggetti tenant possano essere risolti o che l'applicazione abbia i permessi necessari per crearli.

Note

Per l'autenticazione interattiva, un CSV che contiene una riga AgentUser richiede l'applicazione ClientId controllata dal chiamante mostrata nell'esempio precedente. L'utente connesso deve anche avere il consenso delegato richiesto e il ruolo di directory.

Avvia l'onboarding in blocco

Dopo che il piano -WhatIf sembra corretto, esegui l'onboarding e salva i log e il report aggregato:

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -LogPath .\logs `
    -OutputJsonPath .\bulk-onboarding-result.json

Lo script elabora i genitori prima dei figli, mantenendo l'ordine CSV tra righe non correlate. Se una riga fallisce:

  • Lo script segna i suoi discendenti come SkippedDependency e non li invia a Microsoft Graph.
  • Gli alberi di dipendenza indipendenti rimanenti.
  • Il comando scrive il riassunto della console e il report aggregato prima di uscire.
  • Il comando restituisce un codice di uscita diverso da zero se qualsiasi riga è Failed o SkippedDependency.

Esaminare i risultati

Gli stati dell'ultima riga sono:

Condizione Meaning
Existing La riga fa riferimento a un progetto modello o all'identità dell'agente esistente e non è stata modificata.
Succeeded L'oggetto fu creato con successo.
Failed Lo script ha tentato il record ma non l'ha completato correttamente.
SkippedDependency Lo script non ha elaborato la riga perché il suo elemento padre non produceva un ID utilizzabile.

Il parametro -OutputJsonPath crea un A365BulkProvisioningRunReport per l'intera esecuzione. Consulta il rapporto per:

  • Lo stato e l'ID risolutivo per ogni riga.
  • Passaggi falliti e dettagli sugli errori.
  • Azioni di consenso dell'amministratore in sospeso.
  • Ha creato progetto, identità, identificatori utente e identificatori di registrazione.

I log dello script bulk, dell'orchestrator e degli script figli condividono un ID di correlazione quando usano lo stesso -LogPath.

Il report omette i segreti del client blueprint a meno che tu non usi -IncludeBlueprintSecretsInOutput esplicitamente. Il report non include mai input di autenticazione, token di accesso o password di certificato.

Warning

Non abilitare l'output segreto o il logging segreto nell'automazione di routine. Se una credenziale appare in una trascrizione, registro, segnalazione, ticket, chat o screenshot, revocala e rigenerala immediatamente.

Verifica onboarding

Dopo la corsa:

  • Esamina lo stato di ogni riga e l'ID dell'oggetto risultante.
  • Verifica che le registrazioni attese compaiano nell'amministrazione di Agent 365.
  • Controlla gli sponsor assegnati e i proprietari assegnati.
  • Se hai richiesto utenti o licenze agenti, verifica quelle assegnazioni.
  • Rivedere e completare le azioni di consenso dell'amministratore in sospeso.

Recuperare da un'esecuzione parziale

Warning

Prima di riprovare, ispeziona il report e gli oggetti tenant per determinare cosa già esiste. Non dare per scontato che il lavoro completato sia stato annullato o che rieseguire l'intero CSV eviti duplicati.

Puoi fare riferimento ai blueprint esistenti e alle identità degli agenti tramite ExistingId le righe di ancoraggio. Questa opzione non è supportata per le righe agent-utente o di registrazione.

Correggi l'errore e prepara un batch revisionato di nuovi tentativi basandoti sullo stato osservato del tenant, invece di rieseguire ciecamente le righe riuscite.

Troubleshooting

Usa la tabella seguente per risolvere i problemi comuni di onboarding.

Sintomo Resolution
La configurazione dell'applicazione di automazione restituisce un errore di autorizzazione. Accedi come Amministratore Globale o Amministratore di Ruoli Privilegiati. Per concedere permessi di applicazione Microsoft Graph è necessario il consenso dell'amministratore.
Una riga di provisioning restituisce HTTP 403. Conferma che hai creato l'applicazione di automazione con -Scenario All, che hai concesso i suoi ruoli applicativi e che hai acquisito un nuovo token dopo il consenso.
Una riga dell'utente agente viene rifiutata prima dell'esecuzione. Usa l'autenticazione basata solo su app. Conferma che l'UPN utilizza un dominio verificato. Se assegni una licenza, fornisci UsageLocation e LicenseSkuId o LicenseSkuPartNumber.
Un proprietario, uno sponsor o un manager non può essere individuato. Usa un UPN, un indirizzo email o un ID oggetto non ambiguo. I proprietari della registrazione devono essere associati agli utenti.
Una riga figlia è SkippedDependency. Correggi la riga padre non riuscita o non risolta. L'elemento figlio non è stato inviato a Microsoft Graph.
Un'identità esiste in Microsoft Entra ma non è visibile nell'amministrazione di Agent 365. Aggiungi una AgentRegistration riga per l'identità. Creare un'identità da solo non crea il record dell'inventario dell'Agente 365.
Il validatore CSV riporta un valore in una colonna non supportata. Sposta il valore in una colonna compatibile con ObjectType, oppure lascia la cella vuota.
L'assegnazione personalizzata degli attributi di sicurezza restituisce HTTP 403. L'applicazione di automazione ha bisogno di CustomSecAttributeAssignment.ReadWrite.All e CustomSecAttributeDefinition.Read.All. L'assegnazione interattiva richiede inoltre che l'utente connesso ricopra il ruolo di Amministratore dell'Assegnazione degli Attributi.

Per problemi generali sul prodotto e sulla CLI, consulta la guida alla risoluzione dei problemi di Agent 365. Per segnalare un problema con questi script, usa Agent 365 DevTools issues.

Passaggi successivi

Dopo l'inserimento dei tuoi agenti: