Erstellen einer Synonymzuordnung (Azure AI Search-REST-API)

  • Artikel

In Azure AI Search enthält eine Synonymzuordnung eine Liste von Regeln zum Erweitern oder Umschreiben einer Suchabfrage in entsprechende Begriffe.

Sie können entweder POST oder PUT für die Anforderung verwenden. Für beide stellt das JSON-Dokument im Anforderungstext die Objektdefinition bereit.

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

Alternativ können Sie PUT verwenden und den Namen der Synonymzuordnung für den URI angeben.

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

HTTPS ist für alle Dienstanforderungen erforderlich. Wenn die Synonymzuordnung nicht vorhanden ist, wird sie erstellt. Wenn sie bereits vorhanden ist, wird sie auf die neue Definition aktualisiert.

Hinweis

Die maximale Anzahl von Synonymzuordnungen, die Sie erstellen können, variiert je nach Tarif. Weitere Informationen finden Sie unter Diensteinschränkungen.

URI-Parameter

Parameter BESCHREIBUNG
Dienstname Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
Name der Synonymzuordnung Erforderlich für den URI, wenn PUT verwendet wird. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte aufweisen und weniger als 128 Zeichen lang sein. Nachdem Sie den Namen mit einem Buchstaben oder einer Zahl gestartet haben, kann der Rest des Namens beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgen.
api-version Erforderlich. Die aktuelle stabile Version ist api-version=2020-06-30. Weitere Versionen finden Sie unter API-Versionen .

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder BESCHREIBUNG
Content-Type Erforderlich. Auf application/json
api-key Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken für die Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Ein API-Schlüssel ist eine eindeutige, vom System generierte Zeichenfolge, die die Anforderung bei Ihrem Suchdienst authentifiziert. Erstellen von Anforderungen muss einen api-key Header enthalten, der auf Ihren Administratorschlüssel (im Gegensatz zu einem Abfrageschlüssel) festgelegt ist. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung .

Anforderungstext

Der Text der Anforderung enthält eine Synonymzuordnungsdefinition, die das Format der Synonymzuordnung und die Liste der Regeln im angegebenen Format enthält.

Der folgende JSON-Code ist eine allgemeine Darstellung des Standard Teile der Definition.

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

Die Anforderung enthält die folgenden Eigenschaften:

Eigenschaft BESCHREIBUNG
name Erforderlich. Der Name der Synonymzuordnung. Ein Synonymzuordnungsname darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, kann nicht mit Bindestrichen beginnen oder enden und ist auf 128 Zeichen beschränkt.
format Erforderlich. Derzeit wird nur das Apache Solr-Format (solr) unterstützt.
Synonyme Erforderlich. Synonymregeln, die durch das neue Zeilenzeichen ("\n") getrennt sind.
encryptionKey Optional. Wird verwendet, um eine Synonymzuordnung mit Ihren eigenen Schlüsseln zu verschlüsseln, die in Ihrer Azure-Key Vault verwaltet werden. Verfügbar für abrechenbare Suchdienste, die am oder nach dem 01.01.2019 erstellt wurden.

Ein encryptionKey Abschnitt enthält einen benutzerdefinierten keyVaultKeyName (erforderlich), einen systemgenerierten keyVaultKeyVersion (erforderlich) und einen keyVaultUri Schlüssel, der den Schlüssel bereitstellt (erforderlich, auch als DNS-Name bezeichnet). Ein Beispiel-URI kann "https://my-keyvault-name.vault.azure.net"" sein.

Optional können Sie angeben accessCredentials , ob Sie keine verwaltete Systemidentität verwenden. Eigenschaften von accessCredentials include applicationId (Azure Active Directory-Anwendungs-ID, der Zugriffsberechtigungen für Ihre angegebene Azure Key Vault gewährt wurden) und applicationSecret (Authentifizierungsschlüssel der angegebenen Azure AD-Anwendung). Ein Beispiel im nächsten Abschnitt veranschaulicht die Syntax.

Antwort

Bei erfolgreicher Anforderung: "201 Erstellt".

Beispiele

Beispiel: Liste von Synonymen mit entsprechenden und expliziten Zuordnungen.

Eine entsprechende Zuordnungsregel listet äquivalente Begriffe oder Ausdrücke auf, die durch Kommas getrennt sind ("USA, USA, USA von Amerika"). Die Regel erweitert die Suche auf alle gleichwertigen Begriffe oder Ausdrücke. Ein Suchdokument, das z. B. enthält USA , stimmt mit Abfragen überein, die den Ausdruck USA oder die Ausdrücke "United States"enthalten, oder "United States of America".

Die explizite Zuordnung wird durch einen Pfeil => gekennzeichnet ("USA, USA, USA, USA, USA von Amerika => USA"). Wenn angegeben, wird eine Begriffssequenz einer Suchabfrage, die der linken Seite von => entspricht, durch die Alternativen auf der rechten Seite ersetzt. Aufgrund der Regel fragt die Suche ab U.S. oder "United States" wird in umgeschrieben USA. Die explizite Zuordnung gilt nur in der angegebenen Richtung und schreibt die Abfrage USA"United States" in diesem Fall nicht um. Beachten Sie, dass "USA" eine Abfrage mit Anführungszeichen ist. Wenn Sie eine Übereinstimmung für den gesamten Ausdruck wünschen, muss die Abfragezeichenfolge in doppelte Anführungszeichen eingeschlossen werden. Andernfalls wird jeder Begriff , "United" und "States", separat ausgewertet.

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

Beispiel: Verschlüsselungsschlüssel

Verschlüsselungsschlüssel sind kundenseitig verwaltete Schlüssel, die für die zusätzliche Verschlüsselung verwendet werden. Weitere Informationen finden Sie unter Verschlüsselung mithilfe von kundenseitig verwalteten Schlüsseln 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)"
      }
  }
}

Weitere Informationen