Configuração do Confluence Cloud

Esta página descreve como configurar a sua instância do Confluence Cloud antes de criar o arquivo de dados do Confluence Cloud.

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

Tem de configurar a autenticação e as autorizações no centro de administração da conta da Atlassian. Isto é fundamental para permitir que o conetor aceda e sincronize dados. O conector do Confluence 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 Confluence

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

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

  2. Selecione a app Confluence.

  3. Clique em Definições.

    Se vir a opção Sistema em Definições do Confluence, tem acesso de administrador da organização do Confluence. Caso contrário, peça ao administrador da sua organização do Confluence 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 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/confluence_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.
    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 Confluence a função de editor do motor de descoberta na Google Cloud consola, faça o seguinte:

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

  2. Navegue para IAM.

    Aceda ao IAM

  3. Localize a conta de utilizador que tem acesso de administrador no Confluence 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.

  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.

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 Confluence.

  3. Selecione Administrador do produto como função para a administração do Confluence.

  4. Clique em Conceder acesso.

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

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

Para configurar o OAuth 2.0 e obter as credenciais necessárias para a configuração do conetor do Confluence, faça o seguinte:

  1. Ative o OAuth 2.0:
    1. Clique em Autorizações.
    2. Aceda à API Confluence.
    3. Clique em Adicionar.
    4. Clique em Configurar.
    5. Aceda ao separador Âmbitos detalhados e clique em Editar âmbitos.
    6. Selecione os seguintes âmbitos.
      • read:attachment:confluence
      • read:configuration:confluence
      • read:content.metadata:confluence
      • read:content-details:confluence
      • read:whiteboard:confluence
      • read:group:confluence
      • read:space:confluence
      • read:user:confluence
      • search:confluence
      • write:page:confluence
      • write:attachment:confluence
    7. Confirme que todos os âmbitos estão selecionados e guarde as alterações.

Configure um token de API no Confluence

Se planeia usar um token de API para autenticação, tem de criar um token de API sem âmbitos. Este conector não suporta tokens de API com âmbitos.

  1. Inicie sessão na Atlassian Console.
  2. Clique em Criar token de API.
  3. Introduza um nome para o token da API.
  4. Selecione uma data de validade para o token da API. O período de validade do token varia entre 1 e 365 dias.
  5. Clique em Criar.
  6. Guarde o token para utilização posterior.

Faça a gestão da visibilidade dos utilizadores

Para tornar o email do utilizador visível para qualquer pessoa na conta da Atlassian, siga estes passos:

  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.

  4. Navegue para Perfil e visibilidade.

  5. Aceda a Contacto e defina Quem pode ver isto como Qualquer pessoa.

Para tornar o email do utilizador visível a qualquer pessoa no Confluence, siga estes passos:

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

  2. Selecione uma app Confluence.

  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.

  7. Clique em Atualizar.

Instale e configure o User Identity Accessor para o Confluence Cloud

Se os endereços de email dos utilizadores não forem acessíveis publicamente por predefinição devido às definições de privacidade no Confluence Cloud, tem de instalar a app User Identity Accessor for Confluence Cloud para obter os endereços de email dos utilizadores de forma segura. Se os endereços de email dos utilizadores já forem visíveis publicamente, pode não precisar de instalar a app. Para mais informações sobre a visibilidade restrita de emails, consulte o artigo Faça a gestão da visibilidade dos utilizadores e atribua funções.

Funções e permissões

Para instalar e configurar a app User Identity Accessor for Confluence Cloud, tem de ter a função administrativa adequada e conceder as autorizações necessárias ao nível da app.

  • Função necessária: tem de ser Confluence Site administrator para instalar e configurar a app.
  • Autorizações ao nível da app: tem de conceder as seguintes autorizações durante a instalação da app:
    • Read Email Address: permite à app obter de forma segura os endereços de email dos utilizadores, mesmo quando a visibilidade do perfil está restrita.
    • App Storage scope: permite que a app leia e escreva no respetivo dispositivo de armazenamento.

Instale o User Identity Accessor para o Confluence Cloud

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

  1. Navegue para a Atlassian Developer Console.

  2. Reveja as autorizações Ler endereço de email e Âmbito de armazenamento da app e clique em Obter app.

  3. Na lista Selecione um site onde instalar esta app, selecione o site do Confluence onde quer instalar a app. Esta lista apresenta apenas os sites aos quais tem acesso de administrador.

    Nota: tem de ser administrador de, pelo menos, um site do Confluence para instalar a app.

  4. Clique em Instalar para concluir a instalação da app.

Configure o User Identity Accessor para o Confluence Cloud

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

Aceda à página de configuração

Para aceder à página de configuração da app User Identity Accessor for Confluence Cloud no Confluence Cloud, siga estes passos:

  1. Na sua instância do Confluence 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 Confluence 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 Confluence.

Configure a chave da API

Para configurar a chave da API na página de configuração, siga estes passos:

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

    • Introduza 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.

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

      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.

Teste a configuração da app

Verifique se o User Identity Accessor para a app Confluence Cloud está configurado 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 Confluence e desta instalação da app:
    • O seu sistema externo tem de chamar este URL para pedir os emails dos utilizadores. Por exemplo, https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, onde YOUR_INSTANCE_ID é o identificador da instância do Confluence Cloud e WEBTRIGGER_ID é o identificador exclusivo do ponto final do Webtrigger 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 Confluence com a chave da 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 Confluence 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 Confluence 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 os endereços de email dos 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 Confluence 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 os acionadores Web do User Identity Accessor for Confluence Cloud.

Apoio técnico do User Identity Accessor para o Confluence Cloud

As ofertas de apoio técnico estão disponíveis a partir de Google para a app User Identity Accessor for Confluence 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.