Skapa synonymkarta (REST API för Azure AI Search)

  • Artikel

I Azure AI Search innehåller en synonymkarta en lista med regler för att expandera eller skriva om en sökfråga till motsvarande termer.

Du kan använda POST eller PUT på begäran. För någon av dem innehåller JSON-dokumentet i begärandetexten objektdefinitionen.

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

Du kan också använda PUT och ange synonymmappningsnamnet på URI:n.

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

HTTPS krävs för alla tjänstbegäranden. Om synonymkartan inte finns skapas den. Om den redan finns uppdateras den till den nya definitionen.

Anteckning

Det maximala antalet synonymkartor som du kan skapa varierar beroende på prisnivå. Mer information finns i Tjänstbegränsningar.

URI-parametrar

Parameter Beskrivning
tjänstnamn Krävs. Ange det unika, användardefinierade namnet på söktjänsten.
synonymmappningsnamn Krävs på URI:n om du använder PUT. Namnet måste vara gemener, börja med en bokstav eller ett tal, ha inga snedstreck eller punkter och vara färre än 128 tecken. När du har startat namnet med en bokstav eller siffra kan resten av namnet innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd.
api-version Krävs. Den aktuella stabila versionen är api-version=2020-06-30. Se API-versioner för fler versioner.

Rubriker för begäran

I följande tabell beskrivs nödvändiga och valfria begärandehuvuden.

Fält Description
Content-Type Krävs. Ange detta till application/json
api-key Valfritt om du använder Azure-roller och en ägartoken anges på begäran, annars krävs en nyckel. En API-nyckel är en unik, systemgenererad sträng som autentiserar begäran till söktjänsten. Skapa begäranden måste innehålla en api-key rubrik inställd på din administratörsnyckel (till skillnad från en frågenyckel). Mer information finns i Ansluta till Azure AI Search med nyckelautentisering .

Begärandetext

Brödtexten i begäran innehåller en definition av synonymkartan, som innehåller formatet för synonymkartan och listan över regler i det angivna formatet.

Följande JSON är en övergripande representation av definitionens huvuddelar.

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

Begäran innehåller följande egenskaper:

Egenskap Beskrivning
name Krävs. Namnet på synonymkartan. Ett synonymkartnamn får bara innehålla gemener, siffror eller bindestreck, kan inte starta eller sluta med bindestreck och är begränsat till 128 tecken.
format Krävs. Endast Apache Solr-format (solr) stöds för närvarande.
Synonymer Krävs. Synonymregler avgränsade med det nya radtecknet ("\n").
encryptionKey Valfritt. Används för att kryptera en synonymkarta med dina egna nycklar som hanteras i azure-Key Vault. Tillgängligt för fakturerbara söktjänster som skapats på eller efter 2019-01-01.

Ett encryptionKey avsnitt innehåller en användardefinierad keyVaultKeyName (obligatorisk), ett systemgenererat (obligatoriskt keyVaultKeyVersion ) och en keyVaultUri som tillhandahåller nyckeln (krävs, även kallat DNS-namn). Ett exempel på URI kan vara "https://my-keyvault-name.vault.azure.net".

Du kan också ange accessCredentials om du inte använder en hanterad systemidentitet. accessCredentials Egenskaper för inkluderar applicationId (Azure Active Directory-program-ID som har beviljats åtkomstbehörigheter till din angivna Azure-Key Vault) och applicationSecret (autentiseringsnyckel för det angivna Azure AD-programmet). Ett exempel i nästa avsnitt illustrerar syntaxen.

Svarsåtgärder

För en lyckad begäran: 201 Skapad.

Exempel

Exempel: Lista över synonymer med motsvarande och explicita mappningar.

En motsvarande mappningsregel visar motsvarande termer eller fraser avgränsade med kommatecken ("USA, USA, USA of America"). Regeln utökar sökningen till alla motsvarande termer eller fraser. Till exempel matchar ett sökdokument som innehåller USA frågor som innehåller termen USA eller fraserna "United States", eller "United States of America".

Explicit mappning betecknas med en pil => ("USA, USA, USA, USA, USA, USA of America => USA"). När det anges ersätts en termsekvens av en sökfråga som matchar vänster sida av => med alternativen till höger. Med tanke på regeln skrivs sökfrågorna U.S. eller "United States" alla om till USA. Explicit mappning gäller endast i den angivna riktningen och skriver inte om frågan USA till "United States" i det här fallet. Observera att "USA" är en citattät frasfråga. Om du vill ha en matchning i hela frasen måste frågesträngen omges av dubbla citattecken. Annars utvärderas varje term, "United" och "States", separat.

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

Exempel: Krypteringsnycklar

Krypteringsnycklar är kundhanterade nycklar som används för extra kryptering. Mer information finns i Kryptering med kundhanterade nycklar i 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)"
      }
  }
}

Se även