Indexers - Create
새 인덱서를 만듭니다.
POST {endpoint}/indexers?api-version=2025-09-01
URI 매개 변수
| Name | In(다음 안에) | 필수 | 형식 | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string |
검색 서비스의 엔드포인트 URL입니다. |
|
api-version
|
query | True |
string |
클라이언트 API 버전입니다. |
요청 헤더
| Name | 필수 | 형식 | Description |
|---|---|---|---|
| x-ms-client-request-id |
string (uuid) |
디버깅을 돕기 위해 요청과 함께 전송된 추적 ID입니다. |
요청 본문
| Name | 필수 | 형식 | Description |
|---|---|---|---|
| dataSourceName | True |
string |
이 인덱서가 데이터를 읽는 데이터 원본의 이름입니다. |
| name | True |
string |
인덱서의 이름입니다. |
| targetIndexName | True |
string |
이 인덱서가 데이터를 쓰는 인덱스의 이름입니다. |
| @odata.etag |
string |
인덱서의 ETag입니다. |
|
| description |
string |
인덱서에 대한 설명입니다. |
|
| disabled |
boolean |
인덱서가 비활성화되었는지 여부를 나타내는 값입니다. 기본값은 false입니다. |
|
| encryptionKey |
Azure Key Vault에서 만드는 암호화 키에 대한 설명입니다. 이 키는 Microsoft를 포함한 누구도 암호를 해독할 수 없다는 완전한 확신을 원하는 경우 인덱서 정의(인덱서 실행 상태뿐만 아니라)에 대한 추가 수준의 미사용 암호화를 제공하는 데 사용됩니다. 인덱서 정의를 암호화한 후에는 항상 암호화된 상태로 유지됩니다. 검색 서비스는 이 속성을 null로 설정하려는 시도를 무시합니다. 암호화 키를 순환하려는 경우 필요에 따라 이 속성을 변경할 수 있습니다. 인덱서 정의(및 인덱서 실행 상태)는 영향을 받지 않습니다. 고객 관리형 키를 사용한 암호화는 무료 검색 서비스에서 사용할 수 없으며 2019년 1월 1일 이후에 생성된 유료 서비스에서만 사용할 수 있습니다. |
||
| fieldMappings |
데이터 원본의 필드와 인덱스의 해당 대상 필드 간의 매핑을 정의합니다. |
||
| outputFieldMappings |
출력 필드 매핑은 보강 후 인덱싱 직전에 적용됩니다. |
||
| parameters |
인덱서 실행을 위한 매개 변수입니다. |
||
| schedule |
이 인덱서의 일정입니다. |
||
| skillsetName |
string |
이 인덱서를 사용하여 실행하는 기술 집합의 이름입니다. |
응답
| Name | 형식 | Description |
|---|---|---|
| 201 Created | ||
| Other Status Codes |
오류 응답입니다. |
예제
SearchServiceCreateIndexer
샘플 요청
POST https://stableexampleservice.search.windows.net/indexers?api-version=2025-09-01
{
"name": "myindexer",
"description": "Description of the indexer",
"dataSourceName": "mydocdbdatasource",
"skillsetName": "myskillset",
"targetIndexName": "stable-test",
"schedule": {
"interval": "P1D",
"startTime": "2025-01-07T19:30:00Z"
},
"parameters": {
"batchSize": 10,
"maxFailedItems": 10,
"maxFailedItemsPerBatch": 5,
"configuration": {
"excludedFileNameExtensions": ".png,.mp4",
"indexedFileNameExtensions": ".docx,.pptx",
"failOnUnsupportedContentType": true,
"failOnUnprocessableDocument": false,
"indexStorageMetadataOnlyForOversizedDocuments": true,
"delimitedTextHeaders": "Header1,Header2",
"delimitedTextDelimiter": "|",
"firstLineContainsHeaders": true,
"documentRoot": "/root",
"dataToExtract": "storageMetadata",
"imageAction": "none",
"allowSkillsetToReadFileData": false,
"pdfTextRotationAlgorithm": "none",
"executionEnvironment": "standard"
}
},
"fieldMappings": [
{
"sourceFieldName": "/document",
"targetFieldName": "name",
"mappingFunction": {
"name": "base64Encode"
}
}
],
"outputFieldMappings": [
{
"sourceFieldName": "/document",
"targetFieldName": "name",
"mappingFunction": {
"name": "base64Encode"
}
}
],
"disabled": false,
"@odata.etag": "0x1234568AE7E58A1"
}
샘플 응답
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "myindexer",
"description": "Description of the indexer",
"dataSourceName": "mydocdbdatasource",
"skillsetName": "myskillset",
"targetIndexName": "stable-test",
"disabled": false,
"schedule": {
"interval": "P1D",
"startTime": "2024-06-06T00:01:50.265Z"
},
"parameters": {
"batchSize": 10,
"maxFailedItems": 10,
"maxFailedItemsPerBatch": 5,
"configuration": {
"excludedFileNameExtensions": ".png,.mp4",
"indexedFileNameExtensions": ".docx,.pptx",
"failOnUnsupportedContentType": true,
"failOnUnprocessableDocument": false,
"indexStorageMetadataOnlyForOversizedDocuments": true,
"delimitedTextHeaders": "Header1,Header2",
"delimitedTextDelimiter": "|",
"firstLineContainsHeaders": true,
"documentRoot": "/root",
"dataToExtract": "storageMetadata",
"imageAction": "none",
"allowSkillsetToReadFileData": false,
"pdfTextRotationAlgorithm": "none",
"executionEnvironment": "standard"
}
},
"fieldMappings": [
{
"sourceFieldName": "/document",
"targetFieldName": "name",
"mappingFunction": {
"name": "base64Encode"
}
}
],
"outputFieldMappings": [
{
"sourceFieldName": "/document",
"targetFieldName": "name",
"mappingFunction": {
"name": "base64Encode"
}
}
]
}
정의
| Name | Description |
|---|---|
|
Azure |
Azure Key Vault에 저장된 암호화 키에 대한 인증된 액세스에 사용되는 검색 서비스에 대해 만든 등록된 애플리케이션의 자격 증명입니다. |
|
Blob |
Azure Blob Storage에서 추출할 데이터를 지정하고 "imageAction"이 "none" 이외의 값으로 설정된 경우 이미지 콘텐츠에서 추출할 데이터를 인덱서에 알려줍니다. 이는 .PDF 또는 기타 애플리케이션에 포함된 이미지 콘텐츠 또는 Azure Blob의 .jpg 및 .png와 같은 이미지 파일에 적용됩니다. |
|
Blob |
Azure Blob Storage에서 포함된 이미지 및 이미지 파일을 처리하는 방법을 결정합니다. "imageAction" 구성을 "none" 이외의 값으로 설정하려면 기술 세트도 해당 인덱서에 연결해야 합니다. |
|
Blob |
Azure Blob 데이터 원본에서 인덱싱하기 위한 구문 분석 모드를 나타냅니다. |
|
Blob |
Azure Blob Storage의 PDF 파일에서 텍스트 추출을 위한 알고리즘을 결정합니다. |
|
Error |
리소스 관리 오류 추가 정보입니다. |
|
Error |
오류 세부 정보입니다. |
|
Error |
오류 응답 |
|
Field |
데이터 소스의 필드와 인덱스의 대상 필드 간의 맵핑을 정의합니다. |
|
Field |
인덱싱하기 전에 데이터 원본의 값을 변환하는 함수를 나타냅니다. |
|
Indexer |
인덱서를 실행해야 하는 환경을 지정합니다. |
|
Indexing |
인덱서 실행에 대한 매개 변수를 나타냅니다. |
|
Indexing |
인덱서 관련 구성 속성의 사전입니다. 각 이름은 특정 속성의 이름입니다. 각 값은 기본 형식이어야 합니다. |
|
Indexing |
인덱서 실행 일정을 나타냅니다. |
|
Search |
인덱서를 나타냅니다. |
|
Search |
Azure Key Vault의 고객 관리형 암호화 키입니다. 만들고 관리하는 키를 사용하여 인덱스 및 동의어 맵과 같은 미사용 데이터를 암호화하거나 복호화할 수 있습니다. |
AzureActiveDirectoryApplicationCredentials
Azure Key Vault에 저장된 암호화 키에 대한 인증된 액세스에 사용되는 검색 서비스에 대해 만든 등록된 애플리케이션의 자격 증명입니다.
| Name | 형식 | Description |
|---|---|---|
| applicationId |
string |
미사용 데이터를 암호화할 때 사용할 Azure Key Vault에 필요한 액세스 권한이 부여된 AAD 애플리케이션 ID입니다. 애플리케이션 ID를 AAD 애플리케이션의 개체 ID와 혼동해서는 안 됩니다. |
| applicationSecret |
string |
지정된 AAD 애플리케이션의 인증 키입니다. |
BlobIndexerDataToExtract
Azure Blob Storage에서 추출할 데이터를 지정하고 "imageAction"이 "none" 이외의 값으로 설정된 경우 이미지 콘텐츠에서 추출할 데이터를 인덱서에 알려줍니다. 이는 .PDF 또는 기타 애플리케이션에 포함된 이미지 콘텐츠 또는 Azure Blob의 .jpg 및 .png와 같은 이미지 파일에 적용됩니다.
| 값 | Description |
|---|---|
| storageMetadata |
표준 Blob 속성 및 사용자 지정 메타데이터만 인덱싱합니다. |
| allMetadata |
Azure Blob Storage 하위 시스템에서 제공하는 메타데이터 및 콘텐츠 형식별 메타데이터(예: .png 파일만 인덱싱된 고유한 메타데이터)를 추출합니다. |
| contentAndMetadata |
각 Blob에서 모든 메타데이터 및 텍스트 콘텐츠를 추출합니다. |
BlobIndexerImageAction
Azure Blob Storage에서 포함된 이미지 및 이미지 파일을 처리하는 방법을 결정합니다. "imageAction" 구성을 "none" 이외의 값으로 설정하려면 기술 세트도 해당 인덱서에 연결해야 합니다.
| 값 | Description |
|---|---|
| none |
데이터 세트에 포함된 이미지 또는 이미지 파일을 무시합니다. 기본값입니다. |
| generateNormalizedImages |
이미지에서 텍스트(예: 교통 정지 표지판의 "STOP"이라는 단어)를 추출하여 콘텐츠 필드에 포함합니다. 이 작업을 수행하려면 "dataToExtract"가 "contentAndMetadata"로 설정되어 있어야 합니다. 정규화된 이미지는 시각적 검색 결과에 이미지를 포함할 때 일관된 렌더링을 촉진하기 위해 균일한 이미지 출력, 크기 및 회전을 생성하는 추가 처리를 의미합니다. 이 정보는 이 옵션을 사용할 때 각 이미지에 대해 생성됩니다. |
| generateNormalizedImagePerPage |
이미지에서 텍스트(예: 교통 정지 표지판의 "STOP"이라는 단어)를 추출하여 콘텐츠 필드에 포함하지만 포함된 이미지를 추출하는 대신 각 페이지가 이미지로 렌더링되고 그에 따라 정규화된다는 점에서 PDF 파일을 다르게 처리합니다. PDF가 아닌 파일 형식은 "generateNormalizedImages"가 설정된 경우와 동일하게 처리됩니다. |
BlobIndexerParsingMode
Azure Blob 데이터 원본에서 인덱싱하기 위한 구문 분석 모드를 나타냅니다.
| 값 | Description |
|---|---|
| default |
일반 파일 처리의 경우 기본값으로 설정합니다. |
| text |
Blob Storage의 일반 텍스트 파일에 대한 인덱싱 성능을 향상시키려면 텍스트로 설정합니다. |
| delimitedText |
Blob이 일반 CSV 파일인 경우 delimitedText로 설정합니다. |
| json |
JSON 파일에서 구조화된 콘텐츠를 추출하려면 json으로 설정합니다. |
| jsonArray |
jsonArray로 설정하여 JSON 배열의 개별 요소를 별도의 문서로 추출합니다. |
| jsonLines |
jsonLines로 설정하여 새 줄로 구분된 개별 JSON 엔터티를 별도의 문서로 추출합니다. |
BlobIndexerPDFTextRotationAlgorithm
Azure Blob Storage의 PDF 파일에서 텍스트 추출을 위한 알고리즘을 결정합니다.
| 값 | Description |
|---|---|
| none |
일반 텍스트 추출을 활용합니다. 기본값입니다. |
| detectAngles |
텍스트가 회전된 PDF 파일에서 더 좋고 읽기 쉬운 텍스트 추출을 생성할 수 있습니다. 이 매개변수를 사용할 때 성능 속도에 약간의 영향을 미칠 수 있습니다. 이 매개변수는 PDF 파일에만 적용되며 텍스트가 포함된 PDF에만 적용됩니다. 회전된 텍스트가 PDF의 포함된 이미지 내에 나타나면 이 매개변수가 적용되지 않습니다. |
ErrorAdditionalInfo
리소스 관리 오류 추가 정보입니다.
| Name | 형식 | Description |
|---|---|---|
| info |
object |
추가 정보입니다. |
| type |
string |
추가 정보 유형입니다. |
ErrorDetail
오류 세부 정보입니다.
| Name | 형식 | Description |
|---|---|---|
| additionalInfo |
오류 추가 정보입니다. |
|
| code |
string |
오류 코드입니다. |
| details |
오류 세부 정보입니다. |
|
| message |
string |
오류 메시지입니다. |
| target |
string |
오류 대상입니다. |
ErrorResponse
오류 응답
| Name | 형식 | Description |
|---|---|---|
| error |
오류 개체입니다. |
FieldMapping
데이터 소스의 필드와 인덱스의 대상 필드 간의 맵핑을 정의합니다.
| Name | 형식 | Description |
|---|---|---|
| mappingFunction |
인덱싱하기 전에 각 원본 필드 값에 적용할 함수입니다. |
|
| sourceFieldName |
string |
데이터 원본의 필드 이름입니다. |
| targetFieldName |
string |
인덱스에 있는 대상 필드의 이름입니다. 기본적으로 원본 필드 이름과 동일합니다. |
FieldMappingFunction
인덱싱하기 전에 데이터 원본의 값을 변환하는 함수를 나타냅니다.
| Name | 형식 | Description |
|---|---|---|
| name |
string |
필드 매핑 함수의 이름입니다. |
| parameters |
object |
함수에 전달할 매개변수 이름/값 쌍의 사전입니다. 각 값은 기본 형식이어야 합니다. |
IndexerExecutionEnvironment
인덱서를 실행해야 하는 환경을 지정합니다.
| 값 | Description |
|---|---|
| standard |
검색 서비스가 인덱서를 실행해야 하는 위치를 결정할 수 있음을 나타냅니다. 아무것도 지정하지 않은 경우 기본 환경이며 권장 값입니다. |
| private |
인덱서가 검색 서비스에 대해 특별히 프로비전된 환경에서 실행되어야 함을 나타냅니다. 인덱서가 공유 프라이빗 링크 리소스를 통해 리소스에 안전하게 액세스해야 하는 경우에만 실행 환경으로 지정해야 합니다. |
IndexingParameters
인덱서 실행에 대한 매개 변수를 나타냅니다.
| Name | 형식 | Default value | Description |
|---|---|---|---|
| batchSize |
integer (int32) |
성능 향상을 위해 데이터 원본에서 읽고 단일 일괄 처리로 인덱싱된 항목 수입니다. 기본값은 데이터 소스 유형에 따라 다릅니다. |
|
| configuration |
인덱서 관련 구성 속성의 사전입니다. 각 이름은 특정 속성의 이름입니다. 각 값은 기본 형식이어야 합니다. |
||
| maxFailedItems |
integer (int32) |
0 |
인덱서 실행에 대한 인덱싱에 실패할 수 있는 최대 항목 수는 여전히 성공적인 것으로 간주됩니다. -1은 제한 없음을 의미합니다. 기본값은 0입니다. |
| maxFailedItemsPerBatch |
integer (int32) |
0 |
일괄 처리에 대한 인덱싱에 실패할 수 있는 단일 일괄 처리의 최대 항목 수는 여전히 성공적인 것으로 간주됩니다. -1은 제한 없음을 의미합니다. 기본값은 0입니다. |
IndexingParametersConfiguration
인덱서 관련 구성 속성의 사전입니다. 각 이름은 특정 속성의 이름입니다. 각 값은 기본 형식이어야 합니다.
| Name | 형식 | Default value | Description |
|---|---|---|---|
| allowSkillsetToReadFileData |
boolean |
False |
true인 경우 Blob 데이터 원본에서 다운로드한 원본 파일 데이터를 나타내는 개체인 경로 //document//file_data를 만듭니다. 이를 통해 원본 파일 데이터를 보강 파이프라인 내에서 처리하기 위해 사용자 지정 기술 또는 문서 추출 기술에 전달할 수 있습니다. |
| dataToExtract | contentAndMetadata |
Azure Blob Storage에서 추출할 데이터를 지정하고 "imageAction"이 "none" 이외의 값으로 설정된 경우 이미지 콘텐츠에서 추출할 데이터를 인덱서에 알려줍니다. 이는 .PDF 또는 기타 애플리케이션에 포함된 이미지 콘텐츠 또는 Azure Blob의 .jpg 및 .png와 같은 이미지 파일에 적용됩니다. |
|
| delimitedTextDelimiter |
string |
CSV Blob의 경우 각 줄이 새 문서를 시작하는 CSV 파일에 대한 줄 끝 단일 문자 구분 기호를 지정합니다(예: "|"). |
|
| delimitedTextHeaders |
string |
CSV Blob의 경우 쉼표로 구분된 열 머리글 목록을 지정하며, 원본 필드를 인덱스의 대상 필드에 매핑하는 데 유용합니다. |
|
| documentRoot |
string |
JSON 배열의 경우 구조화 또는 반구조화된 문서가 주어지면 이 속성을 사용하여 배열의 경로를 지정할 수 있습니다. |
|
| excludedFileNameExtensions |
string |
Azure Blob Storage에서 처리할 때 무시할 파일 이름 확장명의 쉼표로 구분된 목록입니다. 예를 들어 ".png, .mp4"를 제외하여 인덱싱 중에 해당 파일을 건너뛸 수 있습니다. |
|
| executionEnvironment | standard |
인덱서를 실행해야 하는 환경을 지정합니다. |
|
| failOnUnprocessableDocument |
boolean |
False |
Azure Blob의 경우 문서가 인덱싱에 실패할 경우 인덱싱을 계속하려면 false로 설정합니다. |
| failOnUnsupportedContentType |
boolean |
False |
Azure Blob의 경우 지원되지 않는 콘텐츠 형식이 발견되고 모든 콘텐츠 형식(파일 확장명)을 미리 알지 못할 때 인덱싱을 계속하려면 false로 설정합니다. |
| firstLineContainsHeaders |
boolean |
True |
CSV Blob의 경우 각 Blob의 첫 번째(비어 있지 않은) 줄에 헤더가 포함되어 있음을 나타냅니다. |
| imageAction | none |
Azure Blob Storage에서 포함된 이미지 및 이미지 파일을 처리하는 방법을 결정합니다. "imageAction" 구성을 "none" 이외의 값으로 설정하려면 기술 세트도 해당 인덱서에 연결해야 합니다. |
|
| indexStorageMetadataOnlyForOversizedDocuments |
boolean |
False |
Azure Blob의 경우 이 속성을 true로 설정하여 처리하기에는 너무 큰 Blob 콘텐츠에 대한 스토리지 메타데이터를 계속 인덱싱합니다. 너무 큰 Blob은 기본적으로 오류로 처리됩니다. Blob 크기에 대한 제한은 을 참조하세요 https://learn.microsoft.com/azure/search/search-limits-quotas-capacity. |
| indexedFileNameExtensions |
string |
Azure Blob Storage에서 처리할 때 선택할 파일 이름 확장명의 쉼표로 구분된 목록입니다. 예를 들어, 특정 응용 프로그램 파일 ".docx, .pptx, .msg"에 인덱싱을 집중하여 해당 파일 형식을 구체적으로 포함할 수 있습니다. |
|
| parsingMode | default |
Azure Blob 데이터 원본에서 인덱싱하기 위한 구문 분석 모드를 나타냅니다. |
|
| pdfTextRotationAlgorithm | none |
Azure Blob Storage의 PDF 파일에서 텍스트 추출을 위한 알고리즘을 결정합니다. |
|
| queryTimeout |
string |
00:05:00 |
"hh:mm:ss" 형식으로 지정된 Azure SQL 데이터베이스 데이터 원본의 기본값 5분 이상으로 시간 제한을 늘립니다. |
IndexingSchedule
인덱서 실행 일정을 나타냅니다.
| Name | 형식 | Description |
|---|---|---|
| interval |
string (duration) |
인덱서 실행 사이의 시간 간격입니다. |
| startTime |
string (date-time) |
인덱서가 실행을 시작해야 하는 시간입니다. |
SearchIndexer
인덱서를 나타냅니다.
| Name | 형식 | Default value | Description |
|---|---|---|---|
| @odata.etag |
string |
인덱서의 ETag입니다. |
|
| dataSourceName |
string |
이 인덱서가 데이터를 읽는 데이터 원본의 이름입니다. |
|
| description |
string |
인덱서에 대한 설명입니다. |
|
| disabled |
boolean |
False |
인덱서가 비활성화되었는지 여부를 나타내는 값입니다. 기본값은 false입니다. |
| encryptionKey |
Azure Key Vault에서 만드는 암호화 키에 대한 설명입니다. 이 키는 Microsoft를 포함한 누구도 암호를 해독할 수 없다는 완전한 확신을 원하는 경우 인덱서 정의(인덱서 실행 상태뿐만 아니라)에 대한 추가 수준의 미사용 암호화를 제공하는 데 사용됩니다. 인덱서 정의를 암호화한 후에는 항상 암호화된 상태로 유지됩니다. 검색 서비스는 이 속성을 null로 설정하려는 시도를 무시합니다. 암호화 키를 순환하려는 경우 필요에 따라 이 속성을 변경할 수 있습니다. 인덱서 정의(및 인덱서 실행 상태)는 영향을 받지 않습니다. 고객 관리형 키를 사용한 암호화는 무료 검색 서비스에서 사용할 수 없으며 2019년 1월 1일 이후에 생성된 유료 서비스에서만 사용할 수 있습니다. |
||
| fieldMappings |
데이터 원본의 필드와 인덱스의 해당 대상 필드 간의 매핑을 정의합니다. |
||
| name |
string |
인덱서의 이름입니다. |
|
| outputFieldMappings |
출력 필드 매핑은 보강 후 인덱싱 직전에 적용됩니다. |
||
| parameters |
인덱서 실행을 위한 매개 변수입니다. |
||
| schedule |
이 인덱서의 일정입니다. |
||
| skillsetName |
string |
이 인덱서를 사용하여 실행하는 기술 집합의 이름입니다. |
|
| targetIndexName |
string |
이 인덱서가 데이터를 쓰는 인덱스의 이름입니다. |
SearchResourceEncryptionKey
Azure Key Vault의 고객 관리형 암호화 키입니다. 만들고 관리하는 키를 사용하여 인덱스 및 동의어 맵과 같은 미사용 데이터를 암호화하거나 복호화할 수 있습니다.
| Name | 형식 | Description |
|---|---|---|
| accessCredentials |
Azure Key Vault에 액세스하는 데 사용되는 선택적 Azure Active Directory 자격 증명입니다. 대신 관리 ID를 사용하는 경우에는 필요하지 않습니다. |
|
| keyVaultKeyName |
string |
미사용 데이터를 암호화하는 데 사용할 Azure Key Vault 키의 이름입니다. |
| keyVaultKeyVersion |
string |
미사용 데이터를 암호화하는 데 사용할 Azure Key Vault 키의 버전입니다. |
| keyVaultUri |
string |
미사용 데이터를 암호화하는 데 사용할 키를 포함하는 Azure Key Vault의 URI(DNS 이름이라고도 함)입니다. URI |