Delen via

Synoniementoewijzing maken (Azure AI Search REST API)

  • Artikel

In Azure AI Search bevat een synoniemtoewijzing een lijst met regels voor het uitbreiden of herschrijven van een zoekquery naar equivalente termen.

U kunt POST of PUT gebruiken voor de aanvraag. Voor beide biedt het JSON-document in de aanvraagbody de objectdefinitie.

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

U kunt ook PUT gebruiken en de naam van de synoniemtoewijzing opgeven op de URI.

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

HTTPS is vereist voor alle serviceaanvragen. Als de synoniementoewijzing niet bestaat, wordt deze gemaakt. Als deze al bestaat, wordt deze bijgewerkt naar de nieuwe definitie.

Notitie

Het maximum aantal synoniemenkaarten dat u kunt maken, verschilt per prijscategorie. Zie Servicelimieten voor meer informatie.

URI-parameters

Parameter Beschrijving
servicenaam Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice.
synoniemenkaartnaam Vereist voor de URI als u PUT gebruikt. De naam moet kleine letters bevatten, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en minder dan 128 tekens bevatten. Nadat u de naam hebt gestart met een letter of cijfer, kan de rest van de naam een willekeurige letter, cijfer en streepjes bevatten, zolang de streepjes niet opeenvolgend zijn.
api-versie Vereist. De huidige stabiele versie is api-version=2020-06-30. Zie API-versies voor meer versies.

Aanvraagheaders

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Velden Description
Content-Type Vereist. Stel dit in op application/json
api-key Optioneel als u Azure-rollen gebruikt en er een Bearer-token is opgegeven voor de aanvraag, anders is een sleutel vereist. Een API-sleutel is een unieke, door het systeem gegenereerde tekenreeks die de aanvraag verifieert bij uw zoekservice. Create-aanvragen moeten een api-key header bevatten die is ingesteld op uw beheerderssleutel (in plaats van een querysleutel). Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie.

Aanvraagbody

De hoofdtekst van de aanvraag bevat een definitie van een synoniemtoewijzing, waaronder de indeling van de synoniemtoewijzing en de lijst met regels in de opgegeven indeling.

De volgende JSON is een weergave op hoog niveau van de belangrijkste onderdelen van de definitie.

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

Aanvraag bevat de volgende eigenschappen:

Eigenschap Beschrijving
naam Vereist. De naam van de synoniemenkaart. Een synoniemenkaartnaam mag alleen kleine letters, cijfers of streepjes bevatten, mag niet beginnen of eindigen met streepjes en mag maximaal 128 tekens bevatten.
indeling Vereist. Alleen de Apache Solr-indeling (solr) wordt momenteel ondersteund.
Synoniemen Vereist. Synoniemregels gescheiden door het nieuwe regelteken ('\n').
encryptionKey Optioneel. Wordt gebruikt voor het versleutelen van een synoniemtoewijzing, met uw eigen sleutels, beheerd in uw Azure Key Vault. Beschikbaar voor factureerbare zoekservices die zijn gemaakt op of na 01-2019.

Een encryptionKey sectie bevat een door de gebruiker gedefinieerde keyVaultKeyName (vereist), een door het systeem gegenereerde keyVaultKeyVersion (vereist) en een keyVaultUri die de sleutel levert (vereist, ook wel DNS-naam genoemd). Een voorbeeld van een URI kan 'https://my-keyvault-name.vault.azure.net".

U kunt desgewenst opgeven accessCredentials of u geen beheerde systeemidentiteit gebruikt. Eigenschappen van accessCredentials include applicationId (Azure Active Directory-toepassings-id waaraan toegangsmachtigingen zijn verleend voor uw opgegeven Azure Key Vault) en applicationSecret (verificatiesleutel van de opgegeven Azure AD toepassing). Een voorbeeld in de volgende sectie illustreert de syntaxis.

Antwoord

Voor een geslaagde aanvraag: 201 Gemaakt.

Voorbeelden

Voorbeeld: Lijst met synoniemen met equivalente en expliciete toewijzingen.

Een equivalente toewijzingsregel bevat equivalente termen of woordgroepen, gescheiden door komma's ('USA, Verenigde Staten, Verenigde Staten of America'). Met de regel wordt de zoekopdracht uitgebreid naar alle equivalente termen of woordgroepen. Een zoekdocument dat bijvoorbeeld bevat USA , komt overeen met query's die de term USA of de woordgroepen "United States"bevatten, of "United States of America".

Expliciete toewijzing wordt aangegeven met een pijl => ('USA, U.S.A., U.S., Verenigde Staten, Verenigde Staten of America => USA'). Wanneer dit is opgegeven, wordt een termenreeks van een zoekquery die overeenkomt met de linkerkant van => vervangen door de alternatieven aan de rechterkant. Op basis van de regel worden de zoekquery's U.S. of "United States" allemaal herschreven naar USA. Expliciete toewijzing is alleen van toepassing in de opgegeven richting en schrijft de query USA in dit geval niet opnieuw."United States" U ziet dat 'Verenigde Staten' een ingesloten woordgroepsquery is. Als u een overeenkomst wilt voor de hele woordgroep, moet de querytekenreeks tussen dubbele aanhalingstekens worden geplaatst. Anders wordt elke term, 'United' en 'States', afzonderlijk geëvalueerd.

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

Voorbeeld: Versleutelingssleutels

Versleutelingssleutels zijn door de klant beheerde sleutels die worden gebruikt voor extra versleuteling. Zie Versleuteling met door de klant beheerde sleutels in Azure Key Vault voor meer informatie.

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

Zie ook