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

  • 아티클

Azure AI 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 매개 변수

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

요청 헤더

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

필드 Description
콘텐츠 형식 필수 사항입니다. application/json
api-key Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. api-key는 검색 서비스에 대한 요청을 인증하는 고유한 시스템 생성 문자열입니다. 요청 만들기에는 쿼리 키와 api-key 달리 관리자 키로 설정된 헤더가 포함되어야 합니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

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

다음 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 } 
}

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

속성 Description
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 of America"를 포함하는 쿼리에서 일치합니다"United States".

명시적 매핑은 화살표 => ("미국, 미국, 미국, 미국, 미국 => 미국")로 표시됩니다. 지정하면 의 왼쪽 => 과 일치하는 검색 쿼리의 용어 시퀀스가 오른쪽의 대안으로 바뀝니다. 규칙이 지정된 경우 검색 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)"
      }
  }
}

추가 정보