Indicizzare BLOB e file JSON in Azure AI Search
Si applica a: Indicizzatori BLOB, Indicizzatori file
Per l'indicizzazione BLOB in Azure AI Search, questo articolo illustra come impostare le proprietà per BLOB o file costituiti da documenti JSON. I file JSON in Archiviazione BLOB di Azure o File di Azure hanno in genere uno dei formati seguenti:
- Un singolo documento JSON
- Documento JSON contenente una matrice di elementi JSON ben formati
- Documento JSON contenente più entità, separate da una nuova riga
L'indicizzatore BLOB fornisce un parametro parsingMode per ottimizzare l'output del documento di ricerca in base alla struttura JSON. Le modalità di analisi sono costituite dalle opzioni seguenti:
| parsingMode | Documento JSON | Descrizione |
|---|---|---|
json |
Un solo documento per BLOB | (Impostazione predefinita) Analizza i BLOB JSON come un singolo blocco di testo. Ogni BLOB JSON diventa un singolo documento di ricerca. |
jsonArray |
Più documenti per BLOB | Analizza una matrice JSON nel BLOB, dove ogni elemento della matrice diventa un documento separato di ricerca. |
jsonLines |
Più documenti per BLOB | Analizza un BLOB che contiene più entità JSON (anche una matrice), con singoli elementi separati da una nuova riga. L'indicizzatore avvia un nuovo documento di ricerca dopo ogni nuova riga. |
Per jsonArray e jsonLines è necessario esaminare Indicizzazione di un BLOB per produrre molti documenti di ricerca per comprendere il modo in cui l'indicizzatore BLOB gestisce la disambiguazione della chiave del documento per più documenti di ricerca generati dallo stesso BLOB.
Se si vuole, all'interno della definizione dell'indicizzatore è possibile usare i mapping dei campi per scegliere quali proprietà del documento JSON di origine vengono usate per popolare l'indice di ricerca di destinazione. Ad esempio, quando si usa la modalità di analisi jsonArray, se la matrice esiste come proprietà di livello inferiore, è possibile impostare una proprietà "documentRoot" che indica la posizione della matrice all'interno del BLOB.
Nota
Quando viene usata una modalità di analisi JSON, Azure AI Search presuppone che tutti i BLOB usino lo stesso parser (per json, jsonArray o jsonLines). Se si ha una combinazione di tipi di file diversi nella stessa origine dati, è consigliabile usare filtri di estensione di file per controllare quali file vengono importati.
Le sezioni seguenti descrivono ogni modalità in modo più dettagliato. Se non si ha familiarità con i client e i concetti dell'indicizzatore, vedere Creare un indicizzatore di ricerca. È anche necessario avere familiarità con i dettagli della configurazione dell'indicizzatore BLOB di base, che non viene ripetuta qui.
Indicizzare singoli documenti JSON (uno per BLOB)
Per impostazione predefinita, gli indicizzatori BLOB analizzano i BLOB JSON come un singolo blocco di testo, un documento di ricerca per ogni BLOB in un contenitore. Se il codice JSON è strutturato, il documento di ricerca può riflettere tale struttura, con singoli elementi rappresentati come singoli campi. Si supponga, ad esempio, che in Archiviazione BLOB di Azure sia presente il documento JSON seguente:
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2020-04-13",
"tags" : [ "search", "storage", "howto" ]
}
}
L'indicizzatore BLOB analizza il documento JSON in un singolo documento di ricerca, caricando un indice associando "text", "datePublished" e "tags" dall'origine a campi di indice di destinazione denominati e tipizzati in modo identico. Dato un indice con i campi "text", "datePublished" e "tag", l'indicizzatore di BLOB è in grado di dedurre il mapping corretto senza che sia definito un mapping di campi nella richiesta.
Anche se il comportamento predefinito è un documento di ricerca per BLOB JSON, l'impostazione della modalità di analisi json modifica i mapping dei campi interni per il contenuto, promuovendo i campi all'interno di content a campi effettivi nell'indice di ricerca. Una definizione dell'indicizzatore di esempio per la modalità di analisi json potrebbe essere simile alla seguente:
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "json" } }
}
Nota
Come per tutti gli indicizzatori, se i campi non corrispondono chiaramente, ci si deve aspettare che sia necessario specificare in modo esplicito i singoli mapping dei campi, a meno che non si usino i mapping dei campi impliciti disponibili per il contenuto e i metadati BLOB, come descritto nella configurazione dell'indicizzatore BLOB di base.
Esempio JSON (file hotel JSON singoli)
Il set di dati del documento hotel JSON in GitHub è utile per il test dell'analisi JSON, in cui ogni BLOB rappresenta un file JSON strutturato. È possibile caricare i file di dati in Archiviazione BLOB e usare la procedura guidata Importa dati per valutare rapidamente il modo in cui questo contenuto viene analizzato in singoli documenti di ricerca.
Il set di dati è costituito da cinque BLOB, ognuno dei quali contiene un documento hotel con una raccolta di indirizzi e una raccolta di camere. L'indicizzatore BLOB rileva entrambe le raccolte e riflette la struttura dei documenti di input nello schema dell'indice.
Analizzare matrici JSON
In alternativa, è possibile usare l'opzione basata su matrice JSON. Questa opzione è utile quando i BLOB contengono una matrice di oggetti JSON ben formati e si vuole che ogni elemento della matrice diventi un documento separato di ricerca. Usando jsonArrays, il BLOB JSON seguente produce tre documenti separati, ognuno con i campi "id" e "text".
[
{ "id" : "1", "text" : "example 1" },
{ "id" : "2", "text" : "example 2" },
{ "id" : "3", "text" : "example 3" }
]
La proprietà parameters nell'indicizzatore contiene valori della modalità di analisi. Per una matrice JSON, la definizione di indicizzatore dovrebbe avere un aspetto simile all'esempio seguente.
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}
Esempio jsonArrays
Il set di dati New York Philharmonic JSON in GitHub è utile per testare l'analisi di matrici JSON. È possibile caricare i file di dati in Archiviazione BLOB e usare la procedura guidata Importa dati per valutare rapidamente il modo in cui questo contenuto viene analizzato in singoli documenti di ricerca.
Il set di dati è costituito da otto BLOB, ognuno dei quali contiene una matrice JSON di entità, per un totale di 100 entità. Le entità variano a seconda dei campi popolati, ma il risultato finale è un documento di ricerca per entità, da tutte le matrici, in tutti i BLOB.
Analisi di matrici JSON annidate
Per le matrici JSON con elementi annidati è possibile specificare documentRoot per indicare una struttura a più livelli. Ad esempio, se i BLOB sono simili a questo:
{
"level1" : {
"level2" : [
{ "id" : "1", "text" : "Use the documentRoot property" },
{ "id" : "2", "text" : "to pluck the array you want to index" },
{ "id" : "3", "text" : "even if it's nested inside the document" }
]
}
}
Usare questa configurazione per indicizzare la matrice contenuta nella proprietà level2:
{
"name" : "my-json-array-indexer",
... other indexer properties
"parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}
Analizzare le entità JSON separate da nuove righe
Se il BLOB contiene più entità JSON separate da una nuova riga e si vuole che ogni elemento diventi un documento di ricerca separato, usare jsonLines.
{ "id" : "1", "text" : "example 1" }
{ "id" : "2", "text" : "example 2" }
{ "id" : "3", "text" : "example 3" }
Per le righe JSON, la definizione di indicizzatore dovrebbe avere un aspetto simile all'esempio seguente.
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "my-json-indexer",
"dataSourceName" : "my-blob-datasource",
"targetIndexName" : "my-target-index",
"parameters" : { "configuration" : { "parsingMode" : "jsonLines" } }
}
Eseguire il mapping dei campi JSON ai campi di ricerca
I mapping dei campi associano un campo di origine a un campo di destinazione in situazioni in cui i nomi e i tipi dei campi non sono identici. Ma i mapping dei campi possono essere usati anche per trovare le corrispondenze tra parti di un documento JSON e "sollevarle" in campi di primo livello del documento di ricerca.
Nel seguente scenario di esempio viene illustrato questo aspetto. Per altre informazioni sui mapping dei campi in generale, vedere Mapping dei campi.
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2016-04-13"
"tags" : [ "search", "storage", "howto" ]
}
}
Si supponga di avere un indice di ricerca con i campi seguenti: text di tipo Edm.String, date di tipo Edm.DateTimeOffset e tags di tipo Collection(Edm.String). Si noti la discrepanza tra "datePublished" nell'origine e il campo date nell'indice. Per eseguire il mapping del file JSON per ottenere la forma desiderata, usare i mapping dei campi seguenti:
"fieldMappings" : [
{ "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
{ "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
{ "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
]
I campi di origine vengono specificati usando la notazione JSON Pointer. Iniziare con una barra per fare riferimento alla radice del documento JSON, quindi passare alla proprietà desiderata, a un livello di annidamento arbitrario, usando un percorso separato da barre.
È anche possibile fare riferimento a singoli elementi della matrice usando un indice a base zero. Ad esempio, per selezionare il primo elemento della matrice "tags" dall'esempio precedente, usare un mapping dei campi analogo al seguente:
{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }
Nota
Se "sourceFieldName" fa riferimento a una proprietà che non esiste nel BLOB JSON, tale mapping viene ignorato senza errori. Questo comportamento consente di continuare l'indicizzazione per i BLOB JSON che hanno uno schema diverso, che è un caso d'uso comune. Poiché non è presente alcun controllo di convalida, controllare attentamente i mapping per individuare gli errori di digitazione in modo da non perdere documenti per il motivo sbagliato.