Share via

Vytvoření mapy synonym (rozhraní REST API služby Azure AI Search)

  • Článek

Ve službě Azure AI Search obsahuje mapa synonym seznam pravidel pro rozbalení nebo přepsání vyhledávacího dotazu na ekvivalentní termíny.

Na žádost můžete použít post nebo PUT. U obou z nich dokument JSON v textu požadavku poskytuje definici objektu.

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

Případně můžete použít PUT a zadat název mapy synonym v identifikátoru URI.

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

Https se vyžaduje pro všechny žádosti o služby. Pokud mapa synonym neexistuje, vytvoří se. Pokud už existuje, aktualizuje se na novou definici.

Poznámka

Maximální počet map synonym, které můžete vytvořit, se liší podle cenové úrovně. Další informace najdete v tématu Limity služby.

Parametry identifikátoru URI

Parametr Popis
název služby Povinná hodnota. Nastavte ho na jedinečný, uživatelem definovaný název vaší vyhledávací služby.
název mapy synonym Vyžaduje se u identifikátoru URI, pokud používáte PUT. Název musí být malé, musí začínat písmenem nebo číslicí, nesmí obsahovat lomítka ani tečky a musí být kratší než 128 znaků. Po začátku názvu písmenem nebo číslicí může zbytek názvu obsahovat libovolné písmeno, číslo a pomlčky, pokud pomlčky nejsou po sobě jdoucí.
verze-api Povinná hodnota. Aktuální stabilní verze je api-version=2020-06-30. Další verze najdete v tématu Verze rozhraní API .

Hlavičky požadavku

Následující tabulka popisuje požadovanou a volitelnou hlavičku požadavku.

Pole Description
Typ obsahu Povinná hodnota. Nastavte tuto možnost na application/json
klíč rozhraní API Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Klíč api-key je jedinečný, systémem vygenerovaný řetězec, který ověřuje požadavek na vaši vyhledávací službu. Požadavky na vytvoření musí obsahovat hlavičku nastavenou api-key na klíč správce (na rozdíl od klíče dotazu). Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Text požadavku

Tělo požadavku obsahuje definici mapy synonym, která zahrnuje formát mapy synonym a seznam pravidel v zadaném formátu.

Následující kód JSON představuje základní reprezentaci hlavních částí definice.

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

Požadavek obsahuje následující vlastnosti:

Vlastnost Popis
name Povinná hodnota. Název mapy synonym. Název mapy synonym musí obsahovat pouze malá písmena, číslice nebo pomlčky, nesmí začínat ani končit pomlčkami a je omezený na 128 znaků.
formát Povinná hodnota. V současné době se podporuje pouze formát Apache Solr (solr).
Synonyma Povinná hodnota. Pravidla synonym oddělená znakem nového řádku (\n).
šifrovací klíč Nepovinný parametr. Používá se k šifrování mapy synonym s vlastními klíči spravovanými ve vaší Key Vault Azure. K dispozici pro fakturovatelné vyhledávací služby vytvořené 1. 1. 2019 nebo později.

Oddíl encryptionKey obsahuje uživatelem definovaný (povinné), systémově vygenerovaný keyVaultKeyNamekeyVaultKeyVersion (povinné) a klíč s poskytnutím keyVaultUri (povinný, označovaný také jako název DNS). Příkladem identifikátoru URI může být "https://my-keyvault-name.vault.azure.net".

Volitelně můžete určit accessCredentials , jestli nepoužíváte spravovanou systémovou identitu. Vlastnosti zahrnují accessCredentialsapplicationId (ID aplikace Azure Active Directory, kterému byla udělena přístupová oprávnění k zadané Key Vault Azure) a applicationSecret (ověřovací klíč zadané Azure AD aplikace). Příklad v další části ukazuje syntaxi.

Odpověď

Pro úspěšný požadavek: 201 Vytvořeno.

Příklady

Příklad: Seznam synonym s ekvivalentními a explicitními mapováními.

Ekvivalentní pravidlo mapování uvádí ekvivalentní termíny nebo fráze oddělené čárkami ("USA, USA, USA Of America"). Pravidlo rozšíří hledání na všechny ekvivalentní termíny nebo fráze. Například dokument hledání, který obsahuje USA , se bude shodovat s dotazy, které obsahují termín USA nebo fráze "United States", nebo "United States of America".

Explicitní mapování je označeno šipkou => ("USA, USA, USA, USA, USA Of America => USA"). Při zadání se posloupnost termínů vyhledávacího dotazu, která odpovídá levé straně => dotazu, nahradí alternativami na pravé straně. Vzhledem k pravidlu se vyhledávací dotazy nebo "United States" přepíšou U.S. na USA. Explicitní mapování se použije pouze v zadaném směru a v tomto případě dotaz nepřepíše USA na "United States" . Všimněte si, že "USA" je dotaz fráze v uvozovkách. Pokud chcete, aby se shodovala celá fráze, musí být řetězec dotazu uzavřený do dvojitých uvozovek. V opačném případě se každý termín "Spojené" a "States" vyhodnocuje zvlášť.

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

Příklad: Šifrovací klíče

Šifrovací klíče jsou klíče spravované zákazníkem, které slouží k dodatečnému šifrování. Další informace najdete v tématu Šifrování pomocí klíčů spravovaných zákazníkem v 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)"
      }
  }
}

Viz také