Esportazione/ripristino di Git

Nota: a febbraio 2025 è stata rilasciata una nuova versione di questa integrazione. Gli utenti della versione precedente possono fornire token senza utilizzare secret. La documentazione riportata di seguito si applica principalmente alla nuova versione.

Dialogflow CX si integra con più provider Git (GitHub, Gitlab, Bitbucket e altri). Questa integrazione semplifica l'esportazione dell'agente in JSON per il push a un provider Git e il pull da un provider Git per il ripristino dell'agente. Il formato JSON esportato inviato a un provider Git è il contenuto del file ZIP espanso dell'agente esportato.

L'utilizzo di questa funzionalità ti consente di sfruttare le funzionalità di controllo della versione di un provider Git, ad esempio:

• Revisioni delle modifiche dell'agente utilizzando strumenti di revisione del codice
• Esamina le differenze degli agenti utilizzando gli strumenti di confronto
• Unioni

Limitazioni

Si applicano le seguenti limitazioni:

• [Solo per la versione precedente dell'integrazione] Le API GitHub hanno un limite al numero di file che possono essere aggiornati in un singolo commit. Se il numero di file supera i 500, potresti non essere in grado di eseguire il push su GitHub da Dialogflow CX. In questi casi, puoi esportare l'agente come file ZIP e utilizzare l'interfaccia a riga di comando di Git sulla tua macchina per eseguire il push dei file dell'agente su GitHub. Questa limitazione verrà risolta in una release futura di Dialogflow CX.
• I repository di accesso privato GitHub self-hosted non sono supportati, perché Dialogflow CX non può accedervi.
• Il repository Git non può contenere file diversi da quelli dell'agente esportati dall'esportazione dell'agente. Tutti gli altri file nel repository verranno rimossi a ogni push.

Configurazione

Per configurare questa funzionalità, devi acquisire un token di accesso dal tuo provider Git, archiviarlo in Secret Manager e fornire la risorsa secret a Dialogflow CX:

Token di accesso

Per acquisire un token di accesso dal tuo provider Git:

GitHub

Devi acquisire un token personale GitHub. Se utilizzi un token di accesso personale granulare, devi disporre delle seguenti autorizzazioni di accesso:

• Repository Permissions > Contents (Autorizzazioni repository > Contenuti): Read and write (Lettura e scrittura)
• Repository Permissions > Metadata (Autorizzazioni repository > Metadati): Sola lettura (dovrebbe essere selezionata automaticamente dopo aver selezionato l'autorizzazione Contents (Contenuti))

GitLab

Devi acquisire un token di accesso personale GitLab.

Bitbucket

Devi acquisire un token di accesso Bitbucket.

Secret Manager

Ora che hai un token di accesso, devi creare un secret per il token:

1. Abilita l'API Secret Manager.
2. Crea un secret.

Configurazione di Dialogflow CX

Per configurare questa integrazione per Dialogflow CX:

1. Concedi all'agente di servizio Dialogflow l'autorizzazione per accedere al secret del token di accesso in Secret Manager. Assegna il ruolo Secret Manager Secret Accessor all'account di servizio gcp-sa-dialogflow.iam.gserviceaccount.com nel progetto dell'agente. Consulta Concedi l'accesso al secret di Secret Manager.
2. Apri la configurazione dell'integrazione Git:
   • Console Conversational Agents
     1. Apri la visualizzazione delle impostazioni facendo clic sull'icona delle impostazioni nell'angolo in alto a destra.
     2. Scorri verso il basso e fai clic su Aggiungi integrazione Git.
   • Console Dialogflow CX
     1. Fai clic sulla scheda Gestisci.
     2. Fai clic su Git nella sezione Test e deployment.
     3. Fai clic su Crea nuova.
3. Fornisci i dettagli della configurazione:
   1. Inserisci:
      • Nome visualizzato per la connessione GitHub.
      • URL del repository Git (ad esempio: https://github.com/<path-to-repo>.git).
      • Aggiungi i rami Git con cui interagirà l'agente. Puoi designare un ramo come predefinito facendo clic sull'icona a forma di stella accanto.
      • Secret del token di accesso, ovvero la versione del secret che hai creato nel formato projects/*/secrets/*/versions/* per una versione specifica o projects/*/secrets/*/versions/latest per l'ultima versione.
   2. Fai clic su Connetti.
   3. Potrebbe essere necessario un minuto prima che il servizio Git sia pronto. La console mostrerà le notifiche.

Push e ripristino

Una volta configurato, puoi eseguire il push/pull dell'agente su/da Git.

Il pulsante Push viene utilizzato per esportare l'agente ed eseguire un commit nel branch Git selezionato nel menu a discesa del branch Git. Questo commit sarà costituito dall'intero agente e non da modifiche specifiche ed eliminerà tutti i file esistenti nel repository.

Gli utenti con ruoli Lettore Dialogflow possono eseguire il push ai repository Git. Per impedire push indesiderati, configura questi agenti con token di accesso personale di sola lettura.

Il pulsante Ripristina viene utilizzato per estrarre i dati dell'agente dal branch Git selezionato nel menu a discesa del branch Git e ripristinare l'agente Dialogflow CX da questi dati. In questo modo, l'agente verrà sovrascritto come avviene per qualsiasi ripristino di un agente.

Caso d'uso di esempio

L'esempio seguente illustra come questa funzionalità può essere utilizzata da più persone per proporre diverse modifiche all'agente di produzione.

Supponiamo che il tuo agente utilizzi i seguenti rami Git:

• Prod: branch per l'agente di produzione
• Dev1: branch per lo sviluppo degli agenti
• Dev2: un altro branch per lo sviluppo degli agenti

L'Utente 1 vuole proporre modifiche all'agente e segue questi passaggi:

1. Esporta l'agente di produzione in un nuovo agente.
2. Apporta le modifiche che preferisci a questa copia dell'agente.
3. Testa le modifiche.
4. Esegui il push dell'agente modificato nel branch Dev1.
5. Crea una richiesta di unione al branch Prod.

L'Utente 2 vuole proporre modifiche all'agente e segue questi passaggi:

1. Esporta l'agente di produzione in un nuovo agente.
2. Apporta le modifiche che preferisci a questa copia dell'agente.
3. Testa le modifiche.
4. Esegui il push dell'agente modificato nel branch Dev2.
5. Crea una richiesta di unione al branch Prod.

L'utente 3 esamina le richieste di unione di entrambi gli utenti e segue questi passaggi:

1. Risolvi i conflitti.
2. Esegue il commit delle modifiche approvate.
3. Ripristina il branch Git di produzione nell'agente Dialogflow CX di produzione.