Condividi tramite

Connettori Di Microsoft Graph PostgreSQL (anteprima)

  • Articolo

Il connettore PostgreSQL Microsoft Graph consente all'organizzazione di indicizzare i record da un database PostgreSQL. Dopo aver configurato il connettore, gli utenti finali possono cercare questi record da PostgreSQL in Microsoft Copilot e da qualsiasi client di Microsoft Search.

Questo articolo è destinato agli amministratori di Microsoft 365 o a tutti coloro che configurano, eseguono e monitorano un connettore PostgreSQL Graph.

Nota

Il connettore PostgreSQL è in anteprima. Se si vuole ottenere l'accesso per provarlo, è necessario abilitare l'anello rilascio mirato per l'account Amministrazione.

Funzionalità

  • Indicizzare i record dal database PostgreSQL usando una query SQL.
  • Specificare le autorizzazioni di accesso per ogni record con l'elenco di utenti o gruppi aggiunti nella query SQL.
  • Abilitare gli utenti finali per porre domande relative ai record indicizzati in Copilot.
  • Usare la ricerca semantica in Copilot per consentire agli utenti di trovare contenuti pertinenti in base a parole chiave, preferenze personali e connessioni di social networking.

Limitazioni

  • Versioni di PostgreSQL supportate: il connettore supporta PostgreSQL versione 14 o successiva.
  • Per supportare una velocità di ricerca per indicizzazione elevata e prestazioni migliori, il connettore è progettato per supportare solo carichi di lavoro OLTP (Online Transaction Processing). Carichi di lavoro OLAP (Online Analytical Processing) che non eseguono la query SQL fornita in un timeout di 40 secondi e non sono supportati.
  • Gli elenchi di controllo di accesso sono supportati solo tramite un nome dell'entità utente (UPN), Microsoft Entra ID o sicurezza di Active Directory.
  • L'indicizzazione di contenuto avanzato all'interno di colonne di database non è supportata. Esempi di tali contenuti sono HTML, JSON, XML, BLOB e analisi di documenti esistenti come collegamenti all'interno delle colonne del database.

Prerequisiti

  • È necessario essere l'amministratore della ricerca per il tenant di Microsoft 365 dell'organizzazione.
  • Installare l'agente connettore Microsoft Graph: per accedere al server PostgreSQL, è necessario installare e configurare l'agente del connettore. Per altre informazioni, vedere Installare l'agente connettore Microsoft Graph .
  • Indirizzo del server PostgreSQL: per connettersi ai dati PostgreSQL, è necessario l'indirizzo del server PostgreSQL dell'organizzazione.
  • Account del servizio: per connettersi al server PostgreSQL e consentire a Microsoft Graph Connector di aggiornare regolarmente i record, è necessario un account del servizio con autorizzazioni di lettura concesse all'account del servizio.

Introduzione all'installazione

1. Nome visualizzato

Un nome visualizzato viene usato per identificare ogni citazione in Copilot, consentendo agli utenti di riconoscere facilmente il file o l'elemento associato. Il nome visualizzato indica anche contenuto attendibile. Il nome visualizzato viene usato anche come filtro dell'origine di contenuto. Per questo campo è presente un valore predefinito, ma è possibile personalizzarlo in base a un nome riconosciuto agli utenti dell'organizzazione.

2. Server PostgreSQL

Per connettersi ai dati PostgreSQL, sono necessari l'indirizzo del server PostgreSQL, la porta e il nome del database.

3. Tipo di autenticazione

Il connettore PostgreSQL supporta solo l'autenticazione basata su password per connettersi al database.

4. Distribuire a un pubblico limitato

Distribuire questa connessione a una base di utenti limitata se si vuole convalidarla in Copilot e in altre aree di ricerca prima di espandere l'implementazione a un pubblico più ampio. Per altre informazioni sull'implementazione limitata, fare clic qui.

Contenuto

Per eseguire ricerche nel contenuto del database, è necessario specificare query SQL quando si configura il connettore. Queste query SQL devono denominare tutte le colonne di database da indicizzare (proprietà di origine). Sono inclusi tutti i join SQL che devono essere eseguiti per ottenere tutte le colonne. Per limitare l'accesso ai risultati della ricerca, è necessario specificare Controllo di accesso Elenchi (ACL) nelle query SQL quando si configura il connettore.

1. Ricerca per indicizzazione completa (obbligatorio)

a. Selezionare colonne di dati (obbligatorio) e colonne ACL (facoltativo)

[Fare clic per espandere] Selezione delle colonne di dati per la query di ricerca per indicizzazione completa.

In questo passaggio viene configurata la query SQL che esegue una ricerca per indicizzazione completa del database. La ricerca per indicizzazione completa seleziona tutte le colonne o le proprietà che devono essere presentate in Microsoft Copilot o Ricerca. È anche possibile specificare colonne ACL per limitare l'accesso dei risultati della ricerca a utenti o gruppi specifici.

Consiglio

Per ottenere tutte le colonne necessarie, è possibile unire più tabelle.

Nell'esempio viene illustrata una selezione di cinque colonne di dati che contengono i dati per la ricerca: OrderId, OrderTitle, OrderDesc, CreatedDateTime e IsDeleted. Per impostare le autorizzazioni di visualizzazione per ogni riga di dati, è possibile selezionare facoltativamente queste colonne ACL: AllowedUsers, AllowedGroups, DeniedUsers e DeniedGroups. Tutte queste colonne di dati hanno anche le opzioni Query, Search, Retrieve o Refine.

Selezionare le colonne di dati come illustrato in questa query di esempio: SELECT OrderId, OrderTitle, OrderDesc, AllowedUsers, AllowedGroups, DeniedUsers, DeniedGroups, CreatedDateTime, IsDeleted

I connettori SQL non consentono nomi di colonna con caratteri non alfanumerici nella clausola SELECT. Rimuovere eventuali caratteri non alfanumerici dai nomi di colonna usando un alias. Esempio : SELECT column_name AS columnName

Per gestire l'accesso ai risultati della ricerca, è possibile specificare una o più colonne ACL nella query. Il connettore SQL consente di controllare l'accesso a livello di record. È possibile scegliere di avere lo stesso controllo di accesso per tutti i record in una tabella. Se le informazioni ACL vengono archiviate in una tabella separata, potrebbe essere necessario eseguire un join con tali tabelle nella query.

L'uso di ognuna delle colonne ACL nella query precedente è descritto di seguito. L'elenco seguente illustra i quattro meccanismi di controllo di accesso.

  • AllowedUsers: questa colonna specifica l'elenco di ID utente che possono accedere ai risultati della ricerca.
  • AllowedGroups: questa colonna specifica il gruppo di utenti che possono accedere ai risultati della ricerca.
  • DeniedUsers: questa colonna specifica l'elenco di utenti che non hanno accesso ai risultati della ricerca.
  • DeniedGroups: questa colonna specifica il gruppo di utenti che non hanno accesso ai risultati della ricerca.

b. Tipi di dati supportati

[Fare clic per espandere] Elenco dei tipi di dati supportati.

La tabella riepiloga i tipi di dati SQL supportati nel connettore PostgreSQL. La tabella riepiloga anche il tipo di dati di indicizzazione per il tipo di dati SQL supportato. Per altre informazioni sui connettori di Microsoft Graph supportati dai tipi di dati per l'indicizzazione, vedere la documentazione sui tipi di risorse di proprietà.

Categoria Tipo di dati di origine Tipo di dati di indicizzazione
Numerico smallint
integer
bigint
smallserial
seriale
bigserial		 int64
Numerico decimale
numerico
real
precisione doppia		 doppio
Carattere carattere variabile(n)
varchar(n)
character(n)
char(n)
bpchar(n)
bpchar
Testo
 stringa
Monetario denaro int64
Binario bytea stringa
Data o ora timestamp [(p)] senza fuso orario
timestamp [(p)] con fuso orario
data
time [(p)] senza fuso orario
time [(p)] con fuso orario		 datetime
Data o ora interval [fields] [(p)] stringa
Booleano booleano booleano
Enumerato enumerazione stringa

Per qualsiasi altro tipo di dati attualmente non supportato direttamente, è necessario eseguire il cast esplicito della colonna a un tipo di dati supportato.


c. Filigrana (obbligatorio)

[Fare clic per espandere] Specifica della colonna filigrana nella query di ricerca per indicizzazione completa

Per evitare l'overload del database, il connettore crea un batch e riprende le query con ricerca per indicizzazione completa con una colonna filigrana a ricerca per indicizzazione completa. Usando il valore della colonna filigrana, ogni batch successivo viene recuperato e l'esecuzione di query viene ripresa dall'ultimo checkpoint. Essenzialmente questo meccanismo controlla l'aggiornamento dei dati per le ricerche per indicizzazione complete.

Creare frammenti di query per le filigrane, come illustrato negli esempi seguenti:

  • WHERE (CreatedDateTime > @watermark). Citare il nome della colonna filigrana con la parola chiave @watermarkriservata . Se l'ordinamento della colonna filigrana è crescente, utilizzare >; in caso contrario, utilizzare <.
  • ORDER BY CreatedDateTime ASC. Ordinare la colonna filigrana in ordine crescente o decrescente.

Per recuperare il primo batch di righe, specificare il tipo di dati della colonna filigrana.

La prima query recupera il primo numero N di righe usando: "CreatedDateTime > 1 gennaio 1753 00:00:00" (valore minimo del tipo di dati DateTime). Dopo il recupero del primo batch, il valore più alto di CreatedDateTime restituito nel batch viene salvato come checkpoint se le righe vengono ordinate in ordine crescente. Un esempio è il 1° marzo 2019 03:00:00. Il batch successivo di N righe viene quindi recuperato usando "CreatedDateTime > 1 marzo 2019 03:00:00" nella query.


2. Istruzioni di eliminazione temporanea (facoltativo)

Per escludere l'indicizzazione delle righe eliminate temporaneamente nel database, specificare il nome e il valore della colonna di eliminazione temporanea che indicano che la riga è stata eliminata.

Utenti

1. Eseguire il mapping di colonne contenenti informazioni sulle autorizzazioni di accesso

Selezionare Mappa colonne per scegliere le varie colonne di controllo di accesso (ACL) che specificano il meccanismo di controllo di accesso. Selezionare il nome di colonna specificato nella query SQL per indicizzazione completa.

Ogni colonna ACL deve essere una colonna multivalore. I separatori, ad esempio punto e virgola (;), virgola (,) e così via, possono separare questi valori ID multipli. È necessario specificare questo separatore nel campo separatore di valori .

I tipi di ID seguenti sono supportati per l'uso come ACL:

  • Nome entità utente (UPN): un nome dell'entità utente (UPN) è il nome di un utente di sistema in formato indirizzo di posta elettronica. Un UPN (ad esempio: john.doe@domain.com) è costituito dal nome utente (nome di accesso), dal separatore (simbolo @) e dal nome di dominio (suffisso UPN).
  • Microsoft Entra ID: in Microsoft Entra ID, ogni utente o gruppo ha un ID oggetto simile a "e0d3ad3d-0000-1111-2222-3c5f5c52ab9b".
  • ID di sicurezza di Active Directory (AD): in un'installazione di Active Directory locale, ogni utente e gruppo ha un identificatore di sicurezza univoco non modificabile simile a "S-1-5-21-3878594291-2115959936-132693609-65242".

2. Autorizzazioni di accesso

È possibile scegliere di usare gli ACL specificati nel passaggio precedente oppure eseguirne l'override per rendere visibile il contenuto a tutti.

Sincronizza

L'intervallo di aggiornamento determina la frequenza con cui i dati vengono sincronizzati tra l'origine dati e l'indice del connettore Graph.

È possibile configurare ricerche per indicizzazione complete e incrementali in base alle opzioni di pianificazione disponibili qui. Per impostazione predefinita, la ricerca per indicizzazione incrementale (se configurata) viene impostata per ogni 15 minuti e la ricerca per indicizzazione completa viene impostata per ogni giorno. Se necessario, è possibile modificare queste pianificazioni in base alle esigenze di aggiornamento dei dati.

A questo punto, si è pronti per creare la connessione per PostgreSQL. È possibile fare clic sul pulsante "Crea" per pubblicare i dati di connessione e indice dal database.

Risoluzione dei problemi

Dopo aver pubblicato la connessione, è possibile esaminare lo stato nella scheda Origini datinell'interfaccia di amministrazione. Per informazioni su come eseguire aggiornamenti ed eliminazioni, vedere Gestire il connettore.

In caso di problemi o se si desidera fornire commenti e suggerimenti, contattare Microsoft Graph | Supporto.