Adicione ações do Jira Cloud

Quando as ações do Jira estão ativadas, os utilizadores finais podem pedir ao assistente para realizar as seguintes ações do Jira Cloud:

  • Crie problemas do Jira
  • Edite problemas do Jira

Por exemplo, um utilizador pode introduzir "cria uma história do Jira denominada "Lançar projeto Y" no projeto ABC" ou "atualiza o título do pedido do Jira JCD-1 para "Lançar projeto Y"" na sua app. O assistente pede detalhes adicionais, se necessário, e, em seguida, pede ao utilizador para confirmar o pedido de criação ou edição.

O assistente pode ler e editar os seguintes campos do Jira através de 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.
Estado Estado do problema.
Descrição Descrição do problema no formato Markdown.
Componente Componente de emissão.
Atribuído a A pessoa responsável pelo problema, por exemplo, user@google.com.

Configure a autenticação e as autorizações no Jira

Antes de ativar as ações do Jira, um administrador do Jira tem de configurar credenciais do OAuth 2.0 dedicadas para ações no Jira. Isto é necessário para associar a sua integração do Jira e permitir autorização de leitura e escrita para ações.

Os clientes de autorização para ações do Jira são diferentes dos clientes para carregar dados do Jira. Usam autorizações diferentes e uma configuração de URL de retorno de chamada diferente. Para saber como configurar clientes de autorização para conetores do Jira Cloud para carregar dados, consulte o artigo Associe o Jira Cloud.

Estas instruções explicam como criar um ID do cliente e um segredo do cliente através da consola do programador da Atlassian, configurar os âmbitos do OAuth 2.0 necessários e configurar autorizações para os utilizadores. Por último, obtenha o URL e o ID da instância, configure funções e autentique-se para ler e escrever dados entre o Jira Cloud e o Google.

Crie o ID de cliente e o segredo do cliente

  1. Inicie sessão em developer.atlassian.com.
  2. Clique no ícone do perfil no canto superior direito e selecione Consola do programador.
  3. Clique em Criar e selecione Integração OAuth 2.0.
  4. Introduza um nome para a app.
    • Selecione a caixa de verificação dos Termos de Utilização.
    • 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 retorno de chamada, introduza https://vertexaisearch.cloud.google.com/oauth-redirect e, de seguida, clique em Guardar alterações.

  8. Clique em Autorizações:

    1. Aceda à API Jira, clique em Adicionar e, de seguida, em Configurar.

    2. Aceda ao separador Âmbitos clássicos e clique em Editar âmbitos. Selecione os seguintes âmbitos e, de seguida, guarde as alterações:

      • Âmbitos clássicos:

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

      • Âmbitos detalhados:

        • read:user:jira

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

    1. Selecione primeiro o botão de opção Partilha para ativar a edição de outros campos.
    2. Preencha os restantes campos.
      1. Para Fornecedor, selecione Google.
      2. Para a Política de Privacidade, introduza https://policies.google.com.
      3. Para A sua app armazena dados pessoais?, selecione Yes.
      4. Selecione a caixa de verificação Confirmo que implementei a API de relatórios de dados pessoais.
    3. Clique em Guardar alterações.

  10. Selecione Definições para copiar o ID de cliente e o segredo do cliente.

Obtenha o URL e o ID da instância

Para obter o URL da instância:

  1. Aceda a atlassian.net e inicie sessão com a sua conta de administrador.
  2. Selecione a app que quer sincronizar. Por exemplo, sincronize a primeira app.
  3. Encontre o URL da instância, que é o subdomínio na barra de endereço.

Para obter o ID da instância:

  1. Abra um novo separador, copie o URL da instância e anexe /_edge/tenant_info ao URL da instância. Por exemplo, https://YOUR-INSTANCE.atlassian.net/_edge/tenant_info.
  2. Navegue para o link para encontrar o valor cloudId. O cloudId é o seu ID da instância.

Configure autorizações e funções

  1. Inicie sessão em atlassian.com com a sua conta de administrador.
  2. Clique no ícone de menu na parte superior esquerda ou aceda a admin.atlassian.com.
  3. Na página Administração, clique em Gerir utilizadores e aceda à página Grupos.
  4. Clique em Criar grupo. Introduza um nome para o grupo e crie-o.
  5. Na secção Agrupar acesso a produtos da página do novo grupo, clique em Adicionar produtos ao grupo.
  6. Para o Jira, selecione Administrador de acesso do utilizador como função do produto.
  7. Para Administrador do Jira, selecione Administrador do produto como função do produto e guarde as alterações.
  8. Na página Grupos, clique em Adicionar membros do grupo e adicione utilizadores ou contas que o conector vai autenticar.

Obtenha um token de atualização

Se planear configurar ações do Jira através da Google Cloud consola, não precisa de obter um token de atualização.

Se precisar de usar a API para configurar as ações do Jira, é necessário um token de atualização. Para obter um token de atualização:

  1. Aceda à sua app na Google Cloud consola.
  2. Selecione Autorização.
  3. Selecione Configurar junto a OAuth 2.0 (3LO).
  4. Para o URL de redirecionamento, use um marcador de posição, como https://example.com.
  5. Para obter um token de atualização no fluxo de autorização inicial, adicione offline_access ao parâmetro de âmbito 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 de receber a autorização, é feito o redirecionamento de volta para o URL de redirecionamento. Na barra de endereço, deve ver um parâmetro de consulta denominado "code". Tome nota do respetivo valor.

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

    1. grant_type: authorization_code
    2. client_id: o seu ID de cliente
    3. client_secret: o segredo do cliente
    4. code: o código que recebeu no passo 6
    5. redirect_uri: o seu URI de redirecionamento

  8. Recebe o refresh_token na resposta

Para saber mais sobre os tokens de atualização, consulte o artigo Implementar o fluxo de tokens de atualização na documentação da Atlassian.

Configure uma ação do Jira

Esta secção descreve como criar um conector do Jira para ações e ativar as ações do Jira para o seu assistente.

Antes de começar

Antes de configurar as ações, certifique-se de que concluiu os seguintes passos:

  • O seu projeto tem de ser adicionado à lista de autorizações para ações do assistente
  • Um administrador do Jira concluiu os passos em Configure a autenticação e as autorizações no Jira e facultou-lhe as seguintes informações:
    • ID do cliente
    • Segredo do cliente
    • ID da instância
    • Símbolo de atualização. Obrigatório apenas para criar ações do Jira através da API em vez da consola Google Cloud . A Google recomenda que crie ações através da Google Cloud consola.

Configure ações do Jira na Google Cloud consola

A Google recomenda a criação de ações através da Google Cloud consola.

Para adicionar ações à sua app através da consola, faça o seguinte:

  1. Na Google Cloud consola, aceda à página do Gemini Enterprise.
  2. Aceda à app.
  3. No menu de navegação, clique em Ações.
  4. Para o Jira, clique em Associar.
  5. Selecione uma instância do Jira.
  6. Se lhe for pedido, introduza as informações de autorização do conector. Isto só é necessário se a instância ainda não tiver sido configurada para uma ação.
  7. Selecione as ações a ativar.
  8. Clique em Concluir configuração. A sua ação é apresentada na página Ações.

Crie e ative ações do Jira através da API

A Google recomenda que crie ações através da Google Cloud consola. Se precisar de criar ações através da API, faça o seguinte:

  1. Crie um conetor do Jira e configure-o para a 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 o seguinte:

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

  2. Inclua configurações de ações 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 o 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 o seguinte:

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

    • APP_ID: o ID da app.

    • CONNECTOR_ID: o ID de recolha do conector que gerou no passo anterior.

Depois de adicionar ações, o assistente pode realizar essas ações em nome dos seus utilizadores finais na app. Da primeira vez que um utilizador pedir ao assistente para realizar uma ação do Jira Cloud, é-lhe pedido que autorize o acesso à respetiva conta da Atlassian.