동의어 맵 만들기(Azure Cognitive Search REST API)

Azure Cognitive Search 동의어 맵에는 검색 쿼리를 동등한 용어로 확장하거나 다시 쓰기 위한 규칙 목록이 포함되어 있습니다.

요청에 POST 또는 PUT을 사용할 수 있습니다. 둘 중 하나의 경우 요청 본문의 JSON 문서는 개체 정의를 제공합니다.

POST https://[service name].search.windows.net/synonymmaps?api-version=[api-version]      
  Content-Type: application/json  
  api-key: [admin key]  

또는 PUT을 사용하여 URI에서 동의어 맵 이름을 지정할 수 있습니다.

PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]  

모든 서비스 요청에는 HTTPS를 사용해야 합니다. 동의어 맵이 없으면 생성됩니다. 이미 있으면 새 정의로 업데이트됩니다.

참고

만들 수 있는 동의어 맵의 최대 수는 가격 책정 계층에 따라 다릅니다. 자세한 내용은 서비스 제한을 참조하세요.

URI 매개 변수

매개 변수 설명
서비스 이름 필수 요소. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
동의어 맵 이름 PUT을 사용하는 경우 URI에 필요합니다. 이름은 소문자여야 하고, 문자 또는 숫자로 시작하고, 슬래시나 점이 없고, 128자 미만이어야 합니다. 문자 또는 숫자로 이름을 시작한 후 대시가 연속되지 않는 한 나머지 이름에는 문자, 숫자 및 대시가 포함될 수 있습니다.
api-version 필수 요소. 현재 안정적인 버전은 api-version=2020-06-30. 더 많은 버전은 API 버전을 참조하세요.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

필드 Description
콘텐츠 형식 필수 요소. application/json
api-key 필수 요소. api-key는 Search 서비스에 대한 요청을 인증하는 데 사용되며, 서비스에 고유한 문자열 값입니다. 만들기 요청에는 쿼리 키가 아닌 관리자 키로 설정된 헤더가 포함되어 api-key 야 합니다. Azure Portal 검색 서비스 대시보드에서 API 키를 찾을 수 있습니다.

요청 본문

요청 본문에는 동의어 맵의 형식과 지정된 형식의 규칙 목록이 포함된 동의어 맵 정의가 포함되어 있습니다.

다음 JSON은 정의의 주요 부분을 개략적으로 표현한 것입니다.

{   
    "name" : (optional on PUT; required on POST) "Name of the synonym map",  
    "format" : (required) "Only Apache Solr format ('solr') is currently supported.",
    "synonyms" : (required) "Synonym rules separated by the new line ('\n') character.",
    "encryptionKey":(optional) { See below for details }
  } 
}  

요청에는 다음 속성이 포함됩니다.

속성 설명
name 필수 요소. 동의어 맵의 이름입니다. 동의어 맵 이름은 소문자, 숫자 또는 대시만 포함해야 하며 대시로 시작하거나 끝낼 수 없으며 128자로 제한됩니다.
format 필수 요소. 현재 Apache Solr 형식(solr)만 지원됩니다.
동의어 필수 요소. 동의어 규칙은 새 줄('\n') 문자로 구분됩니다.
encryptionKey 선택 사항입니다. Azure Key Vault 관리되는 고유한 키를 사용하여 동의어 맵을 암호화하는 데 사용됩니다. 2019-01-01 이후 생성된 청구 가능한 검색 서비스에 사용할 수 있습니다.

encryptionKey 섹션에는 사용자 정의 keyVaultKeyName (필수), 시스템 생성 keyVaultKeyVersion (필수) 및 keyVaultUri 제공 키(필수, DNS 이름이라고도 함)가 포함되어 있습니다. 예제 URI는 "https://my-keyvault-name.vault.azure.net"일 수 있습니다.

필요에 따라 관리되는 시스템 ID를 사용하지 않는지 지정할 accessCredentials 수 있습니다. accessCredentials 포함 applicationId 속성(지정된 Azure Key Vault 대한 액세스 권한이 부여된 Azure Active Directory 애플리케이션 ID) 및 applicationSecret (지정된 Azure AD 애플리케이션의 인증 키) 다음 섹션의 예제에서는 구문을 보여 줍니다.

응답

요청이 성공적으로 실행되면 '201 생성됨'이 반환됩니다.

예: 동일하고 명시적인 매핑이 있는 동의어 목록입니다.

동등한 매핑 규칙은 쉼표("미국, 미국, 미국")로 구분된 동등한 용어 또는 구를 나열합니다. 규칙은 검색을 해당하는 모든 용어 또는 구로 확장합니다. 예를 들어 포함된 USA 검색 문서는 용어 USA 또는 구 "United States"를 포함하는 쿼리 또는 "United States of America".

명시적 매핑은 화살표 => ("미국, 미국, 미국, 미국, 미국 => 미국")로 표시됩니다. 지정하면 왼쪽과 일치하는 검색 쿼리의 => 용어 시퀀스가 오른쪽의 대안으로 바뀝니다. 규칙을 지정하면 검색 쿼리가 U.S. 쿼리되거나 "United States" 모두 .로 USA다시 작성됩니다. 명시적 매핑은 지정된 방향으로만 적용되며 이 경우 쿼리 USA"United States" 다시 작성하지 않습니다. "미국"는 따옴표로 묶인 구 쿼리입니다. 전체 구에서 일치를 원하는 경우 쿼리 문자열을 큰따옴표로 묶어야 합니다. 그렇지 않으면 각 용어인 "United" 및 "States"가 별도로 평가됩니다.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA"
}  

예: 암호화 키

암호화 키는 추가 암호화에 사용되는 고객 관리형 키입니다. 자세한 내용은 Azure Key Vault 고객 관리형 키를 사용한 암호화를 참조하세요.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "encryptionKey": (optional) { 
    "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
    "keyVaultKeyVersion": "Version of the Azure Key Vault key",
    "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
    "accessCredentials": (optional, only if not using managed system identity) {
      "applicationId": "Azure AD Application ID that was granted access permissions to your specified Azure Key Vault",
      "applicationSecret": "Authentication key of the specified Azure AD application)"
    }
}  

참조