Indexar blobs e arquivos JSON no Azure AI Search
Aplica-se a: Indexadores de blobs, Indexares de arquivos
Para a indexação de blobs no IA do Azure Search, esse artigo mostra como definir propriedades para blobs ou arquivos que consistem em documentos JSON. Os arquivos JSON no Armazenamento de Blobs do Azure ou nos Arquivos do Azure geralmente assumem qualquer um desses formatos:
- Um documento JSON único
- Um documento JSON com uma matriz de elementos JSON bem formados
- Um documento JSON com várias entidades, separadas por uma nova linha
O indexador de blob fornece um parâmetro parsingMode para otimizar a saída do documento de pesquisa com base na estrutura JSON. Os modos de análise consistem nas seguintes opções:
| parsingMode | Documento JSON | Descrição |
|---|---|---|
json |
Um por blob | (padrão) Analisa blobs JSON como um bloco único de texto. Cada blob JSON se torna um único documento de pesquisa. |
jsonArray |
Múltiplos por blob | Analisa uma matriz JSON no blob, em que cada elemento da matriz se torna um documento de pesquisa separado. |
jsonLines |
Múltiplos por blob | Analisa um blob que contém várias entidades JSON (também uma matriz), com elementos individuais separados por uma nova linha. O indexador inicia um novo documento de pesquisa depois de cada nova linha. |
Para jsonArray e jsonLines, consulte Indexando um blob para produzir muitos documentos de pesquisa para entender como o indexador de blobs processa a desambiguidade da chave do documento para vários documentos de pesquisa produzidos com base no mesmo blob.
Na definição de indexador, você tem a opção de definir mapeamentos de campo para selecionar quais propriedades do documento JSON de origem serão usadas para preencher o índice de pesquisa de destino. Por exemplo, se a matriz existir como uma propriedade de nível inferior ao usar o modo de análise jsonArray, você poderá definir uma propriedade "documentRoot" que indica onde a matriz está inserida no blob.
Observação
Quando um modo de análise JSON é usado, a Pesquisa de IA do Azure pressupõe que todos os blobs usem o mesmo analisador (para json, jsonArray ou jsonLines). Se você tiver uma combinação de tipos de arquivo diferentes na mesma fonte de dados, considere usar os filtros de extensão dos arquivo para controlar quais arquivos são importados.
As seções a seguir descrevem cada modo mais detalhadamente. Se você não estiver familiarizado com conceitos e clientes de indexador, confira Criar um indexador de pesquisa. Você também deve estar familiarizado com os detalhes da configuração básica do indexador de blobs, que não é repetida aqui.
Indexar documentos JSON únicos (um por blob)
Por padrão, os indexadores de blobs analisam blobs JSON como um bloco único de texto, um documento de pesquisa para cada blob em um contêiner. Se o JSON for estruturado, o documento de pesquisa poderá refletir essa estrutura, com elementos individuais representados como campos individuais. Por exemplo, suponha que você tem o seguinte documento JSON no Armazenamento de Blobs do Azure:
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2020-04-13",
"tags" : [ "search", "storage", "howto" ]
}
}
O indexador de blobs analisa o documento JSON em um único documento de pesquisa e carrega um índice correspondendo "text", "datePublished" e "tags" da origem com campos de índice de destino nomeados e digitados de forma idêntica. Dado um índice com os campos "texto", "data de publicação e "marcas", o indexador blob pode inferir o mapeamento correto sem um campo de mapeamento presente na solicitação.
Embora o comportamento padrão seja um documento de pesquisa por blob JSON, definir o modo de análise json altera os mapeamentos de campos internos para conteúdo, promovendo campos dentro de content para campos reais no índice de pesquisa. Um exemplo de definição de indexador para o modo de análise json pode ter esta aparência:
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" } }
}
Observação
Como ocorre com todos os indexadores, se os campos não correspondem claramente, a expectativa é que os mapeamentos de campo individuais sejam especificados explicitamente, a menos que você esteja usando os mapeamentos de campos implícitos disponíveis para metadados e conteúdo de blob, conforme descrito na configuração básica do indexador de blobs.
Exemplo de JSON (arquivos JSON de um único hotel)
O conjunto de dados de documentos JSON de hotel no GitHub é útil para testar a análise JSON, em que cada blob representa um arquivo JSON estruturado. Você pode carregar os arquivos de dados no Armazenamento de Blobs e usar o Assistente para importação de dados para avaliar rapidamente como esse conteúdo é analisado em documentos de pesquisa individuais.
O conjunto de dados consiste em cinco blobs, cada um contendo um documento de hotel com uma coleção de endereços e uma coleção de quartos. O indexador de blobs detecta as coleções e reflete a estrutura dos documentos de entrada no esquema de índice.
Analisar matrizes JSON
Uma alternativa é usar a matriz JSON. Essa opção é útil quando os blobs contêm uma matriz de objetos JSON bem formados e você deseja que cada elemento da matriz se torne um documento de pesquisa separado. Usando jsonArrays, o blob JSON a seguir produz três documentos separados, cada um com os campos "id" e "text".
[
{ "id" : "1", "text" : "example 1" },
{ "id" : "2", "text" : "example 2" },
{ "id" : "3", "text" : "example 3" }
]
A propriedade parameters no indexador contém valores de modos de análise. Para uma matriz JSON, a definição do indexador deve ser semelhante ao exemplo a seguir.
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" } }
}
Exemplo de jsonArrays
O conjunto de dados JSON da Filarmônica de Nova York no GitHub é útil para testar a análise de matriz JSON. Você pode carregar os arquivos de dados no Armazenamento de Blobs e usar o Assistente para importação de dados para avaliar rapidamente como esse conteúdo é analisado em documentos de pesquisa individuais.
O conjunto de dados consiste em oito blobs, cada um contendo uma matriz JSON de entidades, totalizando 100 entidades. As entidades variam de acordo com os campos que são populados, mas o resultado final é um documento de pesquisa por entidade, de todas as matrizes, em todos os blobs.
Analisando matrizes JSON aninhadas
Em matrizes JSON com elementos aninhados, é possível especificar um documentRoot para indicar uma estrutura de vários níveis. Por exemplo, se o seu blob tiver esta aparência:
{
"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" }
]
}
}
Use esta configuração para indexar a matriz contida na propriedade level2:
{
"name" : "my-json-array-indexer",
... other indexer properties
"parameters" : { "configuration" : { "parsingMode" : "jsonArray", "documentRoot" : "/level1/level2" } }
}
Analisar entidades JSON separadas por novas linhas
Se o blob contiver várias entidades JSON separadas por uma nova linha e você quiser que cada elemento se torne um documento de pesquisa separado, use jsonLines.
{ "id" : "1", "text" : "example 1" }
{ "id" : "2", "text" : "example 2" }
{ "id" : "3", "text" : "example 3" }
Em linhas JSON, a definição de indexador deve ser semelhante ao exemplo a seguir.
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" } }
}
Mapear campos JSON para campos de pesquisa
Os mapeamentos de campo associam um campo de origem a um campo de destino em situações em que os nomes e tipos de campo não são idênticos. Mas os mapeamentos de campo também podem ser usados para corresponder partes de um documento JSON e "refazê-las" em campos de nível superior do documento de pesquisa.
O exemplo a seguir ilustra esse cenário. Para obter mais informações sobre mapeamentos de campo em geral, confira Mapeamentos de campo.
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2016-04-13"
"tags" : [ "search", "storage", "howto" ]
}
}
Digamos que você tenha um índice de pesquisa com os seguintes campos: text do tipo Edm.String, date do tipo Edm.DateTimeOffset e tags do tipo Collection(Edm.String). Observe a discrepância entre "data de publicação" na fonte e campo date no índice. Para mapear seu JSON para a forma desejada, use os seguintes mapeamentos de campo:
"fieldMappings" : [
{ "sourceFieldName" : "/article/text", "targetFieldName" : "text" },
{ "sourceFieldName" : "/article/datePublished", "targetFieldName" : "date" },
{ "sourceFieldName" : "/article/tags", "targetFieldName" : "tags" }
]
Os campos de origem são especificados por meio da notação JSON Pointer. Comece com uma barra invertida para referir-se à raiz do documento JSON, então selecione a propriedade desejada (em nível arbitrário de aninhamento) usando um caminho separado por barra invertida.
Você também pode se referir a elementos individuais da matriz usando um índice com base em zero. Por exemplo, para selecionar o primeiro elemento da matriz "tags" do exemplo anterior, use um mapeamento de campo como este:
{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }
Observação
Caso "sourceFieldName" faça referência a uma propriedade que não existe no blob JSON, esse mapeamento será ignorado sem um erro. Esse comportamento permite que a indexação continue para blobs JSON que tenham um esquema diferente (que é um caso de uso comum). Como não há verificação de validação, confira cuidadosamente se há erros de digitação nos mapeamentos para que você não perca documentos pelo motivo errado.