Добавление, обновление и удаление документов (REST API поиска Azure)
Вы можете импортировать документы поиска в указанный индекс с помощью HTTP POST. Для большого обновления рекомендуется пакетная обработка (до 1000 документов на пакет или около 16 МБ на пакет) и значительно повысит производительность индексирования.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Для поддерживаемых источников данных Azure индексаторы предлагают более простую альтернативу для добавления и обновления документов. Дополнительные сведения см. в статье Indexer operations (Azure Search Service REST API) (Операции индексатора (REST API службы "Поиск Azure")).
Параметры URI
| Параметр | Описание |
|---|---|
| имя службы | Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска. |
| имя индекса | Требуется в универсальном коде ресурса (URI) с указанием индекса для публикации документов. За один раз можно отправить документы только в один индекс. |
| api-version | Обязательный. Текущая стабильная версия — api-version=2020-06-30. Дополнительные версии см. в разделе Версии API . |
Заголовки запросов
Таблица ниже содержит обязательные и необязательные заголовки запроса.
| Поля | Описание |
|---|---|
| Content-Type | Обязательный. Для этого заголовка необходимо задать значение application/json |
| api-key | Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса к службе поиска. Для отправки документов требуется ключ API администратора. Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу . |
Текст запроса
Тело запроса содержит один или несколько индексируемых документов. Документы идентифицируются уникальным ключом с учетом регистра. Каждый документ связан с действием: "upload", "delete", "merge" или "mergeOrUpload". Запросы на добавление должны содержать данные документа в виде набора пар "ключ/значение".
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema)
...
},
...
]
}
| Свойство | Описание |
|---|---|
| @search.action | Обязательный. Допустимые значения: upload, delete, merge или mergeOrUpload. По умолчанию используется значение "upload". В одном пакете можно объединить действия по одному для каждого документа. "upload": действие отправки похоже на "upsert", где документ будет вставлен, если он новый, и обновлен или заменен, если он существует. Все поля заменяются в случае обновления. "delete": удаление удаляет указанный документ из индекса. Все поля, указанные в операции удаления, кроме ключевого, будут игнорироваться. Если вы хотите удалить отдельное поле из документа, используйте merge вместо него и задайте для поля явное значение null. mergeOrUpload: это действие выполняется как слияние, если документ с заданным ключом уже существует в индексе. Если документ не существует, он ведет себя как отправка с новым документом. "merge": слияние обновляет существующий документ с указанными полями. Если документ не существует, слияние завершается ошибкой. Поля, указанные в запросе на объединение, заменяют собой существующие поля документа. Это также относится к коллекциям примитивных и сложных типов. Если в примитивных коллекциях документ содержит поле Tags типа Collection(Edm.String) со значением ["бюджет"], и выполняется слияние со значением ["экономика", "пул"] для тега, конечное значение поля Tags будет равно ["экономика", "пул"]. Оно не будет ["бюджет", "экономика", "пул"]. В сложных коллекциях, если документ содержит сложное поле коллекции с именем Rooms со значением [{ "Type": "Budget Room", "BaseRate": 75.0 }], и выполняется слияние со значением [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], окончательное значение поля Комнаты будет [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Это не будет ни одно из следующих значений: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (add elements) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60,5 }] (объединить элементы по порядку, а затем добавить дополнительные компоненты) |
| key_field_name | Обязательный. Определение поля в индексе, которое служит ключом документа и содержит только уникальные значения. Ключи документов могут содержать только буквы, цифры, дефисы ("-"), символы подчеркивания ("_") и знаки равенства ("=") и учитывать регистр. Дополнительные сведения см. в разделе Правила именования. |
| field_name | Обязательный. Пары "имя-значение", где имя поля соответствует имени поля в определении индекса. Значение определяется пользователем, но должно быть допустимым для типа поля. |
Примечание
Нет гарантий упорядочения, для которого действие в тексте запроса выполняется первым. Не рекомендуется иметь несколько действий слияния, связанных с одним и тем же документом в одном тексте запроса. Если для одного документа требуется несколько действий слияния, выполните слияние на стороне клиента перед обновлением документа в индексе поиска.
Ответ
Код состояния: для успешного ответа возвращается значение 200. Это означает, что все элементы сохранены и начнут индексироваться. Индексирование выполняется в фоновом режиме и делает новые документы доступными (то есть доступными для запроса и поиска) через несколько секунд после завершения операции индексирования. Конкретная задержка зависит от нагрузки на службу.
Успешное индексирование определяется свойством состояния, для которых задано значение true для всех элементов, а для свойства statusCode задано значение 201 (для вновь отправленных документов) или 200 (для объединенных или удаленных документов):
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
Код состояния: возвращается значение 207, если по крайней мере один элемент не был успешно проиндексирован. Для элементов, которые не были проиндексированы, поле состояния имеет значение false. Свойства errorMessage и statusCode указывают причину ошибки индексирования:
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
Свойство errorMessage указывает причину ошибки индексирования, если это возможно.
В следующей таблице описаны различные коды состояния для каждого документа, которые могут быть возвращены в ответе. Некоторые коды состояния указывают на проблемы с самим запросом, а другие — на временные ошибки. Во втором случае нужно повторить попытку подключения через некоторое время.
| Код состояния | Значение | Возможности повторной попытки | Примечания |
|---|---|---|---|
| 200 | Документ был успешно изменен или удален. | Недоступно | Операции удаления являются идемпотентными. Это значит, что даже если ключ документа не существует в индексе, попытка выполнить операцию удаления с этим ключом приведет к коду состояния 200. |
| 201 | Документ создан. | Недоступно | |
| 400 | Ошибка в документе, препятствующая индексированию. | Нет | Сообщение об ошибке в ответе указывает, что не так с документом. |
| 404 | Не удалось объединить документ, так как указанный ключ не существует в индексе. | Нет | Эта ошибка не возникает при отправке, так как они создают новые документы, и не возникает при удалении, так как они идемпотентны. |
| 409 | Обнаружен конфликт версий при попытке индексирования документа. | Да | Это может произойти при нескольких одновременных попытках индексирования одного документа. |
| 422 | Индекс временно недоступен, так как для флага allowIndexDowntime было установлено значение true. | Да | |
| 503 | Служба поиска временно недоступна, возможно, из-за высокой нагрузки. | Да | Следует подождать, прежде чем предпринимать повторную попытку. В противном случае вы можете только увеличить время недоступности службы. |
Примечание
Если ваш код клиента часто сталкивается с ответом "207", одной из возможных причин может быть загрузка системы. Чтобы выяснить, так ли это, проверьте, не имеет ли свойство statusCode значение 503. Если это так, рекомендуется регулирование запросов индексирования. В противном случае если поток запросов на индексирование не уменьшится, система может начать отклонять их все с кодом ошибки 503.
Код состояния: если превышено разрешенное количество документов в индексе, система возвращает код ошибки 429. В этом случае нужно создать новый индекс или повысить предельную емкость.
Примеры
Пример. Отправка двух полностью определенных документов
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
Примечание
При отправке DateTimeOffset значений со сведениями о часовом поясе в индекс поиск ИИ Azure нормализует эти значения в формате UTC. Например, 2019-01-13T14:03:00-08:00 будет храниться как 2019-01-13T22:03:00Z. Если вам нужно сохранить сведения о часовом поясе, необходимо добавить в индекс дополнительный столбец.