문서 추가, 업데이트 또는 삭제(Azure AI Search REST API)
HTTP POST를 사용하여 검색 문서를 지정된 인덱스로 가져올 수 있습니다. 대규모 업데이트의 경우 일괄 처리(일괄 처리당 최대 1,000개 문서 또는 일괄 처리당 약 16MB)를 권장하며 인덱싱 성능이 크게 향상됩니다.
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 데이터 원본의 경우 인덱서는 문서를 추가하고 업데이트하기 위한 더 간단한 대안을 제공합니다. 자세한 내용은 인덱서 작업을 참조하세요.
URI 매개 변수
| 매개 변수 | Description |
|---|---|
| 서비스 이름 | 필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다. |
| 인덱스 이름 | 문서를 게시할 인덱스 지정을 지정하는 URI에 필요합니다. 문서는 한 번에 하나의 인덱스에만 게시할 수 있습니다. |
| api-version | 필수 사항입니다. 현재 안정적인 버전은 입니다 api-version=2020-06-30. 더 많은 버전은 API 버전을 참조하세요. |
요청 헤더
다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.
| 필드 | Description |
|---|---|
| 콘텐츠 형식 | 필수 사항입니다.
application/json
|
| api-key | Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. api-key는 검색 서비스에 대한 요청을 인증하는 고유한 시스템 생성 문자열입니다. 문서를 업로드하려면 관리자 API 키가 필요합니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요. |
요청 본문
요청 본문에는 인덱싱할 하나 이상의 문서가 포함됩니다. 문서는 고유한 대/소문자 구분 키로 식별됩니다. 각 문서는 "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)
...
},
...
]
}
| 속성 | Description |
|---|---|
| @search.action | 필수 사항입니다. 유효한 값은 "upload", "delete", "merge" 또는 "mergeOrUpload"입니다. 기본값은 "업로드"입니다. 동일한 일괄 처리로 문서당 하나씩 작업을 결합할 수 있습니다.
"업로드": 업로드 작업은 문서가 새로 추가된 경우 삽입되고 문서가 있는 경우 업데이트/교체되는 'upsert'와 유사합니다. 업데이트 사례에서 모든 필드가 대체됩니다. "delete": Delete는 인덱스에서 지정된 문서를 제거합니다. 키 필드를 제외한 삭제 작업에서 지정한 모든 필드는 무시됩니다. 문서에서 개별 필드를 제거하려면 대신 를 사용하고 merge 필드를 명시적으로 로 null설정합니다.
"mergeOrUpload": 지정된 키가 있는 문서가 인덱스에 이미 있는 경우 이 작업은 병합처럼 동작합니다. 문서가 없으면 새 문서를 업로드하는 것처럼 동작합니다. "merge": 병합은 지정된 필드로 기존 문서를 업데이트합니다. 문서가 없으면 병합이 실패합니다. 문서의 기존 필드는 병합에서 지정하는 필드로 바뀝니다. 이는 기본 형식 및 복합 형식의 컬렉션에도 적용됩니다. 기본 컬렉션에서 문서에 값이 ["budget"]인 Collection(Edm.String) 형식의 태그 필드가 포함되어 있고 태그에 대해 ["economy", "pool"] 값으로 병합을 실행하는 경우 태그 필드의 최종 값은 ["economy", "pool"]입니다. ["budget", "economy", "pool"]이 아닌 ["economy", "pool"]이 됩니다. 복합 컬렉션에서 문서에 값이 [{ "Type": "Budget Room"인 Rooms라는 복합 컬렉션 필드가 포함되어 있으면 "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 }](추가 요소) [{ "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 | 문서가 성공적으로 수정되었거나 삭제되었습니다. | 해당 없음 | 삭제 작업은 idempotent입니다. 즉, 인덱스에서 문서 키가 없더라도 해당 키를 사용하여 삭제 작업을 시도하면 200 상태 코드가 생성됩니다. |
| 201 | 문서를 성공적으로 만들었습니다. | 해당 없음 | |
| 400 | 인덱싱되는 것을 방지하는 문서에 오류가 발생했습니다. | No | 응답의 오류 메시지는 문서에 무엇이 잘못되었음을 나타냅니다. |
| 404 | 지정된 키가 인덱스 안에 없기 때문에 문서를 병합할 수 없습니다. | No | 이 오류는 새 문서를 만들기 때문에 업로드에 대해 발생하지 않으며, idempotent이기 때문에 삭제에 대해 발생하지 않습니다. |
| 409 | 문서를 인덱싱하려고 할 때 버전 충돌이 감지되었습니다. | Yes | 동일한 문서를 동시에 한 번 이상 인덱싱하려고 하는 경우 발생할 수 있습니다. |
| 422 | 'true'로 설정된 'allowIndexDowntime' 플래그가 업데이트되었으므로 인덱스를 일시적으로 사용할 수 없습니다. | Yes | |
| 503 | 큰 부하로 인해 검색 서비스를 일시적으로 사용할 수 없습니다. | Yes | 이 경우 다시 시도하기 전에 코드는 대기해야 합니다. 그렇지 않으면 서비스 사용 불가가 연장될 위험이 있습니다. |
참고
클라이언트 코드에서 207 응답이 자주 반환된다면 시스템의 부하가 높아서 일 수 있습니다. 503에 대한 statusCode 속성을 통해 시스템 부하가 원인인지 확인할 수 있습니다. 시스템 부하가 원인이라면 인덱싱 요청을 제한하는 것이 좋습니다. 인덱싱 트래픽이 감소하지 않는 경우에는 시스템에서 모든 요청을 거부하며 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 AI Search는 이러한 값을 UTC로 정규화합니다. 예를 들어 2019-01-13T14:03:00-08:00은 2019-01-13T22:03:00Z로 저장됩니다. 표준 시간대 정보를 저장해야 하는 경우 인덱스에 추가 열을 추가해야 합니다.