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 i 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 un push a un provider Git e il pull da un provider Git per il ripristino di un agente. Il formato JSON esportato e inviato a un provider Git è il contenuto del file ZIP espanso dell'agente esportato.

L'utilizzo di questa funzionalità consente di sfruttare le funzionalità di controllo del codice sorgente di un provider Git, ad esempio:

• Revisioni delle modifiche dell'agente utilizzando gli strumenti di revisione del codice
• Esame delle differenze tra gli agenti utilizzando gli strumenti di confronto
• Unioni

Limitazioni

Si applicano le seguenti limitazioni:

• [Solo versione precedente dell'integrazione] Le API GitHub hanno una limitazione al numero di file che possono essere aggiornati in un singolo commit. Se il numero di file supera 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 Git sulla tua macchina per eseguire il push dei file dell'agente su GitHub. Questa limitazione verrà risolta in una release successiva di Dialogflow CX.
• I repository privati self-hosted di GitHub 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 con granularità fine, devi disporre delle seguenti autorizzazioni di accesso:

• Autorizzazioni repository > Contenuti: lettura e scrittura
• Autorizzazioni repository > Metadati: sola lettura (deve essere selezionata automaticamente dopo aver selezionato l'autorizzazione 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'account di servizio Dialogflow l'autorizzazione ad accedere al secret del token di accesso in Secret Manager. Concedi il ruolo Secret Manager Secret Accessor al account di servizio gcp-sa-dialogflow.iam.gserviceaccount.com nel progetto dell'agente. Consulta Concedere l'accesso al secret di Secret Manager.
2. Apri la configurazione dell'integrazione Git:
   • Console Agenti conversazionali
     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 di 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 quanto segue:
      • 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 ramo predefinito facendo clic sull'icona a forma di stella accanto a questo.
      • 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 visualizzerà le notifiche.

Push e ripristino

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

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

Gli utenti con i ruoli Lettore Dialogflow hanno la possibilità di eseguire il push nei repository Git. Per evitare push indesiderati, configura questi agenti con token di accesso personali di sola lettura.

Il pulsante Ripristina viene utilizzato per eseguire il pull dei dati dell'agente dal ramo Git selezionato nel menu a discesa Ramo Git e ripristinare l'agente Dialogflow CX da questi dati. In questo modo l'agente verrà sovrascritto nello stesso modo in cui si comporta qualsiasi ripristino dell'agente.

Caso d'uso di esempio

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

Supponiamo che l'agente utilizzi i seguenti rami Git:

• Prod: ramo per l'agente di produzione
• Dev1: ramo per lo sviluppo dell'agente
• Dev2: un altro ramo per lo sviluppo dell'agente

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 desiderate a questa copia dell'agente.
3. Testa le modifiche.
4. Esegui il push dell'agente modificato nel ramo Dev1.
5. Crea una richiesta di unione nel ramo 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 desiderate a questa copia dell'agente.
3. Testa le modifiche.
4. Esegui il push dell'agente modificato nel ramo Dev2.
5. Crea una richiesta di unione nel ramo 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 ramo Git di produzione nell'agente di produzione di Dialogflow CX.