Tworzenie mapy synonimów (interfejs API REST usługi Azure AI Search)

  • Artykuł

W usłudze Azure AI Search mapa synonimów zawiera listę reguł rozwijania lub ponownego pisania zapytania wyszukiwania na równoważne terminy.

Możesz użyć metody POST lub PUT na żądanie. W przypadku jednej z nich dokument JSON w treści żądania zawiera definicję obiektu.

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

Alternatywnie możesz użyć funkcji PUT i określić nazwę mapy synonimów w identyfikatorze URI.

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

Protokół HTTPS jest wymagany dla wszystkich żądań obsługi. Jeśli mapa synonimów nie istnieje, zostanie utworzona. Jeśli już istnieje, zostanie ona zaktualizowana do nowej definicji.

Uwaga

Maksymalna liczba map synonimów, które można utworzyć, różni się w zależności od warstwy cenowej. Aby uzyskać więcej informacji, zobacz Limity usługi.

Parametry identyfikatora URI

Parametr Opis
nazwa usługi Wymagane. Ustaw tę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania.
nazwa mapy synonimów Wymagane dla identyfikatora URI w przypadku używania funkcji PUT. Nazwa musi mieć małe litery, zaczynać się literą lub cyfrą, nie ma ukośników ani kropek i ma mniej niż 128 znaków. Po rozpoczęciu nazwy literą lub cyfrą reszta nazwy może zawierać dowolną literę, cyfrę i kreski, o ile kreski nie są kolejne.
api-version Wymagane. Bieżąca stabilna wersja to api-version=2020-06-30. Zobacz Wersje interfejsu API , aby uzyskać więcej wersji.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Pola Opis
Content-Type Wymagane. Ustaw tę wartość na application/json
api-key Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest dostarczany w żądaniu, w przeciwnym razie wymagany jest klucz. Api-key to unikatowy ciąg generowany przez system, który uwierzytelnia żądanie w usłudze wyszukiwania. Tworzenie żądań musi zawierać api-key nagłówek ustawiony na klucz administratora (w przeciwieństwie do klucza zapytania). Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza .

Treść żądania

Treść żądania zawiera definicję mapy synonimów, która zawiera format mapy synonimów i listę reguł w określonym formacie.

Poniższy kod JSON jest ogólną reprezentacją głównych części definicji.

{   
    "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 } 
}

Żądanie zawiera następujące właściwości:

Właściwość Opis
name Wymagane. Nazwa mapy synonimów. Nazwa mapy synonimów musi zawierać tylko małe litery, cyfry lub kreski, nie może zaczynać ani kończyć się kreskami i jest ograniczona do 128 znaków.
format Wymagane. Obecnie obsługiwany jest tylko format apache Solr (solr).
Synonimy Wymagane. Reguły synonimów oddzielone znakiem nowego wiersza ('\n').
encryptionKey Opcjonalny. Służy do szyfrowania mapy synonimów przy użyciu własnych kluczy zarządzanych w usłudze Azure Key Vault. Dostępne dla rozliczanych usług wyszukiwania utworzonych w dniach lub po 2019-01-01.

Sekcja encryptionKey zawiera zdefiniowaną przez keyVaultKeyName użytkownika (wymaganą), wygenerowaną keyVaultKeyVersion przez system (wymaganą keyVaultUri ) i podając klucz (wymagany, nazywany również nazwą DNS). Przykładowy identyfikator URI może mieć wartość "https://my-keyvault-name.vault.azure.net"".

Opcjonalnie możesz określić accessCredentials , czy nie używasz tożsamości systemu zarządzanego. accessCredentials Właściwości funkcji include applicationId (identyfikator aplikacji usługi Azure Active Directory, któremu udzielono uprawnień dostępu do określonej usługi Azure Key Vault) i applicationSecret (klucz uwierzytelniania określonej aplikacji Azure AD). Przykład w następnej sekcji ilustruje składnię.

Reakcja

W przypadku pomyślnego żądania: 201 Utworzono.

Przykłady

Przykład: lista synonimów z równoważnymi i jawnymi mapowaniami.

Równoważna reguła mapowania wyświetla równoważne terminy lub frazy oddzielone przecinkami ("USA, Stany Zjednoczone, Stany Zjednoczone Ameryki"). Reguła rozszerza wyszukiwanie na wszystkie równoważne terminy lub frazy. Na przykład dokument wyszukiwania, który zawiera USA , będzie zgodny z zapytaniami zawierającymi termin USA lub frazy "United States"lub "United States of America".

Jawne mapowanie jest oznaczone strzałką => ("USA, USA, USA, USA, Stany Zjednoczone, Stany Zjednoczone Ameryki => USA"). Po określeniu termin sekwencji zapytania wyszukiwania pasujący do lewej strony => elementu zostanie zastąpiony alternatywami po prawej stronie. Biorąc pod uwagę regułę, kwerendy U.S. wyszukiwania lub "United States" wszystkie zostaną przepisane do .USA Jawne mapowanie ma zastosowanie tylko w określonym kierunku i nie zapisuje ponownie zapytania USA"United States" w tym przypadku. Zwróć uwagę, że wyrażenie "Stany Zjednoczone" jest zapytaniem frazy ujętej w cudzysłów. Jeśli chcesz dopasować do całej frazy, ciąg zapytania musi być ujęta w znaki podwójnego cudzysłowu. W przeciwnym razie każdy termin "United" i "States" jest oceniany oddzielnie.

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

Przykład: klucze szyfrowania

Klucze szyfrowania to klucze zarządzane przez klienta używane do dodatkowego szyfrowania. Aby uzyskać więcej informacji, zobacz Szyfrowanie przy użyciu kluczy zarządzanych przez klienta w usłudze 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)"
      }
  }
}

Zobacz też