Indicizzazione di BLOB JSON con l'indicizzatore di BLOB di Ricerca di AzureIndexing JSON blobs with Azure Search blob indexer

Questo articolo illustra come configurare un indicizzatore di BLOB di Ricerca di Azure per estrarre contenuto strutturato dai BLOB JSON in Archiviazione BLOB di Azure.This article shows you how to configure an Azure Search blob indexer to extract structured content from JSON blobs in Azure Blob storage.

I BLOB JSON in Archiviazione BLOB di Azure consistono in genere in un singolo documento JSON o in una matrice JSON.JSON blobs in Azure Blob storage are typically either a single JSON document or a JSON array. L'indicizzatore di BLOB di Ricerca di Azure è in grado di analizzare entrambi i tipi di costruzione, a seconda dell'impostazione del parametro parsingMode nella richiesta.The blob indexer in Azure Search can parse either construction, depending on how you set the parsingMode parameter on the request.

Documento JSONJSON document parsingModeparsingMode DescrizioneDescription DisponibilitàAvailability
Un solo documento per BLOBOne per blob json Analizza i BLOB JSON come un singolo blocco di testo.Parses JSON blobs as a single chunk of text. Ogni BLOB JSON diventa un singolo documento di Ricerca di Azure.Each JSON blob becomes a single Azure Search document. Disponibile a livello generale nelle API REST e .NET.Generally available in both REST and .NET APIs.
Più documenti per BLOBMultiple per blob jsonArray Analizza una matrice JSON nel BLOB, dove ogni elemento della matrice diventa un documento separato di Ricerca di Azure.Parses a JSON array in the blob, where each element of the array becomes a separate Azure Search document. In anteprima, in REST api-version=2016-09-01-Preview e nella versione di anteprima di .NET SDK.In preview, in REST api-version=2016-09-01-Preview and .NET SDK Preview.

Nota

Le API di anteprima sono destinate alle attività di test e valutazione e non devono essere usate negli ambienti di produzione.Preview APIs are intended for testing and evaluation, and should not be used in production environments.

Configurazione dell'indicizzazione JSONSetting up JSON indexing

L'indicizzazione dei BLOB JSON è simile all'estrazione normale dei documenti in un flusso di lavoro in tre fasi comune a tutti gli indicizzatori di Ricerca di Azure.Indexing JSON blobs is similar to the regular document extraction in a three-part workflow common to all indexers in Azure Search.

Passaggio 1: Creare un'origine datiStep 1: Create a data source

Il primo passaggio consiste nel fornire le informazioni sulla connessione all'origine dati che vengono usate dall'indicizzatore.The first step is to provide data source connection information used by the indexer. Il tipo di origine dati, qui specificato come azureblob, determina i comportamenti di estrazione dei dati che vengono richiamati dall'indicizzatore.The data source type, specified here as azureblob, determines which data extraction behaviors are invoked by the indexer. Per l'indicizzazione di BLOB JSON, la definizione dell'origine dati è identica sia per le matrici che per i documenti JSON.For JSON blob indexing, data source is definition is the same for both JSON documents and arrays.

POST https://[service name].search.windows.net/datasources?api-version=2016-09-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "optional, my-folder" }
}   

Passaggio 2: Creare un indice di ricerca di destinazioneStep 2: Create a target search index

Gli indicizzatori sono associati allo schema di un indice.Indexers are paired with an index schema. Se si usa l'API, anziché il portale, preparare un indice in anticipo in modo poterlo specificare per l'operazione dell'indicizzatore.If you are using the API (rather than the portal), prepare an index in advance so that you can specify it on the indexer operation.

Nota

Gli indicizzatori vengono esposti nel portale tramite l'azione Importa per un numero limitato di indicizzatori disponibili a livello generale.Indexers are exposed in the portal through the Import action for a limited number of generally available indexers. Il flusso di lavoro di importazione può spesso costruire un indice preliminare in base ai metadati presenti nell'origine.Often, the import workflow can often construct a preliminary index based on metadata in the source. Per altre informazioni, vedere Importare dati in Ricerca di Azure tramite il portale.For more information, see Import data into Azure Search in the portal.

Passaggio 3: Configurare ed eseguire l'indicizzatoreStep 3: Configure and run the indexer

Fino a questo momento, le definizioni per l'origine dati e l'indice non sono state influenzate dal parametro parsingMode.Until now, definitions for the data source and index have been parsingMode agnostic. Tuttavia, nel passaggio 3 relativo alla configurazione dell'indicizzatore, la procedura cambia a seconda di come si vuole analizzare e strutturare il contenuto dei BLOB JSON in un indice di Ricerca di Azure.However, in step 3 for Indexer configuration, the path diverges depending on how you want the JSON blob content to be parsed and structured in an Azure Search index.

Quando si chiama l'indicizzatore, eseguire queste operazioni:When calling the indexer, do the following:

  • Impostare il parametro parsingMode su json, per indicizzare ogni BLOB come un singolo documento, oppure su jsonArray, se i BLOB contengono matrici JSON ed è necessario trattare ogni elemento di una matrice come un documento separato.Set the parsingMode parameter to json (to index each blob as a single document) or jsonArray (if your blobs contain JSON arrays and you need each element of an array to be treated as a separate document).

  • Facoltativamente, usare i mapping dei campi per scegliere quali proprietà del documento JSON di origine vengono usate per popolare l'indice di ricerca di destinazione.Optionally, use field mappings to choose which properties of the source JSON document are used to populate your target search index. Per le matrici JSON, se la matrice esiste come proprietà di livello inferiore, è possibile impostare un elemento radice dei documenti che indica il punto in cui la matrice viene posizionata all'interno del BLOB.For JSON arrays, if the array exists as a lower level property, you can set a document root indicating where the array is placed within the blob.

Importante

Quando si usa la modalità di analisi json o jsonArray, Ricerca di Azure presuppone che tutti i BLOB nell'origine dati siano di tipo JSON.When you use json or jsonArray parsing mode, Azure Search assumes that all blobs in your data source contain JSON. Se è necessario supportare una combinazione di BLOB di tipo JSON e non JSON nella stessa origine dati, comunicare questa esigenza sul sito UserVoice.If you need to support a mix of JSON and non-JSON blobs in the same data source, let us know on our UserVoice site.

Come analizzare i singoli BLOB JSONHow to parse single JSON blobs

Per impostazione predefinita, l' indicizzatore BLOB di Ricerca di Azure analizza i BLOB di tipo JSON come blocco singolo di testo.By default, Azure Search blob indexer parses JSON blobs as a single chunk of text. È spesso possibile che si voglia preservare la struttura dei documenti JSON.Often, you want to preserve the structure of your JSON documents. Si supponga, ad esempio, che in Archiviazione BLOB di Azure sia presente il documento JSON seguente:For example, assume you have the following JSON document in Azure Blob storage:

{
    "article" : {
        "text" : "A hopefully useful article explaining how to parse JSON blobs",
        "datePublished" : "2016-04-13"
        "tags" : [ "search", "storage", "howto" ]    
    }
}

Definizione dell'indicizzatore per singoli BLOB JSONIndexer definition for single JSON blobs

Se si usa l'indicizzatore di BLOB di Ricerca di Azure, un documento JSON simile all'esempio precedente viene analizzato in un singolo documento di Ricerca di Azure.Using the Azure Search blob indexer, a JSON document similar to the previous example is parsed into a single Azure Search document. Per caricare un indice, l'indicizzatore stabilisce una corrispondenza tra i campi "text", "datePublished" e "tags" dell'origine e i campi di destinazione tipizzati con lo stesso nome.The indexer loads an index by matching "text", "datePublished", and "tags" from the source against identically named and typed target fields.

La configurazione viene specificata nel corpo di un'operazione dell'indicizzatore.Configuration is provided in the body of an indexer operation. Tenere presente che l'oggetto origine dati, definito in precedenza, specifica le informazioni relative alla connessione e al tipo dell'origine dati.Recall that the data source object, previously defined, specifies the data source type and connection information. L'indice di destinazione deve inoltre essere definito come contenitore vuoto nel servizio.Additionally, the target index must also exist as an empty container in your service. I campi "schedule" e "parameters" sono facoltativi, ma se vengono omessi, l'indicizzatore viene eseguito immediatamente in modalità di analisi json.Schedule and parameters are optional, but if you omit them, the indexer runs immediately, using json as the parsing mode.

Una richiesta completamente specificata può avere l'aspetto seguente:A fully specified request might look as follows:

POST https://[service name].search.windows.net/indexers?api-version=2016-09-01
Content-Type: application/json
api-key: [admin key]

{
  "name" : "my-json-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" },
  "parameters" : { "configuration" : { "parsingMode" : "json" } }
}

Come già indicato, i mapping dei campi non sono obbligatori.As noted, field mappings are not required. 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.Given an index with "text", "datePublished, and "tags" fields, the blob indexer can infer the correct mapping without a field mapping present in the request.

Come analizzare le matrici JSON (anteprima)How to parse JSON arrays (preview)

In alternativa, è possibile scegliere la funzionalità di anteprima per le matrici JSON.Alternatively, you can opt for the JSON array preview feature. Questa funzionalità è utile quando i BLOB contengono una matrice di oggetti JSON e si vuole che ogni elemento della matrice diventi un documento separato di Ricerca di Azure.This capability is useful when blobs contain an array of JSON objects, and you want each element to become a separate Azure Search document. Ad esempio, dato il BLOB JSON seguente, è possibile popolare l'indice di Ricerca di Azure con tre documenti separati, ognuno con i campi "id" e "text".For example, given the following JSON blob, you can populate your Azure Search index with three separate documents, each with "id" and "text" fields.

[
    { "id" : "1", "text" : "example 1" },
    { "id" : "2", "text" : "example 2" },
    { "id" : "3", "text" : "example 3" }
]

Definizione dell'indicizzatore per una matrice JSONIndexer definition for a JSON array

Per una matrice JSON, la richiesta dell'indicizzatore usa l'API di anteprima e la modalità di analisi jsonArray.For a JSON array, the indexer request uses the preview API and the jsonArray parser. Questi sono gli unici due requisiti specifici delle matrici per l'indicizzazione di BLOB JSON.These are the only two array-specific requirements for indexing JSON blobs.

POST https://[service name].search.windows.net/indexers?api-version=2016-09-01-Preview
Content-Type: application/json
api-key: [admin key]

{
  "name" : "my-json-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" },
  "parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}

Anche in questo caso, è opportuno notare che i mapping dei campi non sono obbligatori.Again, notice that field mappings are not required. Dato un indice con i campi "id" e "text", l'indicizzatore di BLOB è in grado di dedurre il mapping corretto senza un elenco di mapping di campi.Given an index with "id" and "text" fields, the blob indexer can infer the correct mapping without a field mapping list.

Matrici JSON annidateNested JSON arrays

Se si vuole indicizzare una matrice di oggetti JSON, ma questa matrice è annidata in un punto qualsiasi all'interno del documento?What if you wish to index an array of JSON objects, but that array is nested somewhere within the document? È possibile scegliere la proprietà che contiene la matrice usando la proprietà di configurazione documentRoot .You can pick which property contains the array using the documentRoot configuration property. Ad esempio, se i BLOB sono simili a questo:For example, if your blobs look like this:

{
    "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:Use this configuration to index the array contained in the level2 property:

{
    "name" : "my-json-array-indexer",
    ... other indexer properties
    "parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}

Uso dei mapping dei campi per creare documenti di ricercaUsing field mappings to build search documents

Quando i campi di origine e di destinazione non sono perfettamente allineati, è possibile definire una sezione di mapping dei campi nel corpo della richiesta per esplicitare le associazioni tra i campi.When source and target fields are not perfectly aligned, you can define a field mapping section in the request body for explicit field-to-field associations.

Ricerca di Azure non può attualmente indicizzare direttamente documenti JSON arbitrari, perché supporta solo tipi di dati primitivi, matrici di stringhe e punti GeoJSON.Currently, Azure Search cannot index arbitrary JSON documents directly, because it supports only primitive data types, string arrays, and GeoJSON points. È tuttavia possibile usare i mapping dei campi per selezionare parti del documento JSON e "portarle" nei campi di livello superiore del documento di ricerca.However, you can use field mappings to pick parts of your JSON document and "lift" them into top-level fields of the search document. Per nozioni fondamentali sui mapping dei campi, vedere Mapping dei campi negli indicizzatori di Ricerca di Azure.To learn about field mappings basics, see Field mappings in Azure Search indexers.

Tornando al documento JSON di esempio:Revisiting our example JSON document:

{
    "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).Assume a search index with the following fields: text of type Edm.String, date of type Edm.DateTimeOffset, and tags of type Collection(Edm.String). Si noti la discrepanza tra "datePublished" nell'origine e il campo date nell'indice.Notice the discrepancy between "datePublished" in the source and date field in the index. Per eseguire il mapping del file JSON per ottenere la forma desiderata, usare i mapping dei campi seguenti:To map your JSON into the desired shape, use the following field mappings:

"fieldMappings" : [
    { "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
    { "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
    { "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
  ]

I nomi dei campi di origine nei mapping vengono specificati mediante la notazione di tipo Puntatore JSON .The source field names in the mappings are specified using the JSON Pointer notation. 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.You start with a forward slash to refer to the root of your JSON document, then pick the desired property (at arbitrary level of nesting) by using forward slash-separated path.

È anche possibile fare riferimento a singoli elementi della matrice usando un indice a base zero.You can also refer to individual array elements by using a zero-based index. Ad esempio, per selezionare il primo elemento della matrice "tags" dall'esempio precedente, usare un mapping dei campi analogo al seguente:For example, to pick the first element of the "tags" array from the above example, use a field mapping like this:

{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }

Nota

Se un nome del campo di origine in un percorso di mapping dei campi fa riferimento a una proprietà inesistente nel file JSON, il mapping verrà ignorato senza errori.If a source field name in a field mapping path refers to a property that doesn't exist in JSON, that mapping is skipped without an error. Ciò consente di supportare documenti con schemi diversi, ovvero un caso di utilizzo comune.This is done so that we can support documents with a different schema (which is a common use case). Poiché non è disponibile alcuna convalida, sarà necessario evitare accuratamente gli errori di ortografia nella specifica dei mapping dei campi.Because there is no validation, you need to take care to avoid typos in your field mapping specification.

Esempio: richiesta dell'indicizzatore con mapping dei campiExample: Indexer request with field mappings

L'esempio seguente mostra un payload di indicizzatore completo con mapping dei campi:The following example is a fully specified indexer payload, including field mappings:

POST https://[service name].search.windows.net/indexers?api-version=2016-09-01
Content-Type: application/json
api-key: [admin key]

{
  "name" : "my-json-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" },
  "parameters" : { "configuration" : { "parsingMode" : "json" } },
  "fieldMappings" : [
    { "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
    { "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
    { "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
    ]
}

Come contribuire al miglioramento di Ricerca di AzureHelp us make Azure Search better

Se si hanno domande sulle funzionalità o idee per apportare miglioramenti, contattare Microsoft sul sito UserVoice.If you have feature requests or ideas for improvements, reach out to us on our UserVoice site.

Vedere ancheSee also