Exportação/restauro do Git

Nota: em fevereiro de 2025, foi lançada uma nova versão desta integração. Os utilizadores da versão antiga podem fornecer tokens sem usar segredos. A documentação abaixo aplica-se principalmente à nova versão.

Os agentes conversacionais (Dialogflow CX) integram-se com vários fornecedores de Git (GitHub, Gitlab, Bitbucket e outros). Esta integração facilita a exportação do seu agente para JSON para um envio para um fornecedor do Git, e a obtenção de um fornecedor do Git para um restauro do agente. O formato JSON exportado enviado para um fornecedor do Git é o conteúdo do ficheiro ZIP expandido do agente exportado.

A utilização desta funcionalidade permite-lhe tirar partido das funcionalidades de controlo da origem de um fornecedor do Git, como:

• Os agentes alteram as críticas através de ferramentas de revisão de código
• Examine as diferenças dos agentes com ferramentas de diferenças
• Unir

Limitações

Aplicam-se as seguintes limitações:

• [Apenas versão antiga da integração] As APIs GitHub têm uma limitação no número de ficheiros que podem ser atualizados num único commit. Se o número de ficheiros exceder 500, pode não conseguir enviar para o GitHub a partir de agentes conversacionais (Dialogflow CX). Nestes casos, pode exportar o agente como um ficheiro ZIP e usar a CLI do Git na sua máquina para enviar os ficheiros do agente para o GitHub. Esta limitação vai ser resolvida numa versão posterior dos agentes conversacionais (Dialogflow CX).
• O acesso privado do GitHub autoalojado não é suportado, porque os agentes conversacionais (Dialogflow CX) não conseguem aceder a estes repositórios.
• O repositório Git não pode conter outros ficheiros além dos ficheiros do agente exportados pela exportação do agente. Todos os outros ficheiros no repositório são removidos em cada envio.

Configuração

Para configurar esta funcionalidade, tem de adquirir um token de acesso junto do seu fornecedor de Git, armazená-lo no Secret Manager e fornecer o recurso secreto aos agentes conversacionais (Dialogflow CX):

Chave de acesso

Para adquirir uma chave de acesso do seu fornecedor de Git:

GitHub

Tem de adquirir um token pessoal do GitHub Se usar um token de acesso pessoal detalhado, precisa do seguinte acesso às autorizações

• Autorizações do repositório > Conteúdos: leitura e escrita
• Autorizações do repositório > Metadados: só de leitura (deve ser selecionado automaticamente depois de selecionar a autorização de conteúdos)

Gitlab

Tem de adquirir um token de acesso pessoal do Gitlab.

Bitbucket

Tem de adquirir um token de acesso do Bitbucket.

Secret Manager

Agora que tem uma chave de acesso, tem de criar um segredo para a sua chave:

1. Ative a API Secret Manager.
2. Crie um segredo.

Configuração de agentes conversacionais (Dialogflow CX)

Para configurar esta integração para agentes conversacionais (Dialogflow CX):

1. Conceda ao agente de serviço do Dialogflow autorização para aceder ao segredo do token de acesso no Secret Manager. Conceda a função Secret Manager Secret Accessor à conta de serviço gcp-sa-dialogflow.iam.gserviceaccount.com no projeto do agente. Consulte o artigo Conceda acesso ao segredo do Secret Manager.
2. Abra a configuração da integração do Git:
   • Consola de agentes conversacionais
     1. Abra o ecrã de definições clicando no ícone de definições junto ao canto superior direito.
     2. Desloque a página para baixo e clique em Adicionar integração do Git.
   • Consola do Dialogflow CX
     1. Clique no separador Gerir.
     2. Clique em Git na secção Testes e implementação.
     3. Clique em Criar novo.
3. Forneça detalhes de configuração:
   1. Introduza os seguintes dados:
      • Nome a apresentar para a associação do GitHub.
      • URL do repositório Git (por exemplo: https://github.com/<path-to-repo>.git).
      • Adicione as ramificações do Git com as quais o seu agente vai interagir. Pode designar uma ramificação como a ramificação predefinida clicando no ícone de estrela junto à mesma.
      • O segredo do token de acesso, que é a versão do segredo que criou no formulário projects/*/secrets/*/versions/* para uma versão específica ou projects/*/secrets/*/versions/latest para a versão mais recente.
   2. Clique em Ligar.
   3. O serviço Git pode demorar um minuto a ficar pronto. A consola apresenta notificações.

Envie e restaure

Depois de configurado, pode enviar/extrair o seu agente para/do Git.

O botão Enviar é usado para exportar o seu agente e consolidar o ramo do Git selecionado no menu pendente do ramo do Git. Este commit vai consistir no agente completo e não em alterações específicas, e vai eliminar todos os ficheiros existentes no repositório.

Os utilizadores com funções de leitor do Dialogflow têm a capacidade de enviar para repositórios do Git. Para evitar envios indesejados, configure estes agentes com tokens de acesso pessoal só de leitura.

O botão Restaurar é usado para extrair os dados do agente do ramo Git selecionado no menu pendente do ramo Git e restaurar o agente de agentes conversacionais (Dialogflow CX) a partir destes dados. Esta ação substitui o seu agente da mesma forma que qualquer restauro de agente.

Exemplo de utilização

O exemplo seguinte ilustra como esta funcionalidade pode ser usada por várias pessoas para propor diferentes alterações de agentes a um agente de produção.

Considere que o seu agente usa os seguintes ramos do Git:

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

O utilizador 1 quer propor alterações ao agente e segue os seguintes passos:

1. Exporte o agente de produção para um novo agente.
2. Faça as alterações pretendidas a esta cópia do agente.
3. Teste as alterações.
4. Envie o agente alterado para o ramo Dev1.
5. Crie um pedido de união para o ramo Prod.

O utilizador 2 quer propor alterações ao agente e segue os seguintes passos:

1. Exporte o agente de produção para um novo agente.
2. Faça as alterações pretendidas a esta cópia do agente.
3. Teste as alterações.
4. Envie o agente alterado para o ramo Dev2.
5. Crie um pedido de união para o ramo Prod.

O utilizador 3 revê os pedidos de união de ambos os utilizadores e toma as seguintes medidas:

1. Resolva conflitos.
2. Confirma as alterações aprovadas.
3. Restaura o ramo Git de produção para o agente de agentes conversacionais de produção (Dialogflow CX).