Adicionar ações do Jira Cloud

Quando as ações do Jira estão ativadas, os usuários finais podem pedir ao Google Assistente para realizar as seguintes ações do Jira Cloud:

  • Criar problemas no Jira
  • Editar problemas do Jira

Por exemplo, um usuário pode inserir "criar uma história do Jira chamada 'Lançar o projeto Y' no projeto ABC" ou "atualizar o título do tíquete do Jira JCD-1 para 'Lançar o projeto Y'" no seu app. O assistente pede mais detalhes, se necessário, e depois pede que o usuário confirme a solicitação de criação ou edição.

O assistente pode ler e editar os seguintes campos do Jira por ações:

Campo Descrição
ID do problema Obrigatório. ID do problema a ser modificado, por exemplo, KAN-123.
Título Título do problema.
Tipo de problema Tipo de problema.
Prioridade Prioridade do problema.
Status Status do problema.
Descrição Descrição do problema no formato Markdown.
Componente Componente de problema.
Responsável Atribuído ao problema, por exemplo, user@google.com.

Configurar autenticação e permissões no Jira

Antes de ativar as ações do Jira, um administrador do Jira precisa configurar credenciais dedicadas do OAuth 2.0 para ações no Jira. Isso é necessário para conectar sua integração do Jira e permitir permissão de leitura e gravação para ações.

Os clientes de autorização para ações do Jira são diferentes daqueles para ingestão de dados do Jira. Eles usam permissões e uma configuração de URL de callback diferentes. Para saber como configurar clientes de autorização para conectores do Jira Cloud e ingerir dados, consulte Conectar o Jira Cloud.

Estas instruções explicam como criar um ID do cliente e uma chave secreta do cliente usando o Atlassian Developer Console, configurar os escopos necessários do OAuth 2.0 e definir permissões para usuários. Por fim, recupere o URL e o ID da instância, configure papéis e faça a autenticação para ler e gravar dados entre o Jira Cloud e o Google.

Criar ID e chave secreta do cliente

  1. Faça login em developer.atlassian.com.
  2. Clique no ícone de perfil no canto superior direito e selecione Developer Console.
  3. Clique em Criar e selecione Integração do OAuth 2.0.
  4. Insira um nome para o app.
    • Marque a caixa de seleção dos Termos e Condições.
    • Clique em Criar.
  5. Clique em Autorização.
  6. Na tabela Tipo de autorização, selecione Adicionar para OAuth 2.0 (3LO).
  7. No campo URL de callback, insira https://vertexaisearch.cloud.google.com/oauth-redirect e clique em Salvar alterações.

  8. Clique em Permissões:

    1. Acesse API Jira, clique em Adicionar e em Configurar.

    2. Acesse a guia Escopos clássicos e clique em Editar escopos. Selecione os seguintes escopos e salve as mudanças:

      • Escopos clássicos:

        • read:jira-work
        • read:jira-user
        • write:jira-work

      • Escopos granulares:

        • read:user:jira

  9. Clique em Distribuição, selecione Editar e faça o seguinte:

    1. Selecione primeiro o botão de opção Compartilhamento para ativar a edição de outros campos.
    2. Preencha os campos restantes.
      1. Em Fornecedor, selecione Google.
      2. Em Política de Privacidade, insira https://policies.google.com.
      3. Em O app armazena dados pessoais?, selecione Yes.
      4. Marque a caixa de seleção Confirmo que implementei a API de relatórios de dados pessoais.
    3. Clique em Salvar alterações.

  10. Selecione Configurações para copiar o ID do cliente e a chave secreta do cliente.

Recuperar o URL e o ID da instância

Para conseguir o URL da instância:

  1. Acesse atlassian.net e faça login com sua conta de administrador.
  2. Selecione o app que você quer sincronizar. Por exemplo, sincronize o primeiro app.
  3. Encontre o URL da instância, que é o subdomínio na barra de endereço.

Para conseguir o ID da instância:

  1. Abra uma nova guia, copie o URL da instância e adicione /_edge/tenant_info ao URL da instância. Por exemplo, https://YOUR-INSTANCE.atlassian.net/_edge/tenant_info.
  2. Navegue até o link para encontrar o valor cloudId. O cloudId é o ID da instância.

Configurar permissões e papéis

  1. Faça login em atlassian.com com sua conta de administrador.
  2. Clique no ícone de menu no canto superior esquerdo ou acesse admin.atlassian.com.
  3. Na página Administrador, clique em Gerenciar usuários e acesse a página Grupos.
  4. Clique em Criar grupo. Digite um nome para o grupo e crie-o.
  5. Na seção Acesso a produtos do grupo da página do novo grupo, clique em Adicionar produtos ao grupo.
  6. Em Jira, selecione Administrador de acesso do usuário como a função do produto.
  7. Para Administrador do Jira, selecione Administrador do produto como a função do produto e salve as mudanças.
  8. Na página Grupos, clique em Adicionar membros do grupo e adicione usuários ou contas que o conector vai autenticar.

Receber um token de atualização

Se você planeja configurar ações do Jira usando o console Google Cloud , não é necessário obter um token de atualização.

Se você precisar usar a API para configurar suas ações do Jira, um token de atualização será necessário. Para receber um token de atualização:

  1. Acesse seu app no console Google Cloud .
  2. Selecione Autorização.
  3. Selecione Configurar ao lado de OAuth 2.0 (3LO).
  4. Para o URL de redirecionamento, use um marcador de posição, como https://example.com.
  5. Para receber um token de atualização no fluxo de autorização inicial, adicione offline_access ao parâmetro de escopo do URL de autorização. Por exemplo: https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=your_client_id**&scope=offline_access**%20read%3Ajira-user&redirect_uri=https%3A%2F%2Fyour-redirect-url&state=%24%7BYOUR_USER_BOUND_VALUE%7D&response_type=code&prompt=consent
  6. Depois da autorização, você será redirecionado de volta para o URL de redirecionamento. Na barra de endereço, você vai encontrar um parâmetro de consulta chamado "code". Anote o valor.

  7. Use ferramentas como curl ou postman para enviar uma solicitação POST para https://auth.atlassian.com/oauth/token, com um objeto JSON com as seguintes chaves:

    1. grant_type: authorization_code
    2. client_id: seu ID do cliente
    3. client_secret: sua chave secreta do cliente
    4. code: o código que você recebeu na etapa 6
    5. redirect_uri: seu URI de redirecionamento

  8. Você vai receber o refresh_token na resposta

Para mais informações sobre tokens de atualização, consulte Implementar o fluxo de token de atualização na documentação da Atlassian.

Configurar uma ação do Jira

Nesta seção, descrevemos como criar um conector do Jira para ações e ativar ações do Jira para seu assistente.

Antes de começar

Antes de configurar as ações, verifique se as etapas a seguir foram concluídas:

  • Seu projeto precisa ser adicionado à lista de permissões para ações do Google Assistente.
  • Um administrador do Jira concluiu as etapas em Configurar autenticação e permissões no Jira e forneceu as seguintes informações:
    • ID do cliente
    • Chave secreta do cliente
    • ID da instância
    • Token de atualização. Necessário apenas para criar ações do Jira pela API em vez do console do Google Cloud . O Google recomenda criar ações pelo console do Google Cloud .

Configurar ações do Jira no console do Google Cloud

O Google recomenda criar ações no console Google Cloud .

Para adicionar ações ao app usando o console, faça o seguinte:

  1. No console Google Cloud , acesse a página do Gemini Enterprise.
  2. Acesse o app.
  3. No menu de navegação, clique em Ações.
  4. Para o Jira, clique em Conectar.
  5. Selecione uma instância do Jira.
  6. Se solicitado, insira as informações de autorização do conector. Isso só é necessário se a instância ainda não tiver sido configurada para uma ação.
  7. Selecione as ações que você quer ativar.
  8. Clique em Concluir configuração. Sua ação é exibida na página Ações.

Criar e ativar ações do Jira usando a API

O Google recomenda que você crie ações pelo console Google Cloud . Se você precisar criar ações usando a API, faça o seguinte:

  1. Crie um conector do Jira e configure-o para pesquisa:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "COLLECTION_ID",
  "collectionDisplayName": "COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "jira",
    "params": {
      "client_id": "{Client ID of your Jira integration}",
      "client_secret": "{Client Secret of your Jira integration}",
      "refresh_token": "{Refresh Token of your Jira integration}",
      "instance_id": "{Your Jira Cloud instance ID}"
    },
    "refreshInterval": "{ >1800 }s",
    "entities": [
      {
        "entityName" : "project",
        "params" : {
          "inclusion_filters" : {}
        }
      },
      {
        "entityName": "{attachment/comment/issue/worklog}" // Optional, you can build up to 4 different entities
      }
    ],
    "syncMode": "PERIODIC"
  }
}

    Substitua:

    • PROJECT_NUMBER: o número do seu projeto Google Cloud .
    • COLLECTION_ID: o ID da coleção.
    • COLLECTION_DISPLAY_NAME: um nome de exibição para a coleção.

  2. Inclua configurações de ação no conector do Jira:

    curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "PROJECT_NUMBER")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global/collections/COLLECTION_ID/dataConnector?update_mask=action_config" \
  -d '{
  "name": "projects/PROJECT_NUMBER/locations/global/collections/COLLECTION_ID/dataConnector",
  "action_config": {
    "is_action_configured": true,
    "action_params": {
        "client_id": "{Client id from Jira integration}",
        "client_secret": "{Client secret from Jira integration}",
        "instance_uri": "{instance URI of your Jira instance}"
      }
    }
  }'

  3. Ative as ações do Jira para seu assistente:

    curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "<var>PROJECT_NUMBER</var>")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant",
    "enabledActions": {
      "projects/PROJECT_NUMBER/locations/global/collections/CONNECTOR_ID/dataConnector": {
        "actionInfo": [
          {
            "actionName": "create_jira_issue",
            "actionDisplayName": "Create Jira Issue"
          }
        ]
      }
    }
  }'

    Substitua:

    • PROJECT_NUMBER: o número do seu projeto Google Cloud .

    • APP_ID: o ID do app.

    • CONNECTOR_ID: o ID da coleção do conector que você gerou na etapa anterior.

Depois de adicionar ações, o assistente pode realizá-las em nome dos usuários finais no app. Na primeira vez que um usuário pede ao assistente para realizar uma ação do Jira Cloud, ele precisa autorizar o acesso à conta da Atlassian.