Exportação/restauração do Git

Observação: em fevereiro de 2025, uma nova versão dessa integração foi lançada. Os usuários da versão antiga podem fornecer tokens sem usar secrets. A documentação abaixo se aplica principalmente à nova versão.

O Dialogflow CX se integra a vários provedores Git (GitHub, Gitlab, Bitbucket e outros). Essa integração facilita a exportação do agente para JSON para um push para um provedor Git e para extrair de um provedor Git para uma restauração de agente. O formato JSON exportado enviado para um provedor do Git é o conteúdo do arquivo ZIP expandido do agente exportado.

Ao usar esse recurso, você pode aproveitar os recursos de controle de origem de um provedor do Git, como:

• Análises de mudanças de agentes usando ferramentas de revisão de código
• Analisar as diferenças do agente usando ferramentas de comparação
• Mesclagens

Limitações

Considere as seguintes limitações:

• [Somente na versão de integração antiga] As APIs do GitHub têm uma limitação no número de arquivos que podem ser atualizados em um único commit. Se o número de arquivos exceder 500, talvez não seja possível enviar para o GitHub pelo Dialogflow CX. Nesses casos, é possível exportar o agente como um ZIP e usar a CLI do Git na sua máquina para enviar os arquivos do agente para o GitHub. Essa limitação será abordada em uma versão posterior do Dialogflow CX.
• Os repositórios auto-hospedados de acesso privado do GitHub não são compatíveis, porque o Dialogflow CX não pode acessá-los.
• O repositório Git não pode conter arquivos além dos arquivos do agente exportados pela exportação do agente. Todos os outros arquivos no repositório serão removidos em cada push.

Configuração

Para configurar esse recurso, é necessário adquirir um token de acesso do seu provedor do Git, armazená-lo no Secret Manager e fornecer o recurso de secret ao Dialogflow CX:

Token de acesso

Para adquirir um token de acesso do seu provedor Git:

GitHub

Você precisa adquirir um token pessoal do GitHub. Se você usar um token de acesso pessoal refinado, precisará das seguintes permissões de acesso:

• Permissões do repositório > Conteúdo: ler e gravar
• Permissões do repositório > Metadados: somente leitura (deve ser selecionado automaticamente depois de selecionar a permissão de conteúdo)

Gitlab

Você precisa adquirir um token de acesso pessoal do Gitlab.

Bitbucket

Você precisa adquirir um token de acesso do Bitbucket.

Secret Manager

Agora que você tem um token de acesso, é preciso criar um secret para ele:

1. Ative a API Secret Manager.
2. Criar um secret.

Configuração do Dialogflow CX

Para configurar essa integração para o Dialogflow CX:

1. Dê ao agente de serviço do Dialogflow permissão para acessar o secret do token de acesso no Secret Manager. Conceda o papel Secret Manager Secret Accessor à conta de serviço gcp-sa-dialogflow. no projeto do agente. Consulte Conceder acesso ao secret do Secret Manager.
2. Abra a configuração da integração do Git:
   • Console dos agentes de conversação
     1. Abra a tela de configurações clicando no ícone de configurações perto do canto superior direito.
     2. Role para baixo e clique em Adicionar integração com o Git.
   • Console do Dialogflow CX
     1. Clique na guia Gerenciar.
     2. Clique em Git na seção Teste e implantação.
     3. Clique em Criar novo.
3. Informe os detalhes de configuração:
   1. Digite o seguinte:
      • Nome de exibição da conexão do GitHub.
      • URL do repositório Git (por exemplo: https://github.com/<path-to-repo>.git).
      • Adicione as ramificações do Git com que o agente vai interagir. Para designar uma ramificação como padrão, clique no ícone de estrela ao lado dela.
      • Secret do token de acesso, que é a versão do secret que você criou no formato projects/*/secrets/*/versions/* para uma versão específica ou projects/*/secrets/*/versions/latest para a versão mais recente.
   2. Clique em Conectar.
   3. Pode levar um minuto para o serviço do Git ficar pronto. O console vai mostrar notificações.

Enviar e restaurar

Depois de configurado, é possível enviar/extrair o agente para/do Git.

O botão Push é usado para exportar o agente e fazer um commit na ramificação do Git selecionada no menu suspenso. Esse commit vai consistir em todo o agente, não em mudanças específicas, e vai excluir todos os arquivos no repositório.

Os usuários com papéis de Leitor do Dialogflow podem enviar para repositórios do Git. Para evitar pushes indesejados, configure esses agentes com tokens de acesso pessoal somente leitura.

O botão Restaurar é usado para extrair os dados do agente de CX da ramificação do Git selecionada no menu suspenso e restaurar o agente de CX do Dialogflow CX com base nesses dados. Isso vai substituir seu agente da mesma forma que qualquer restauração de agente.

Exemplo de caso de uso:

O exemplo a seguir ilustra como esse recurso pode ser usado por várias pessoas para propor diferentes mudanças em um agente de produção.

Considere que seu agente usa as seguintes ramificações do Git:

• Prod: ramificação para seu agente de produção
• Dev1: ramificação para desenvolvimento de agentes
• Dev2: outra ramificação para o desenvolvimento de agentes.

O Usuário 1 quer propor mudanças no agente e segue estas etapas:

1. Exporte o agente de produção para um novo agente.
2. Faça as mudanças que quiser nessa cópia do agente.
3. Teste as mudanças.
4. Envie o agente alterado para a ramificação Dev1.
5. Crie uma solicitação de mesclagem para a ramificação Prod.

O Usuário 2 quer propor mudanças no agente e segue estas etapas:

1. Exporte o agente de produção para um novo agente.
2. Faça as mudanças que quiser nessa cópia do agente.
3. Teste as mudanças.
4. Envie o agente alterado para a ramificação Dev2.
5. Crie uma solicitação de mesclagem para a ramificação Prod.

O Usuário 3 analisa as solicitações de mesclagem de ambos os usuários e segue estas etapas:

1. Resolva os conflitos.
2. Confirma as mudanças aprovadas.
3. Restaura a ramificação de produção do Git para o agente de CX do Dialogflow CX.