Tutorial: indexar blobs JSON aninhados do Armazenamento do Azure usando a REST

Artigo
03/21/2024

A IA do Azure Search pode indexar documentos e matrizes JSON no Armazenamento de Blobs do Azure usando um indexador que sabe ler dados semiestruturados. Dados semi-estruturados contêm marcas ou marcações que separam o conteúdo dentro dos dados. Ele divide a diferença entre dados não estruturados, que devem ser totalmente indexados e dados formalmente estruturados que aderem a um modelo de dados, como um esquema de banco de dados relacional que pode ser indexado por campo.

Este tutorial mostra como indexar matrizes JSON aninhadas. Ele usa um cliente REST e as APIs REST de Pesquisa para executar as seguintes tarefas:

Configurar dados de exemplo e configurar uma fonte de dados azureblob
Criar um índice da IA do Azure Search para conter conteúdo pesquisável
Criar e executar um indexador para ler o contêiner e extrair conteúdo pesquisável
Pesquisar no índice que você acabou de criar

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Visual Studio Code com um cliente REST.
Armazenamento do Azure
Pesquisa de IA do Azure. Crie ou localize um recurso existente da Pesquisa de IA do Azure em sua assinatura atual.

Observação

Use o serviço gratuito para este tutorial. Um serviço de pesquisa gratuito limita você a três índices, três indexadores e três fontes de dados. Este tutorial cria um de cada. Antes de começar, reserve um espaço no seu serviço para aceitar os novos recursos.

Baixar arquivos

Baixe um arquivo zip do repositório de dados de exemplo e extraia o conteúdo. Saiba como.

ny-philharmonic-free

Dados de exemplo são um único arquivo JSON que contém uma matriz JSON e 1.521 elementos JSON aninhados. Os dados de exemplo são originados de Histórico de Desempenho filarmônica de NY no Kaggle. Escolhemos um arquivo JSON para ficar abaixo dos limites de armazenamento da camada gratuita.

Aqui está o primeiro JSON aninhado no arquivo. O restante do arquivo inclui 1.520 outras instâncias de apresentações de concerto.

    {
      "id": "7358870b-65c8-43d5-ab56-514bde52db88-0.1",
      "programID": "11640",
      "orchestra": "New York Philharmonic",
      "season": "2011-12",
      "concerts": [
        {
          "eventType": "Non-Subscription",
          "Location": "Manhattan, NY",
          "Venue": "Avery Fisher Hall",
          "Date": "2011-09-07T04:00:00Z",
          "Time": "7:30PM"
        },
        {
          "eventType": "Non-Subscription",
          "Location": "Manhattan, NY",
          "Venue": "Avery Fisher Hall",
          "Date": "2011-09-08T04:00:00Z",
          "Time": "7:30PM"
        }
      ],
      "works": [
        {
          "ID": "5733*",
          "composerName": "Bernstein,  Leonard",
          "workTitle": "WEST SIDE STORY (WITH FILM)",
          "conductorName": "Newman, David",
          "soloists": []
        },
        {
          "ID": "0*",
          "interval": "Intermission",
          "soloists": []
        }
      ]
    }

Carregar dados de exemplo para o Armazenamento do Microsoft Azure

No Armazenamento do Azure, crie um novo contêiner e nomeie-o ny-philharmonic-free.
Faça upload dos arquivos de dados de amostra.
Obtenha uma cadeia de conexão de armazenamento para que você possa formular uma conexão na Pesquisa de IA do Azure.
1. À esquerda, selecione Teclas de acesso.
2. Copie a cadeia de conexão para a chave um ou para a chave dois. A cadeia de conexão é semelhante ao seguinte exemplo:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Copiar uma URL do serviço de pesquisa e uma chave de API

Para esse tutorial, as conexões com a Pesquisa de IA do Azure exigem um ponto de extremidade e uma chave de API. Você pode obter esses valores no portal do Azure.

Entre no portal do Azure, navegue até a página Visão geral do serviço de pesquisa e copie a URL. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.
Em Configurações>Chaves, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas.

Configure seu arquivo REST

Iniciar o Visual Studio Code e criar um novo arquivo

Forneça valores para variáveis usadas na solicitação:

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE

Salve o arquivo usando uma extensão de nome de arquivo .rest ou .http.

Veja Guia de Início Rápido: pesquisa de texto usando REST se precisar de ajuda com o cliente REST.

Criar uma fonte de dados

Criar fonte de dados (REST) cria uma conexão de fonte de dados que especifica quais dados indexar.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name" : "ny-philharmonic-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Enviar a solicitação. A resposta deve ser semelhante a:

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
ETag: "0x8DC43A5FDB8448F"
Location: https://free-demo-search-svc.search.windows.net:443/datasources('ny-philharmonic-ds')?api-version=2023-11-01
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: 7ca53f73-1054-4959-bc1f-616148a9c74a
elapsed-time: 111
Date: Wed, 13 Mar 2024 21:38:58 GMT
Connection: close

{
  "@odata.context": "https://free-demo-search-svc.search.windows.net/$metadata#datasources/$entity",
  "@odata.etag": "\"0x8DC43A5FDB8448F\"",
  "name": "ny-philharmonic-ds",
  "description": null,
  "type": "azureblob",
  "subtype": null,
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "ny-philharmonic-free",
    "query": null
  },
  "dataChangeDetectionPolicy": null,
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null
}

Crie um índice

Criar índice (REST) cria um índice de pesquisa em seu serviço de pesquisa. Um índice especifica todos os parâmetros e seus atributos.

Para JSON aninhado, os campos de índice devem ser idênticos aos campos de origem. Atualmente, a Pesquisa de IA do Azure não dá suporte a mapeamentos de campo para JSON aninhado. Por esse motivo, os nomes de campo e os tipos de dados devem corresponder completamente. O índice a seguir se alinha aos elementos JSON no conteúdo bruto.

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
      "name": "ny-philharmonic-index",  
      "fields": [
        {"name": "programID", "type": "Edm.String", "key": true, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "orchestra", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "season", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        { "name": "concerts", "type": "Collection(Edm.ComplexType)", 
          "fields": [
            { "name": "eventType", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false},
            { "name": "Location", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Venue", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Date", "type": "Edm.String", "searchable": false, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Time", "type": "Edm.String", "searchable": false, "retrievable": true, "filterable": true, "sortable": false, "facetable": true }
          ]
        },
        { "name": "works", "type": "Collection(Edm.ComplexType)", 
          "fields": [
            { "name": "ID", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false},
            { "name": "composerName", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "workTitle", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "conductorName", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "soloists", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true }
          ]
        }
      ]
    }

Pontos principais:

Você não pode usar mapeamentos de campo para reconciliar diferenças em nomes de campo ou tipos de dados. Esse esquema de índice foi projetado para espelhar o conteúdo bruto.
O JSON aninhado é modelado como Collection(Edm.ComplextType). No conteúdo bruto, há vários concertos para cada temporada, e vários trabalhos para cada concerto. Para acomodar essa estrutura, use coleções para tipos complexos.
No conteúdo bruto, Date e Time são cadeias de caracteres, portanto, os tipos de dados correspondentes no índice também são cadeias de caracteres.

Criar e executar um indexador

Criar Indexador cria um indexador em seu serviço de pesquisa. Um indexador se conecta à fonte de dados, carrega e indexa dados e, opcionalmente, fornece um agendamento para automatizar a atualização de dados.

A configuração do indexador inclui o modo de análise jsonArray e um documentRoot.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
      "name" : "ny-philharmonic-indexer",
      "dataSourceName" : "ny-philharmonic-ds",
      "targetIndexName" : "ny-philharmonic-index",
      "parameters" : { 
        "configuration" : { 
          "parsingMode" : "jsonArray", "documentRoot": "/programs"}
        },
      "fieldMappings" : [ 
      ]
    }

Pontos principais:

O arquivo de conteúdo bruto contém uma matriz JSON ("programs") com 1.526 estruturas JSON aninhadas. Defina parsingMode para jsonArray para informar ao indexador que cada blob contém uma matriz JSON. Como o JSON aninhado inicia um nível abaixo, defina documentRoot como /programs.
O indexador é executado por vários minutos. Aguarde a conclusão da execução do indexador antes de executar as consultas.

Executar consultas

Você poderá iniciar a pesquisa assim que o primeiro documento for carregado.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "count": true
  }

Enviar a solicitação. Esta é uma consulta de pesquisa de texto completo não especificada que retorna todos os campos marcados como recuperáveis no índice, juntamente com uma contagem de documentos. A resposta deve ser semelhante a:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: a95c4021-f7b4-450b-ba55-596e59ecb6ec
elapsed-time: 106
Date: Wed, 13 Mar 2024 22:09:59 GMT
Connection: close

{
  "@odata.context": "https://free-demo-search-svc.search.windows.net/indexes('ny-philharmonic-index')/$metadata#docs(*)",
  "@odata.count": 1521,
  "@search.nextPageParameters": {
    "search": "*",
    "count": true,
    "skip": 50
  },
  "value": [
  ],
  "@odata.nextLink": "https://free-demo-search-svc.search.windows.net/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01"
}

Adicione um parâmetro search para pesquisar em uma cadeia de caracteres. Adicione um parâmetro select para limitar os resultados a menos campos. Adicione um filter para restringir ainda mais a pesquisa.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "puccini",
    "count": true,
    "select": "season, concerts/Date, works/composerName, works/workTitle",
    "filter": "season gt '2015-16'"
  }

Dois documentos são retornados na resposta.

Para filtros, você também pode usar operadores lógicos (e, ou não) e operadores de comparação (eq, ne, gt, lt, ge, le). Comparações de cadeia de caracteres diferenciam maiúsculas de minúsculas. Para obter mais informações e exemplos, consulte Criar uma consulta.

Observação

O parâmetro $filter funciona somente com campos que foram marcados como filtráveis na criação do índice.

Redefinir e execute novamente

Os indexadores podem ser redefinidos, desmarcando o histórico de execução, o que permite uma nova execução completa. As solicitações GET a seguir são para redefinição, seguidas de nova execução.

### Reset the indexer
POST {{baseUrl}}/indexers/ny-philharmonic-indexer/reset?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

### Run the indexer
POST {{baseUrl}}/indexers/ny-philharmonic-indexer/run?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

### Check indexer status 
GET {{baseUrl}}/indexers/ny-philharmonic-indexer/status?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é uma boa ideia remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. Você pode excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Use o portal para excluir índices, indexadores e fontes de dados.

Próximas etapas

Agora que você está familiarizado com os conceitos básicos da indexação de blobs do Azure, vamos examinar mais de perto a configuração do indexador para blobs JSON no Armazenamento do Azure.

Configurar a indexação de blob JSON