Informazioni di riferimento sull'API REST per intelligenza artificiale di Azure Search

  • Articolo

Azure AI Search (in precedenza noto come Ricerca cognitiva di Azure) è un servizio di ricerca cloud completamente gestito che fornisce informazioni sul recupero dei contenuti di proprietà dell'utente.

Le API REST del piano dati vengono usate per l'indicizzazione e i flussi di lavoro di query e sono documentati in questa sezione.

Le operazioni del piano di controllo vengono accessibili tramite un'API REST di gestione separata.

Documentazione dell'API con versione

I documenti dell'API REST sono ora versioneti. Quando si apre una pagina di riferimento api, viene visualizzato un selettore di versione sopra il sommario. Assicurarsi che il riferimento all'API sia dalla cartella Del piano dati di riferimento>.

Screenshot del selettore di versione.

Concetti chiave

Azure AI Search ha i concetti dei servizi di ricerca, degli indici, dei documenti, degli indicizzatori, delle origini dati, dei set di competenze e delle mappe sinonimi.

  • Un servizio di ricerca ospita indici, indicizzatori, origini dati, set di competenze e mappe sinonimi come oggetti di primo livello.
  • Un indice di ricerca fornisce un archivio permanente dei documenti di ricerca. Search documenti sono i dati, articolati come raccolta di campi, caricati da origini esterne e push a un indice per renderlo ricercabile.
  • Un indicizzatore di ricerca aggiunge automazione, lettura dei dati in formati nativi e serializzazione in JSON.
  • Un indicizzatore ha un'origine dati e punta a un indice.
  • Un indicizzatore potrebbe anche avere un set di competenze che aggiunge l'arricchimento dell'intelligenza artificiale e la vettorizzazione integrata alla pipeline di indicizzazione. I set di competenze sono sempre collegati a un indicizzatore. Richiamano Machine Learning per estrarre o blocchi di testo, vettorizzare il contenuto, dedurre funzionalità o aggiungere struttura al contenuto in modo che possa essere indicizzato da un servizio di ricerca.

È possibile creare tutti gli oggetti seguenti in un servizio di ricerca:

Oggetti Descrizione
Origini dati Connessione origine dati usata da un indicizzatore per recuperare e aggiornare i documenti per l'indicizzazione. Le origini dati hanno un typeoggetto . È possibile usare le connessioni fornite da Microsoft per Azure o connettori di terze parti tramite partner. Per l'elenco completo, vedere Raccolta origini dati .
Documenti Concettualmente, un documento è un'entità nell'indice. Mapping di questo concetto agli equivalenti di database più noti: un indice di ricerca equivale a una tabella e i documenti sono approssimativamente equivalenti alle righe di una tabella. I documenti esistono solo in un indice e vengono recuperati solo tramite query destinate alla raccolta documenti (/docs) di un indice. Tutte le operazioni eseguite nella raccolta, ad esempio il caricamento, l'unione, l'eliminazione o l'esecuzione di query dei documenti nel contesto di un singolo indice, in modo che le operazioni del documento in formato URL includano /indexes/[index name]/docs sempre per un determinato nome di indice.
Indici Un indice viene archiviato nel servizio di ricerca e popolato con documenti JSON indicizzati e tokenizzati per il recupero delle informazioni. La raccolta di campi di un indice definisce la struttura del documento di ricerca. I campi hanno un nome, tipi di dati e attributi che determinano la modalità di utilizzo. Ad esempio, searchable i campi vengono usati nella ricerca full-text e quindi tokenizzati durante l'indicizzazione. Un indice definisce anche altri costrutti, ad esempio i profili di assegnazione dei punteggi per l'ottimizzazione della pertinenza, i suggeritori, le configurazioni semantiche e gli analizzatori personalizzati.
Indicizzatori Gli indicizzatori forniscono l'automazione dell'indicizzazione. Un indicizzatore si connette a un'origine dati, legge i dati e lo passa a un motore di ricerca per l'indicizzazione in un indice di ricerca di destinazione. Gli indicizzatori leggono da un'origine esterna usando le informazioni di connessione in un'origine dati e serializzano i dati in ingresso nei documenti di ricerca JSON. Oltre a un'origine dati, un indicizzatore richiede anche un indice. L'indice specifica i campi e gli attributi dei documenti di ricerca.
Set di competenze Un set di competenze aggiunge passaggi di elaborazione esterni all'esecuzione dell'indicizzatore e viene in genere usato per aggiungere modelli di intelligenza artificiale o deep learning per analizzare o trasformare il contenuto per renderlo ricercabile in un indice. Il contenuto di un set di competenze è una o più competenze, che possono essere create da Microsoft, competenze personalizzate o una combinazione di entrambi. Le competenze predefinite esistono per l'analisi delle immagini, tra cui OCR e elaborazione del linguaggio naturale. Altri esempi di competenze predefinite includono il riconoscimento delle entità, l'estrazione di frasi chiave, il blocco di testo in pagine logiche, tra gli altri. Un set di competenze è un oggetto autonomo di alto livello che esiste a livello equivalente a indici, indicizzatori e origini dati, ma è operativo solo all'interno dell'elaborazione dell'indicizzatore. Come oggetto di alto livello, è possibile progettare un set di competenze una volta e quindi farvi riferimento in più indicizzatori.
Mappe sinonimi Una mappa sinonimia è un oggetto a livello di servizio che contiene sinonimi definiti dall'utente. Questo oggetto viene mantenuto indipendentemente dagli indici di ricerca. Dopo il caricamento, è possibile puntare qualsiasi campo ricercabile alla mappa sinonimo (una per campo).

Autorizzazioni e controllo di accesso

È possibile usare l'autenticazione basata su chiavi o basata sul ruolo tramite Microsoft Entra ID.

  • L'autenticazione basata su chiavi si basa sulle chiavi API generate per il servizio di ricerca. La presenza di una chiave valida stabilisce una relazione di trust, in base alle singole richieste, tra l'applicazione che invia la richiesta e il servizio che la gestisce. È possibile usare una chiave API Amministrazione per operazioni di lettura-scrittura o una chiave API query per l'accesso in lettura alla raccolta documenti di un indice di ricerca.

  • Microsoft Entra ID controllo degli accessi in base al ruolo e all'autenticazione richiede che sia stato stabilito un tenant in Microsoft Entra ID, con entità di sicurezza e assegnazioni di ruolo. I membri dei ruoli seguenti hanno accesso al piano dati. È possibile creare ruoli personalizzati se i ruoli predefiniti non sono sufficienti.

    Ruolo Access
    Collaboratore servizi di ricerca Accesso agli oggetti, ma nessun accesso al contenuto dell'indice. Questo ruolo non può eseguire query su un indice di ricerca o aggiungere, rimuovere o aggiornare documenti in un indice di ricerca. Questo ruolo è destinato agli amministratori che devono gestire gli oggetti, ma senza la possibilità di visualizzare o accedere ai dati degli oggetti.
    collaboratore Search indice dati Accesso in lettura-scrittura al contenuto dell'indice. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice.
    lettore di indici dati Search Accesso in lettura al contenuto dell'indice. Questo ruolo è destinato alle app e agli utenti che eseguono query.

Quando si usano ruoli nella connessione, l'app client presenta un token di connessione nell'intestazione di autorizzazione. Vedere Autorizzare l'accesso a un'app di ricerca usando Microsoft Entra ID per informazioni sulla configurazione.

È possibile disabilitare l'autenticazione basata su chiavi o l'autenticazione basata su ruoli. Se si disabilita l'autenticazione basata su ruoli, alcuni ruoli predefiniti avranno comunque accesso. Per informazioni dettagliate, vedere Microsoft Entra ID autenticazione e controllo degli accessi in base al ruolo per i Search di intelligenza artificiale di Azure.

Chiamata delle API

Le API illustrate in questa sezione consentono di accedere alle operazioni sui dati di ricerca, ad esempio creazione e popolamento degli indici, caricamento di documenti e query. Quando si chiamano API, tenere presenti i punti seguenti:

  • Le richieste devono essere rilasciate tramite HTTPS (nella porta predefinita 443).

  • Gli URI della richiesta devono includere la versione api. Il valore deve essere impostato su una versione supportata, formattata come illustrato in questo esempio: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Le intestazioni di richiesta devono includere una chiave API o un token di connessione per le connessioni autenticate. Facoltativamente, è possibile impostare l'intestazione Accept HTTP. Se l'intestazione del tipo di contenuto non è impostata, si presuppone che il valore predefinito sia application/json.

Vedi anche