Руководство: Индексация вложенных JSON-объектов типа BLOB из службы хранилища Azure с помощью REST

2025-04-22

Поиск ИИ Azure может индексировать документы и массивы JSON в Хранилище BLOB-объектов Azure с помощью индексатора, который знает, как считывать полуструктурированные данные. Полуструктурированные данные содержат теги или маркировки, которые разделяют содержимое в данных. Она разделяет разницу между неструктурированными данными, которые должны быть полностью индексированы и формально структурированными данными, которые соответствуют модели данных, например схеме реляционной базы данных, которая может быть индексирована на основе каждого поля.

В этом руководстве показано, как индексировать вложенные массивы JSON с помощью клиента REST и REST API поиска :

Настройка примеров данных и настройка azureblob источника данных
Создание индекса поиска ИИ Azure для хранения содержимого, доступного для поиска
Создание и запуск индексатора для чтения контейнера и извлечения содержимого, доступного для поиска
Поиск по индексу, который вы только что создали.

Требования

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Хранилище Azure.
Поиск по искусственному интеллекту Azure. Создайте службу или найдите существующую службу в текущей подписке.
Visual Studio Code с клиентом REST.

Примечание.

Вы можете использовать бесплатную службу поиска для этого руководства. Уровень "Бесплатный" ограничивается тремя индексами, тремя индексаторами и тремя источниками данных. В этом руководстве создается по одному объекту из каждой категории. Перед началом работы убедитесь, что у вас есть место в службе, чтобы принять новые ресурсы.

Загрузка файлов

Скачайте ZIP-файл примера репозитория данных и извлеките его содержимое. Инструкции.

Нью-Йоркская филармония бесплатно

Пример данных — это один JSON-файл, содержащий массив JSON и 1521 вложенные элементы JSON. Данные исходят из истории выступлений Нью-Йоркской филармонии на Kaggle. Мы выбрали один JSON-файл, чтобы оставаться в пределах хранилища уровня "Бесплатный".

Вот первый вложенный JSON-объект в файле. Оставшаяся часть файла содержит 1,520 других записей концертных выступлений.

    {
      "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": []
        }
      ]
    }

Загрузка примерных данных в службу хранилища Azure

В службе хранилища Azure создайте новый контейнер с именем ny-philharmonic-free.
Отправьте примеры файлов данных.
Получите строку подключения хранилища, чтобы настроить подключение в службе Azure AI Search.
1. В левой части экрана выберите ключи доступа.
2. Скопируйте строку подключения для первого или второго ключа. Строка подключения аналогична следующему примеру:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Копирование URL-адреса службы поиска и ключа API

Для этого руководства подключения к службе "Поиск ИИ Azure" требуют конечную точку и ключ API. Эти значения можно получить из портал Azure. Способы альтернативного подключения смотрите в разделе «Управляемые удостоверения».

Войдите в портал Azure, перейдите на страницу обзора службы поиска и скопируйте URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.
В разделе Параметры>Ключи скопируйте ключ администратора. Ключи администратора используются для добавления, изменения и удаления объектов. Существует два взаимозаменяемых ключа администратора. Скопируйте любой из них.

Настройка REST-файла

Запустите Visual Studio Code и создайте новый файл.

Укажите значения переменных, используемых в запросе.

@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

Сохраните файл с помощью .rest расширения или .http расширения.

Дополнительные сведения о клиенте REST см. в кратком руководстве. Полнотекстовый поиск с помощью REST.

Создание источника данных

Создание источника данных (REST) создает подключение к источнику данных, указывающее, какие данные следует индексировать.

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

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

Отправьте запрос. Результат должен выглядеть следующим образом:

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://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net:443/datasources('ny-philharmonic-ds')?api-version=2024-07-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://<YOUR-SEARCH-SERVICE-NAME>.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
}

Создание индекса

Создание индекса (REST) создает индекс поиска в службе поиска. Индекс указывает все параметры и их атрибуты.

Для вложенных json поля индекса должны совпадать с исходными полями. В настоящее время поиск ИИ Azure не поддерживает сопоставления полей с вложенным JSON, поэтому имена полей и типы данных должны полностью соответствовать. Следующий индекс соответствует элементам JSON в необработанном содержимом.

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-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 }
          ]
        }
      ]
    }

Основные моменты:

Сопоставления полей нельзя использовать для согласования различий в именах полей или типах данных. Эта схема индекса предназначена для зеркального отображения необработанного содержимого.
Вложенный JSON моделиируется как Collection(Edm.ComplextType). В необработанном контенте есть несколько концертов для каждого сезона, и несколько работ для каждого концерта. Для работы с этой структурой используйте коллекции для сложных типов данных.
В необработанном содержимом Date и Time являются строками, поэтому соответствующие типы данных в индексе также являются строками.

Создание и запуск индексатора

Создать индексатор позволяет создать индексатор в вашей службе поиска. Индексатор подключается к источнику данных, загружает и индексирует данные, а также предоставляет расписание для автоматизации обновления данных.

Конфигурация индексатора включает jsonArray режим синтаксического анализа и documentRoot.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-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" : [ 
      ]
    }

Основные моменты:

Необработанный файл содержимого содержит массив JSON ("programs") с 1526 вложенными структурами JSON. Установите parsingMode на jsonArray, чтобы сообщить индексатору, что каждый blob содержит массив JSON. Поскольку вложенный JSON начинается на уровне ниже, установите documentRoot на /programs.
Индексатор работает несколько минут. Дождитесь завершения выполнения индексатора перед выполнением любых запросов.

Выполнение запросов

Вы можете начать поиск сразу после загрузки первого документа.

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

Отправьте запрос. Это неопределенный полнотекстовый поисковый запрос, который возвращает все поля, помеченные как извлекаемые в индексе, а также число документов. Результат должен выглядеть следующим образом:

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://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes('ny-philharmonic-index')/$metadata#docs(*)",
  "@odata.count": 1521,
  "@search.nextPageParameters": {
    "search": "*",
    "count": true,
    "skip": 50
  },
  "value": [
  ],
  "@odata.nextLink": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/ny-philharmonic-index/docs/search?api-version=2024-07-01"
}

Добавьте параметр search для поиска по строке, параметр select для ограничения результатов до меньшего количества полей и параметр filter для дальнейшего сужения поиска.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2024-07-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'"
  }

В ответе возвращаются два документа.

Для фильтров можно также использовать логические операторы (и, не) и операторы сравнения (eq, ne, lt, ge, le). Сравнение строк чувствительно к регистру. Дополнительные сведения и примеры см. в разделе "Создание запроса".

Примечание.

Параметр $filter работает только в полях, которые были помечены фильтруемыми во время создания индекса.

Сброс и повторный запуск

Индексаторы можно сбросить, чтобы очистить историю выполнения, что позволяет полностью повторить выполнение. Следующие запросы POST предназначены для сброса, за которым следует повторно запустить.

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

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

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

Очистка ресурсов

Если вы работаете в рамках своей подписки, после завершения проекта целесообразно удалить ресурсы, которые вам больше не нужны. Ресурсы, оставленные работающими, могут стоить вам денег. Вы можете удалить ресурсы по отдельности либо удалить всю группу ресурсов.

Вы можете использовать портал Azure для удаления индексов, индексаторов и источников данных.

Следующие шаги

Теперь, когда вы знакомы с основами индексирования BLOB-объектов Azure, ознакомьтесь с конфигурацией индексатора для BLOB-объектов JSON в службе хранилища Azure:

Настройка индексирования больших двоичных объектов JSON.