Configuração do Jira Cloud

Pré-visualização pública: as funcionalidades de pesquisa e ações federadas estão em pré-visualização pública. Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Esta página descreve como configurar uma configuração de terceiros antes de criar o arquivo de dados do Jira Cloud.

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

Tem de configurar a autenticação e as autorizações no centro da conta de administrador da Atlassian. Isto é fundamental para permitir que o conetor aceda e sincronize dados. O conetor do Jira Cloud suporta vários métodos de autenticação, como credenciais de cliente OAuth ou tokens de API.

Crie uma app OAuth 2.0

Para criar uma app OAuth 2.0 para autenticação, siga estes passos para configurar a aplicação na Atlassian Developer Console e obter o ID de cliente e o segredo do cliente necessários.

Valide o acesso de administrador da organização do Jira

Para validar o acesso de administrador da organização do Jira, faça o seguinte:

1. Inicie sessão no Atlassian com as suas credenciais de utilizador.

2. Selecione a app Jira.

3. Clique em Definições.

   Se vir a opção Sistema em Definições do Jira, tem acesso de administrador da organização do Jira. Caso contrário, peça ao administrador da sua organização Jira para lhe conceder acesso.

Crie uma app OAuth 2.0

Para criar uma app OAuth 2.0, faça o seguinte:

1. Inicie sessão na Atlassian Developer Console.

2. Clique no ícone do perfil e selecione Consola do programador.

3. Na página Console, clique em Criar e selecione Integração do OAuth 2.0.

4. Na página de criação da app, faça o seguinte:

   1. Introduza um nome para a app.

   2. Selecione a caixa de verificação para aceitar os termos do programador da Atlassian.

   3. Clique em Criar.

5. Na página da app, faça o seguinte:

   1. No menu de navegação, clique em Autorização.

   2. Na tabela Tipo de autorização, selecione Adicionar para OAuth 2.0 (3LO).

6. No campo URL de retorno, introduza https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html.

7. Clique em Guardar alterações.

Obtenha o ID de cliente e o segredo do cliente

Para obter o ID de cliente e o segredo do cliente, faça o seguinte:

1. Na página da app, no menu de navegação, clique em Distribuição.

2. Na página Distribuição, faça o seguinte:

   1. Na secção Controlos de distribuição, selecione Editar.
   2. Na secção Estado da distribuição, selecione Partilhar para ativar a edição de outros campos.
   3. Introduza informações nos seguintes campos obrigatórios:
      1. Em Fornecedor, introduza Google.
      2. Para a Política de Privacidade, introduza https://policies.google.com.
      3. Para A sua app armazena dados pessoais?, selecione Sim.
      4. Selecione a caixa de verificação Confirmo que implementei a API de relatórios de dados pessoais. Para mais informações, consulte o artigo API de relatórios de dados pessoais.
   4. Clique em Guardar alterações.

3. Na página da app, faça o seguinte:

   1. No menu de navegação, clique em Definições.
   2. Na página de definições, copie o ID de cliente e o segredo do cliente.

Obtenha um ID da instância e um URL da instância

1. Obtenha 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 ID da instância.

2. Obtenha 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 (o subdomínio na barra de endereço).

Conceda funções de administrador

Para conceder ao administrador do Jira a função de editor do Discovery Engine na Google Cloud consola, faça o seguinte:

1. Na Google Cloud consola, aceda à página Gemini Enterprise.

2. Navegue para IAM.

   Aceder ao IAM

3. Localize a conta de utilizador que tem acesso de administrador no Jira e clique no ícone Editar .

4. Conceda a função de editor do motor de descoberta ao administrador.

Para conceder a um utilizador uma função de administrador no Atlassian, faça o seguinte:

1. Inicie sessão no Atlassian com uma conta de administrador da organização.

2. Clique no ícone de menu e selecione a sua organização. Em alternativa, pode aceder a admin.atlassian.com.

3. Na página Administração, clique no produto e selecione o botão Gerir utilizadores.

   

   Faça a gestão dos utilizadores

4. Clique em Grupos em Gestão de utilizadores.

5. Na página Grupos:

   1. Clique em Criar grupo.
   2. Introduza um nome para o grupo.

   

   Criar grupo

Este grupo recebe as autorizações necessárias para o conector. Os utilizadores adicionados a este grupo herdam estas autorizações. O conetor usa este grupo para fazer a autenticação e obter documentos.

1. Na página do grupo, clique em Adicionar produto.

2. Selecione Administrador de acesso do utilizador como função para o Jira.

3. Selecione Administrador do produto como função para a Administração do Jira.

   

   Administrador de acesso de utilizadores do Jira

4. Clique em Conceder acesso.

5. Clique em Adicionar membros do grupo para adicionar uma conta de utilizador ou membros do grupo que o conetor usa para autenticar e aceder aos recursos necessários.

   

   Adicione membros do grupo

Faça a gestão da visibilidade do utilizador

Para tornar o email do utilizador visível para qualquer pessoa na conta da Atlassian, faça o seguinte:

1. Inicie sessão na Atlassian Developer Console.

2. Clique no ícone do perfil e selecione Consola do programador.

3. Clique no ícone do perfil do utilizador e selecione Gerir conta.

   

   Gerir conta

4. Navegue para Perfil e visibilidade.

   

   Perfil e visibilidade

5. Aceda a Contacto e defina a opção Quem pode ver isto como Qualquer pessoa.

   

   Contactar

Para tornar o email do utilizador visível a qualquer pessoa no Jira, faça o seguinte:

1. Inicie sessão no Atlassian com as suas credenciais de utilizador.

2. Selecione uma app Jira.

3. Clique em Definições > Sistema.

4. Selecione Configuração geral no painel do lado esquerdo.

5. Clique em Editar definições.

6. Em Visibilidade do email do utilizador, selecione Público.

   

   Selecione a visibilidade do email

7. Clique em Atualizar.

Configure os âmbitos mínimos da aplicação

Para realizar as ações definidas, tem de configurar as seguintes autorizações para o conetor do Jira Cloud na plataforma Atlassian.

1. Na página da aplicação, clique em Autorizações.

2. Aceda à API Jira e clique em Adicionar.

   Nota: depois de adicionar a API Jira, o botão Configurar pode demorar um momento a aparecer. Se não aparecer imediatamente, experimente atualizar a página ou aguardar alguns segundos.

3. Clique em Configurar.

4. Aceda ao separador Âmbitos clássicos.

5. Clique em Editar âmbitos e selecione os âmbitos clássicos de acordo com o seu requisito na tabela seguinte:

   Modo de ligação	Autorização	Finalidade
   Pesquisa e ações federadas	read:jira-user, read:jira-work	Necessário para obter e apresentar resultados da pesquisa e detalhes do utilizador em tempo real.
   	write:jira-work	Permite que o assistente modifique itens de trabalho (por exemplo, atualizando campos de problemas) e faça a gestão de comentários ou problemas.
   Apenas pesquisa federada	read:jira-user, read:jira-work	Necessário para pesquisar e ver problemas, projetos e perfis de utilizadores.
   Carregamento e ações de dados	read:jira-work	Necessário para a indexação e a obtenção de dados abrangentes de itens de trabalho.
   	write:jira-work	Necessário para realizar ações de escrita (criação, atualizações, comentários) em itens de trabalho no ambiente carregado.
   Carregamento de dados	read:jira-work	Necessário para rastrear e indexar conteúdo do Jira para disponibilidade de pesquisa.

6. Confirme que todos os âmbitos estão selecionados e clique em Guardar.

7. Aceda ao separador Âmbitos detalhados.

8. Clique em Editar âmbitos e selecione os âmbitos detalhados de acordo com o seu requisito na tabela seguinte:

   Modo de ligação	Autorização	Finalidade
   Pesquisa e ações federadas	write:comment:jira	Permite que o assistente publique novos comentários ou respostas diretamente a partir da interface de pesquisa.
   	write:issue:jira	Necessário para criar novos problemas ou fazer edições importantes aos existentes.
   Carregamento e ações de dados	read:user:jira, read:group:jira, read:avatar:jira	Necessário para sincronizar metadados de utilizadores/grupos e apresentar perfis de utilizadores.
   	read:issue-security-level:jira, read:issue-security-scheme:jira	Essencial para o controlo de acesso; garante que os dados carregados respeitam os limites de segurança do Jira.
   	read:audit-log:jira	Usado para acompanhar as alterações e fazer sincronizações incrementais para manter os dados carregados atualizados.
   	write:comment:jira	Necessário para adicionar comentários a problemas através do assistente.
   	write:issue:jira	Permite criar ou modificar problemas.
   Carregamento de dados	read:user:jira, read:group:jira, read:avatar:jira	Necessário para rastrear e indexar o conteúdo do Jira e as relações entre utilizadores.
   	read:issue-security-level:jira, read:issue-security-scheme:jira	Necessário para mapear autorizações, para que apenas os utilizadores autorizados possam pesquisar os dados carregados.
   	read:audit-log:jira	Necessário para o motor de sincronização identificar os itens que foram atualizados ou eliminados.

9. Confirme que todos os âmbitos estão selecionados e clique em Guardar.

Nota: se quiser ignorar as ações e usar o arquivo de dados para a pesquisa, pode limitar as autorizações apenas às autorizações read. As autorizações write são necessárias apenas para realizar as ações mencionadas em Ações suportadas.

Instale o User Identity Accessor

Para instalar a app User Identity Accessor for Jira Cloud no seu site do Jira Cloud, siga estes passos:

1. Navegue para o Atlassian Marketplace.

2. Clique em Obter agora.

   

   Obter já

3. Na lista Selecionar um site, selecione o site do Jira onde quer instalar a app.

   Nota: tem de ter privilégios de administrador para o site do Jira selecionado para instalar a app.

4. Clique em Rever para autorizar as autorizações necessárias e aceitar os Termos de Utilização.

5. Clique em Obter agora para concluir a instalação da app.

   Após a instalação bem-sucedida, é apresentada uma mensagem de confirmação: "A sua app foi adicionada à instância e está pronta a ser usada."

Configure o acessor de identidade do utilizador

Depois de instalar a app User Identity Accessor for Jira Cloud, configure uma chave de API que o seu sistema externo (por exemplo, o Jira Cloud Connector) usa para chamar o acionador Web da app de forma segura para obter emails.

Aceda à página de configuração

Para aceder à página de configuração da app User Identity Accessor for Jira Cloud, faça o seguinte:

1. Na instância do Jira Cloud, clique no ícone Definições ⚙️ no menu de navegação.
2. Selecione Apps no menu.
3. Na página Administração de apps, localize a sua app, User Identity Accessor for Jira Cloud, na lista Gerir apps.

4. Clique em Configurar ou no link associado à sua app. A página de configuração dedicada da app é aberta no Jira Cloud.

   

   Configure o User Identity Accessor para a app Jira Cloud

Configure a chave da API

Para configurar a chave da API na página de configuração, faça o seguinte:

1. Na secção Configuração da chave da API, especifique a chave secreta para autenticar pedidos ao acionador Web da app. Pode autenticar pedidos através de um dos seguintes métodos:

   • Introduzir a sua própria chave: escreva ou cole a sua própria chave da API forte e única no campo Chave da API. Use uma chave de, pelo menos, 20 a 30 carateres com uma combinação de letras maiúsculas, letras minúsculas, números e símbolos.

     

     Introduza a sua própria chave

   • Gerar uma chave: clique no botão Gerar nova chave. O sistema gera e apresenta uma chave forte e aleatória no campo.

     

     Gere uma chave

     Importante: copie imediatamente a chave da API apresentada no campo. Por motivos de segurança, pode não conseguir ver novamente a chave completa depois de a guardar ou sair da página. Se o perder, tem de definir ou gerar um novo.

2. Clique em Guardar chave da API. É apresentada uma mensagem de êxito a confirmar que a chave foi guardada em segurança.

Nota: a chave da API gerada ou criada nesta secção serve como valor para o campo Jira Identity Sync Forge Client Secret na secção Opções avançadas durante a configuração do conector.

Teste a configuração da app

Verifique se a app User Identity Accessor for Jira Cloud está configurada corretamente enviando um pedido do seu sistema externo e confirmando que os endereços de email dos utilizadores são devolvidos com êxito.

Obtenha o URL do acionador Web

1. Na página Administração de apps, localize a secção URL do Webtrigger, que apresenta o URL exclusivo específico do seu site do Jira e desta instalação da app:
   • O seu sistema externo tem de chamar este URL para pedir os emails dos utilizadores.
   • Exemplo de URL: https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, em que YOUR_INSTANCE_ID é o identificador da sua instância do Jira Cloud e WEBTRIGGER_ID é o identificador exclusivo do ponto final do acionador Web gerado para a sua app.
2. Clique no botão Copiar URL ou copie o URL completo.

Configure o seu sistema externo

• Configure o seu sistema externo que precisa de obter emails de utilizadores do Jira com a chave de API e o URL do acionador Web obtidos nos passos anteriores.

• URL do ponto final: o URL do acionador Web que copiou.

• Método de HTTP: POST

• Cabeçalhos obrigatórios:

  • Content-Type: application/json

  • X-Api-Key: YOUR_API_KEY

    Substitua YOUR_API_KEY pela chave da API que definiu ou gerou na secção Configure a chave da API.

Comando curl de exemplo

Este exemplo demonstra a chamada do acionador Web User Identity Accessor for Jira Cloud, que aceita uma matriz de IDs de contas e devolve os endereços de email.

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

Substituição:

• YOUR_INSTANCE_ID com o ID da instância do Jira Cloud
• ENDPOINT_PATH com o caminho do ponto final da API
• YOUR_API_KEY com a chave da API que definiu ou gerou na secção Configure a chave da API
• ACCOUNT_ID com os IDs das contas da Atlassian que quer segmentar

Resposta esperada

[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

Substituição:

• ACCOUNT_ID_X com IDs de contas da Atlassian reais
• USER_EMAIL_X com endereços de email de utilizadores devolvidos pela chamada API

Implemente práticas recomendadas de segurança

Para confirmar a segurança da sua chave da API, siga estas recomendações:

• Armazene a chave da API de forma segura na configuração do Jira Cloud Connector.
• Certifique-se de que toda a comunicação com o URL do webhook ocorre através de HTTPS. Esta é a predefinição para acionadores Web do User Identity Accessor for Jira Cloud.

Apoio técnico para o User Identity Accessor para o Jira Cloud

As ofertas de apoio técnico estão disponíveis a partir de Google para a app User Identity Accessor for Jira Cloud, que pode incluir manutenção e atualizações regulares para manter a app atualizada. Se tiver problemas ou perguntas específicas sobre a funcionalidade da app, contacte o Google Cloud apoio técnico. Para mais informações, consulte o artigo Obter apoio técnico ao cliente do Google Cloud.