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

Статья
09/01/2024

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

В этом руководстве показано, как индексировать вложенные массивы JSON. Он использует клиент REST и ИНТЕРФЕЙСы REST API поиска для выполнения следующих задач:

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

Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

Необходимые компоненты

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

Примечание.

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

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

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

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

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

Ниже приведен первый вложенный JSON-файл. Оставшаяся часть файла содержит 1520 других экземпляров концертных выступлений.

    {
      "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".
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": "{{storageConnectionString}}"
        },
        "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 режим синтаксического анализа и a 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 сообщить индексатору, что каждый большой двоичный объект содержит массив 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 работает только в полях, которые были помечены фильтруемыми при создании индекса.

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

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

### 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, давайте подробнее рассмотрим конфигурацию индексатора для больших двоичных объектов JSON в службе хранилища Azure.

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

Поделиться через