Condividi tramite

Creare una mappa sinonimo (API REST ricerca intelligenza artificiale di Azure)

  • Articolo

In Ricerca intelligenza artificiale di Azure, una mappa sinonimo contiene un elenco di regole per l'espansione o la riscrittura di una query di ricerca in termini equivalenti.

È possibile usare POST o PUT nella richiesta. Per uno, il documento JSON nel corpo della richiesta fornisce la definizione dell'oggetto.

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

In alternativa è possibile usare PUT e specificare il nome della mappa sinonimica nell'URI.

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

Per tutte le richieste del servizio, è necessario usare il protocollo HTTPS. Se la mappa dei sinonimi non esiste, viene creata. Se esiste già, viene aggiornato alla nuova definizione.

Nota

Numero massimo di mappe sinonimi che è possibile creare varia in base al piano tariffario. Per altre informazioni, vedere Limiti del servizio.

Parametri dell'URI

Parametro Descrizione
nome servizio Obbligatorio. Impostare questo valore sul nome univoco definito dall'utente del servizio di ricerca.
nome mappa sinonimo Obbligatorio nell'URI se si usa PUT. Il nome deve essere minuscolo, iniziare con una lettera o un numero, non avere barre o punti e essere inferiore a 128 caratteri. Dopo aver avviato il nome con una lettera o un numero, il resto del nome può includere qualsiasi lettera, numero e trattini, purché i trattini non siano consecutivi.
api-version Obbligatorio. La versione stabile corrente è api-version=2020-06-30. Per altre versioni, vedere Versioni API .

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Campi Descrizione
Content-Type Obbligatorio. Impostare il valore su application/json
api-key Facoltativo se si usano ruoli di Azure e viene fornito un token di connessione nella richiesta, altrimenti è necessaria una chiave. Una chiave API è una stringa univoca generata dal sistema che autentica la richiesta al servizio di ricerca. Le richieste di creazione devono includere un api-key set di intestazioni sulla chiave di amministrazione , anziché una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione delle chiavi .

Corpo della richiesta

Il corpo della richiesta contiene una definizione della mappa sinonimo, che include il formato della mappa sinonimia e l'elenco delle regole nel formato specificato.

Il codice JSON seguente è una rappresentazione generale delle parti principali della definizione.

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

La richiesta contiene le proprietà seguenti:

Proprietà Descrizione
name Obbligatorio. Nome della mappa sinonimia. Un nome mappa sinonimo deve contenere solo lettere minuscole, cifre o trattini, non può iniziare o terminare con trattini ed è limitato a 128 caratteri.
format Obbligatorio. È attualmente supportato solo il formato Apache Solr (solr).
sinonimi Obbligatorio. Regole sinonime separate dal carattere della nuova riga ('\n').
EncryptionKey facoltativo. Usato per crittografare una mappa sinonimo, con chiavi personalizzate, gestite nell'Key Vault di Azure. Disponibile per i servizi di ricerca fatturabili creati in o dopo il 2019-01-01.

Una encryptionKey sezione contiene un oggetto definito keyVaultKeyName dall'utente (obbligatorio), un sistema generato keyVaultKeyVersion dal sistema (obbligatorio) e una keyVaultUri chiave (richiesta, definita anche come nome DNS). Un URI di esempio potrebbe essere "https://my-keyvault-name.vault.azure.net".

Facoltativamente, è possibile specificare accessCredentials se non si usa un'identità del sistema gestita. Proprietà di inclusione applicationId (ID applicazione azure Active Directory concesso alle autorizzazioni di accesso per l'Key Vault di Azure specificato) e applicationSecret (chiave di accessCredentials autenticazione dell'applicazione Azure AD specificata). Un esempio nella sezione successiva illustra la sintassi.

Risposta

Se la richiesta ha esito positivo, viene restituito il codice di stato 201 - Creato.

Esempio

Esempio: elenco di sinonimi con mapping equivalenti ed espliciti.

Una regola di mapping equivalente elenca termini o frasi equivalenti separati da virgole ("USA, Stati Uniti, Stati Uniti d'America"). La regola espande la ricerca in tutti i termini o frasi equivalenti. Ad esempio, un documento di ricerca contenente USA corrisponderà alle query che contengono il termine USA o le frasi "United States"o "United States of America".

Il mapping esplicito viene denotato da una freccia => ("USA, Stati Uniti, Stati Uniti, Stati Uniti dell'America => USA"). Se specificato, una sequenza di termini di una query di ricerca corrispondente al lato sinistro di => verrà sostituita con le alternative sul lato destro. Data la regola, le query U.S. di ricerca o "United States" tutte verranno riscritte in USA. Il mapping esplicito si applica solo nella direzione specificata e non riscrive la query USA in "United States" in questo caso. Si noti che "Stati Uniti" è una query di frasi racchiuse tra virgolette. Se si vuole una corrispondenza sull'intera frase, la stringa di query deve essere racchiusa tra virgolette doppie. In caso contrario, ogni termine, "United" e "States", viene valutato separatamente.

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

Esempio: Chiavi di crittografia

Le chiavi di crittografia sono chiavi gestite dal cliente usate per una crittografia aggiuntiva. Per altre informazioni, vedere Crittografia con chiavi gestite dal cliente in 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)"
      }
  }
}

Vedi anche