Connettersi a Confluence per utilizzare la knowledge base - Amazon Bedrock
Funzionalità supportatePrerequisitiConfigurazione della connessione

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Connettersi a Confluence per utilizzare la knowledge base

Atlassian Confluence è uno strumento collaborativo di gestione del lavoro progettato per condividere, archiviare e lavorare sulla pianificazione dei progetti, sullo sviluppo del software e sulla gestione dei prodotti. Per connetterti all’istanza di Confluence corrente per Knowledge Base per Amazon Bedrock, utilizza la Console di gestione AWS per Amazon Bedrock oppure l’API CreateDataSource API (consulta gli SDK supportati e la AWS CLI di Amazon Bedrock).

Nota

Il connettore dell’origine dati in Confluence è disponibile nella versione di anteprima ed è soggetto a modifiche.

Le origini dati Confluence non supportano dati multimodali, come tabelle, grafici, diagrammi o altre immagini.

Amazon Bedrock supporta la connessione a istanze di Confluence Cloud. Attualmente, solo l’archivio vettoriale Amazon OpenSearch serverless è disponibile per l’utilizzo con questa origine dati.

Il numero di file e le dimensioni in MB dei file che possono essere sottoposti a crawling sono limitati. Consulta Quote per le knowledge base.

Funzionalità supportate

  • Rilevamento automatico dei campi principali dei documenti

  • Filtri per inclusione/esclusione del contenuto

  • Sincronizzazione incrementale dei contenuti per aggiunte, aggiornamenti ed eliminazioni

  • Autenticazione OAuth 2.0 e autenticazione con token API Confluence

Prerequisiti

In Confluence, assicurati di:

  • Prendere nota dell’URL dell’istanza di Confluence, ad esempio https://example.atlassian.net per Confluence Cloud. L’URL per Confluence Cloud deve essere quello di base, che termina con .atlassian.net.

  • Configurare le credenziali di autenticazione di base contenenti un nome utente (indirizzo e-mail dell’account amministratore) e una password (token API Confluence) per consentire ad Amazon Bedrock di connettersi all’istanza di Confluence Cloud corrente. Per informazioni sulla creazione di un token API Confluence, consulta Manage API tokens for your Atlassian account sul sito web di Atlassian.

  • (Facoltativo) Configurare un’applicazione OAuth 2.0 con le credenziali di una chiave e di un segreto dell’app, di un token di accesso e di uno di aggiornamento. Per ulteriori informazioni, consulta OAuth 2.0 apps sul sito web di Atlassian.

  • Abilitare determinati ambiti o autorizzazioni di lettura per consentire all’app OAuth 2.0 di connettersi a Confluence.

    API Confluence:

    • offline_access

    • read:content:confluence: consente di visualizzare i contenuti dettagliati

    • read:content-details:confluence: consente di visualizzare i dettagli del contenuto

    • read:space-details:confluence: consente di visualizzare i dettagli dello spazio

    • read:audit-log:confluence: consente di visualizzare i record di audit

    • read:page:confluence: consente di visualizzare le pagine

    • read:attachment:confluence: consente di visualizzare e di scaricare gli allegati al contenuto

    • read:blogpost:confluence: consente di visualizzare i post di blog

    • read:custom-content:confluence: consente di visualizzare contenuto personalizzato

    • read:comment:confluence: consente di visualizzare i commenti

    • read:template:confluence: consente di visualizzare i modelli di contenuto

    • read:label:confluence: consente di visualizzare le etichette

    • read:watcher:confluence: consente di visualizzare gli osservatori del contenuto

    • read:relation:confluence: consente di visualizzare le relazioni tra entità

    • read:user:confluence: consente di visualizzare i dettagli dell’utente

    • read:configuration:confluence: consente di visualizzare le impostazioni di Confluence

    • read:space:confluence: consente di visualizzare i dettagli dello spazio

    • read:space.property:confluence: consente di visualizzare le proprietà dello spazio

    • read:user.property:confluence: consente di visualizzare le proprietà dell’utente

    • read:space.setting:confluence: consente di visualizzare le impostazioni dello spazio

    • read:analytics.content:confluence: consente di visualizzare l’analisi del contenuto

    • read:content.property:confluence: consente di visualizzare le proprietà del contenuto

    • read:content.metadata:confluence: consente di visualizzare i riepiloghi del contenuto

    • read:inlinetask:confluence: consente di visualizzare le attività

    • read:task:confluence: consente di visualizzare le attività

    • read:whiteboard:confluence: consente di visualizzare le lavagne

    • read:app-data:confluence: consente di leggere i dati dell’app

    • read:folder:confluence: consente di visualizzare le cartelle

    • read:embed:confluence: consente di visualizzare i dati Smartlink

Nell’account AWS, assicurati di:

  • Archiviare le credenziali di autenticazione in un segreto di Gestione dei segreti AWS e di prendere nota del nome della risorsa Amazon (ARN) del segreto stesso. Seguire le istruzioni nella sezione Configurazione della connessione in questa pagina per includere le coppie chiave-valore da inserire nel segreto.

  • Includere le autorizzazioni necessarie per la connessione all’origine dati nella policy di ruolo/autorizzazioni di AWS Identity and Access Management (IAM) per la knowledge base corrente. Per informazioni sulle autorizzazioni necessarie per aggiungere l’origine dati al ruolo IAM della knowledge base, consulta Autorizzazioni per accedere alle origini dati.

Nota

Se si utilizza la console, è possibile andare in Gestione dei segreti AWS per aggiungere il segreto oppure utilizzare un segreto esistente nell’ambito della fase di configurazione dell’origine dati. Il ruolo IAM e tutte le autorizzazioni richieste possono essere creati automaticamente durante le fasi di creazione di una knowledge base nella console. Dopo la configurazione dell’origine dati e delle altre impostazioni, il ruolo IAM e tutte le autorizzazioni vengono applicati alla knowledge base specifica.

Sarebbe opportuno aggiornare o ruotare regolarmente le credenziali e il segreto e fornire solo il livello di accesso necessario per motivi di sicurezza. Il riutilizzo di credenziali e segreti tra origini dati diverse non è consigliato.

Configurazione della connessione

Per connettersi all’istanza di Confluence corrente, è necessario fornire le informazioni di configurazione richieste per consentire ad Amazon Bedrock di accedere ai dati e di sottoporli a crawling, nonché rispettare le indicazioni presenti nella sezione Prerequisiti.

Un esempio di configurazione per l’origine dati è incluso in questa sezione.

Per ulteriori informazioni sul rilevamento automatico dei campi del documento, sui filtri di inclusione/esclusione, sulla sincronizzazione incrementale, sulle credenziali di autenticazione segrete e sul relativo funzionamento, consulta le sezioni seguenti:

Il connettore dell’origine dati rileva automaticamente tutti i campi di metadati principali dei documenti o dei contenuti e li sottopone a crawling. Ad esempio, il connettore dell’origine dati può sottoporre a crawling l’equivalente del corpo del documento, il titolo del documento, la data di creazione o di modifica del documento o altri campi principali che potrebbero essere applicati ai documenti.

Importante

Se i contenuti includono informazioni sensibili, Amazon Bedrock potrebbe rispondere utilizzando informazioni di questo tipo.

Per migliorare ulteriormente la pertinenza delle risposte, è possibile applicare operatori di filtro ai campi di metadati, ad esempio “epoch_modification_time” del documento oppure il numero di secondi trascorsi dal 1° gennaio 1970, data dell’ultimo aggiornamento del documento. È possibile filtrare in base ai dati più recenti, in cui “epoch_modification_time” è maggiore di un determinato numero. Per ulteriori informazioni sugli operatori di filtro che è possibile applicare ai campi di metadati, consulta Metadati e filtri.

È possibile includere o escludere il crawling di determinati contenuti, specificando ad esempio un prefisso di esclusione o un modello di espressione regolare per ignorare il crawling dei file che contengono il termine “privato” nel nome. È anche possibile specificare un prefisso di inclusione oppure un modello di espressione regolare per includere determinate entità o tipi di contenuto. Se si specifica un filtro di inclusione ed esclusione ed entrambi corrispondono a un documento, il filtro di esclusione ha la precedenza e il documento non viene sottoposto a crawling.

Un esempio di modello di espressione regolare per escludere o filtrare i file PDF che contengono “privato” nel nome è il seguente: “.*privato.*\\.pdf”.

I filtri di inclusione/esclusione possono essere applicati ai seguenti tipi di contenuto:

  • Space: chiave dello spazio univoca

  • Page: titolo principale della pagina

  • Blog: titolo principale del blog

  • Comment: commenti che appartengono a una pagina oppure a un blog specifico. Specificare Re: Titolo pagina/blog

  • Attachment: nome del file allegato con relativa estensione

Il connettore delle origini dati sottopone a crawling il contenuto nuovo, modificato ed eliminato ogni volta che l’origine dati si sincronizza con la knowledge base. Amazon Bedrock può utilizzare il meccanismo dell’origine dati per tenere traccia delle modifiche al contenuto e sottoporre a crawling il contenuto modificato dall’ultima sincronizzazione. Quando sincronizzi per la prima volta l’origine dati con la knowledge base, per impostazione predefinita tutti i contenuti vengono sottoposti a crawling.

Per sincronizzare l’origine dati con la knowledge base, utilizzare l’API StartIngestionJob o selezionare la knowledge base nella console, quindi scegliere Sincronizza nella sezione di panoramica della console.

Importante

Tutti i dati sincronizzati dall’origine dati diventano disponibili per chiunque disponga delle autorizzazioni bedrock:Retrieve per recuperarli. Ciò può includere anche tutti i dati con autorizzazioni per l’origine dati controllate. Per ulteriori informazioni, consulta Autorizzazioni della knowledge base.

(Se si utilizza l’autenticazione di base) Le credenziali di autenticazione segrete in Gestione dei segreti AWS devono includere queste coppie chiave-valore:

  • username: indirizzo e-mail dell’utente amministratore dell’account Atlassian

  • password: token API Confluence

(Se si utilizza l’autenticazione OAuth 2.0) Le credenziali di autenticazione segrete in Gestione dei segreti AWS devono includere queste coppie chiave-valore:

  • confluenceAppKey: chiave dell’app

  • confluenceAppSecret: segreto dell’app

  • confluenceAccessToken: token di accesso all’app

  • confluenceRefreshToken: token di aggiornamento dell’app

Nota

Il token di accesso OAuth2.0 per Confluence ha una scadenza predefinita di 60 minuti. Se il token di accesso scade durante la sincronizzazione dell’origine dati (processo di sincronizzazione), Amazon Bedrock utilizza il token di aggiornamento fornito per rigenerarlo. In questo caso vengono rigenerati sia i token di accesso sia quelli di aggiornamento. Per mantenere i token aggiornati dal processo di sincronizzazione corrente a quello successivo, Amazon Bedrock richiede le autorizzazioni di scrittura/immissione per le credenziali segrete nell’ambito del ruolo IAM della knowledge base.

Nota

Il segreto in Gestione dei segreti AWS deve utilizzare la stessa Regione della knowledge base.

Console
Connettere un’istanza di Confluence alla knowledge base

  1. Segui i passaggi indicati in Creazione di una knowledge base mediante connessione a un’origine dati in Knowledge Base per Amazon Bedrock e scegli Confluence come origine dati.

  2. Specifica un nome e una descrizione facoltativa per l’origine dati.

  3. Indica l’URL dell’istanza di Confluence corrente, ad esempio https://example.atlassian.net per Confluence Cloud. L’URL per Confluence Cloud deve essere quello di base, che termina con .atlassian.net.

  4. Nella sezione Impostazioni avanzate, puoi configurare gli elementi seguenti (facoltativo):

    • Chiave KMS per l’archiviazione di dati transitori: è possibile crittografare i dati transitori durante la conversione in embedding con la Chiave gestita da AWS predefinita o con la chiave KMS in uso. Per ulteriori informazioni, consulta Crittografia dell'archiviazione di dati transitoria durante l'importazione dei dati.

    • Policy di eliminazione dei dati: è possibile eliminare gli embedding vettoriali per l’origine dati corrente presenti nell’archivio vettoriale per impostazione predefinita oppure scegliere di mantenere i dati dell’archivio vettoriale.

  5. Fornisci le informazioni di autenticazione per connetterti all’istanza di Confluence corrente:

    • Per l’autenticazione di base, vai in Gestione dei segreti AWS per aggiungere le credenziali di autenticazione segrete oppure usa un nome della risorsa Amazon (ARN) esistente per il segreto creato. Il segreto deve contenere l’indirizzo e-mail dell’utente amministratore dell’account Atlassian come nome utente e un token API Confluence come password. Per informazioni sulla creazione di un token API Confluence, consulta Manage API tokens for your Atlassian account sul sito web di Atlassian.

    • Per l’autenticazione OAuth 2.0, vai in Gestione dei segreti AWS per aggiungere le credenziali di autenticazione segrete oppure usa un nome della risorsa Amazon (ARN) esistente per il segreto creato. Il segreto deve contenere la chiave dell’app Confluence, il segreto dell’app, il token di accesso e quello di aggiornamento. Per ulteriori informazioni, consulta OAuth 2.0 apps sul sito web di Atlassian.

  6. (Facoltativo) Nella sezione Chunking e analisi dei contenuti, puoi personalizzare il modo in cui analizzare i dati ed eseguirne il chunking. Per ulteriori informazioni su queste personalizzazioni, consulta le risorse seguenti:

  7. Scegli di utilizzare filtri o modelli di espressione regolare per includere o escludere determinati contenuti. Altrimenti, tutto il contenuto standard viene sottoposto a crawling.

  8. Continua a scegliere un modello di embedding e un archivio vettoriale. Per visualizzare le fasi rimanenti, torna a Creazione di una knowledge base mediante connessione a un’origine dati in Knowledge Base per Amazon Bedrock e continua dalla fase successiva alla connessione all’origine dati.

API

Di seguito è riportato un esempio di configurazione per la connessione a Confluence Cloud per Knowledge Base per Amazon Bedrock. Per configurare l’origine dati, utilizza l’API con la AWS CLI o con il componente SDK supportato, ad esempio Python. Dopo aver chiamato CreateKnowledgeBase, chiama CreateDataSource per creare l’origine dati con le informazioni di connessione in dataSourceConfiguration.

Per informazioni sulle personalizzazioni che è possibile applicare all’importazione includendo il campo vectorIngestionConfiguration opzionale, consulta Personalizzare l’importazione per un’origine dati.

AWS Command Line Interface

aws bedrock create-data-source \
 --name "Confluence Cloud/SaaS connector" \
 --description "Confluence Cloud/SaaS data source connector for Amazon Bedrock to use content in Confluence" \
 --knowledge-base-id "your-knowledge-base-id" \
 --data-source-configuration file://confluence-bedrock-connector-configuration.json \
 --data-deletion-policy "DELETE" \
 --vector-ingestion-configuration '{"chunkingConfiguration":[{"chunkingStrategy":"FIXED_SIZE","fixedSizeChunkingConfiguration":[{"maxTokens":"100","overlapPercentage":"10"}]}]}'

confluence-bedrock-connector-configuration.json
{
    "confluenceConfiguration": {
        "sourceConfiguration": {
            "hostUrl": "https://example.atlassian.net",
            "hostType": "SAAS",
            "authType": "OAUTH2_CLIENT_CREDENTIALS",
            "credentialsSecretArn": "arn:aws::secretsmanager:your-region:secret:AmazonBedrock-Confluence"
        },
        "crawlerConfiguration": {
            "filterConfiguration": {
                "type": "PATTERN",
                "patternObjectFilter": {
                    "filters": [
                        {
                            "objectType": "Attachment",
                            "inclusionFilters": [
                                ".*\\.pdf"
                            ],
                            "exclusionFilters": [
                                ".*private.*\\.pdf"
                            ]
                        }
                    ]
                }
            }
        }
    },
    "type": "CONFLUENCE"
}