Esportazione/ripristino di Git

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

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

L'utilizzo di questa funzionalità ti 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
• Esaminare le 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 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 push su GitHub dagli agenti conversazionali (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 spingere i file dell'agente su GitHub. Questa limitazione verrà risolta in una release successiva di Conversational Agents (Dialogflow CX).
• I repository con accesso privato GitHub self-hosted non sono supportati, poiché Conversational Agents (Dialogflow CX) non può accedere a questi repository.
• Il repository Git non può contenere altri file oltre a 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 agli agenti di conversazione (Dialogflow CX):

Token di accesso

Per ottenere 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.

• Autorizzazioni del repository > Contenuti: lettura e scrittura
• Autorizzazioni del repository > Metadati: di sola lettura (dovrebbe essere selezionata automaticamente dopo la selezione dell'autorizzazione Contenuti)

GitLab

Devi acquisire un token di accesso personale Gitlab.

Bitbucket

Devi acquisire un token di accesso a Bitbucket.

Secret Manager

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

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

Configurazione di Conversational Agents (Dialogflow CX)

Per configurare questa integrazione per Conversational Agents (Dialogflow CX):

1. Fornisci all'agente di servizio Dialogflow l'autorizzazione per accedere a Secret Manager. Fornisci il ruolo Secret Manager Secret Accessor all'account di servizio gcp-sa-dialogflow.iam.gserviceaccount.com nel progetto dell'agente. Consulta Concedere un ruolo IAM.
2. Apri la configurazione dell'integrazione di Git:
   • Console degli agenti conversazionali
     1. Apri la visualizzazione delle impostazioni facendo clic sull'icona delle impostazioni vicino all'angolo in alto a destra.
     2. Scorri verso il basso e fai clic su Aggiungi integrazione di 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 di 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 branch Git con cui l'agente interagirà. Puoi designare un ramo come predefinito facendo clic sull'icona a forma di stella accanto.
      • Secret token di accesso, ovvero la versione del secret che hai creato nel modulo projects/*/secrets/*/versions/* per una versione specifica o projects/*/secrets/*/versions/latest per la versione più recente.
   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 in/da Git.

Il pulsante Push viene utilizzato per esportare l'agente e eseguire un commit sul branch Git selezionato nel menu a discesa del branch 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 possono eseguire push nei repository Git. Per evitare 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 ramo Git selezionato nel menu a discesa del ramo Git e ripristinare l'agente Conversational Agents (Dialogflow CX) da questi dati. 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 diverse modifiche dell'agente a un agente di produzione.

Supponiamo che il tuo agente utilizzi i seguenti rami Git:

• Prod: il branch 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 agli agenti 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 ramo Prod.

L'utente 2 vuole proporre modifiche agli agenti 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 ramo Prod.

L'utente 3 esamina le richieste di unione di entrambi gli utenti ed esegue i seguenti passaggi:

1. Risolvi i conflitti.
2. Applica le modifiche approvate.
3. Ripristina il ramo Git di produzione nell'agente Conversational Agents (Dialogflow CX) di produzione.