Indexar blobs JSON e arquivos no Azure AI Search
Aplica-se a: Indexadores de Blob, Indexadores de arquivo
Para indexação de blob no Azure AI Search, este 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 uma destas formas:
- Um único documento JSON
- Um documento JSON contendo uma matriz de elementos JSON bem formados
- Um documento JSON contendo várias entidades, separadas por uma nova linha
O indexador de blob fornece um parsingMode parâmetro 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 | Description |
|---|---|---|
json |
Um por blob | (padrão) Analisa blobs JSON como um único pedaço de texto. Cada blob JSON torna-se um único documento de pesquisa. |
jsonArray |
Múltiplos por blob | Analisa uma matriz JSON no blob, onde 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 após cada nova linha. |
Para ambos e jsonLinesjsonArray , você deve revisar Indexação de um blob para produzir muitos documentos de pesquisa para entender como o indexador de blob lida com a desambiguação da chave do documento para vários documentos de pesquisa produzidos a partir do mesmo blob.
Dentro da definição do indexador, você pode, opcionalmente, definir mapeamentos de campo para escolher quais propriedades do documento JSON de origem são usadas para preencher seu índice de pesquisa de destino. Por exemplo, ao usar o jsonArray modo de análise, se a matriz existir como uma propriedade de nível inferior, você poderá definir uma propriedade "documentRoot" indicando onde a matriz é colocada dentro do blob.
Nota
Quando um modo de análise JSON é usado, o Azure AI Search assume que todos os blobs usam o mesmo analisador (para json, jsonArray ou jsonLines). Se você tiver uma combinação de diferentes tipos de arquivo na mesma fonte de dados, considere o uso de filtros de extensão de arquivo para controlar quais arquivos são importados.
As seções a seguir descrevem cada modo com mais detalhes. Se você não estiver familiarizado com clientes e conceitos de indexador, consulte Criar um indexador de pesquisa. Você também deve estar familiarizado com os detalhes da configuração básica do indexador de blob, que não é repetida aqui.
Indexar documentos JSON únicos (um por blob)
Por padrão, os indexadores de blob analisam blobs JSON como um único pedaço de texto, um documento de pesquisa para cada blob em um contêiner. Se o JSON estiver estruturado, o documento de pesquisa poderá refletir essa estrutura, com elementos individuais representados como campos individuais. Por exemplo, suponha que você tenha o seguinte documento JSON no Armazenamento de Blob 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 blob analisa o documento JSON em um único documento de pesquisa, carregando um índice combinando "text", "datePublished" e "tags" da origem em relação aos campos de índice de destino com nomes idênticos e digitados. Dado um índice com campos "text", "datePublished" e "tags", o indexador de blob pode inferir o mapeamento correto sem um mapeamento de campo presente na solicitação.
Embora o comportamento padrão seja um documento de pesquisa por blob JSON, definir o json modo de análise altera os mapeamentos de campo interno para conteúdo, promovendo campos dentro content para campos reais no índice de pesquisa. Um exemplo de definição de indexador para o json modo de análise 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" } }
}
Nota
Como acontece com todos os indexadores, se os campos não corresponderem claramente, você deve esperar especificar explicitamente mapeamentos de campos individuais, a menos que esteja usando os mapeamentos de campos implícitos disponíveis para conteúdo de blob e metadados, conforme descrito na configuração básica do indexador de blob.
Exemplo json (arquivos JSON de hotel único)
O conjunto de dados do documento JSON do hotel no GitHub é útil para testar a análise JSON, onde cada blob representa um arquivo JSON estruturado. Você pode carregar os arquivos de dados para o Armazenamento de Blobs e usar o assistente Importar 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 do hotel com uma coleção de endereços e uma coleção de quartos. O indexador de blob deteta ambas as coleções e reflete a estrutura dos documentos de entrada no esquema de índice.
Analisar matrizes JSON
Como alternativa, você pode usar a opção de matriz JSON. Essa opção é útil quando os blobs contêm uma matriz de objetos JSON bem formados e você deseja que cada elemento se torne um documento de pesquisa separado. Usando jsonArrayso , o blob JSON a seguir produz três documentos separados, cada um com "id" e "text" campos.
[
{ "id" : "1", "text" : "example 1" },
{ "id" : "2", "text" : "example 2" },
{ "id" : "3", "text" : "example 3" }
]
A parameters propriedade no indexador contém valores de modo 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 para o armazenamento de Blob e usar o assistente Importar 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, para um total de 100 entidades. As entidades variam quanto aos campos que são preenchidos, mas o resultado final é um documento de pesquisa por entidade, de todas as matrizes, em todos os blobs.
Análise de matrizes JSON aninhadas
Para matrizes JSON com elementos aninhados, você pode especificar a documentRoot para indicar uma estrutura de vários níveis. Por exemplo, se os seus blobs tiverem 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 level2 propriedade:
{
"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" }
Para linhas 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" : "jsonLines" } }
}
Mapear campos JSON para pesquisar campos
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 "elevá-las" para 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, consulte mapeamentos de campo.
{
"article" : {
"text" : "A hopefully useful article explaining how to parse JSON blobs",
"datePublished" : "2016-04-13"
"tags" : [ "search", "storage", "howto" ]
}
}
Suponha um índice de pesquisa com os seguintes campos: text do tipo Edm.String, date do tipo Edm.DateTimeOffsete tags do tipo Collection(Edm.String). Observe a discrepância entre "datePublished" na fonte e date no campo 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 usando a notação de ponteiro JSON. Você começa com uma barra para fazer referência à raiz do documento JSON e, em seguida, escolhe a propriedade desejada (no nível arbitrário de aninhamento) usando o caminho separado por barra para frente.
Você também pode fazer referência a elementos de matriz individuais usando um índice baseado em zero. Por exemplo, para escolher o primeiro elemento da matriz "tags" do exemplo acima, use um mapeamento de campo como este:
{ "sourceFieldName" : "/article/tags/0", "targetFieldName" : "firstTag" }
Nota
Se "sourceFieldName" se referir a uma propriedade que não existe no blob JSON, esse mapeamento será ignorado sem erro. Esse comportamento permite que a indexação continue para blobs JSON que têm um esquema diferente (que é um caso de uso comum). Como não há verificação de validação, verifique os mapeamentos cuidadosamente em busca de erros de digitação para que você não esteja perdendo documentos pelo motivo errado.