Créer une carte de synonymes (API REST Azure AI Search)

  • Article

Dans Recherche Azure AI, une carte de synonymes contient une liste de règles permettant d’étendre ou de réécrire une requête de recherche en termes équivalents.

Vous pouvez utiliser POST ou PUT sur la demande. Pour l’une ou l’autre, le document JSON dans le corps de la demande fournit la définition de l’objet.

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

Vous pouvez également utiliser une requête PUT en spécifiant le nom de la carte de synonymes sur l'URI.

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

Le protocole HTTPS est requis pour toutes les requêtes de service. Si la carte de synonymes n’existe pas, elle est créée. S’il existe déjà, il est mis à jour vers la nouvelle définition.

Notes

Le nombre maximal de mappages de synonymes que vous pouvez créer varie selon le niveau tarifaire. Pour plus d’informations, consultez Limites du Service.

Paramètres URI

Paramètre Description
nom du service Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche.
nom de la carte de synonymes Obligatoire sur l’URI si vous utilisez PUT. Le nom doit être en minuscules, commencer par une lettre ou un nombre, avoir aucune barre oblique ou point, et comporter moins de 128 caractères. Après avoir démarré le nom par une lettre ou un nombre, le reste du nom peut inclure n’importe quelle lettre, nombre et tirets, tant que les tirets ne sont pas consécutifs.
api-version Obligatoire. La version stable actuelle est api-version=2020-06-30. Pour plus d’informations, consultez Versions de l’API .

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.

Champs Description
Content-Type Obligatoire. À définir avec la valeur application/json
api-key Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la demande auprès de votre service de recherche. Les demandes de création doivent inclure un api-key en-tête défini sur votre clé d’administration (par opposition à une clé de requête). Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé .

Corps de la demande

Le corps de la demande contient une définition de carte de synonymes, qui inclut le format de la carte de synonymes et la liste des règles dans le format spécifié.

Le code JSON suivant est une représentation de haut niveau des parties main de la définition.

{   
    "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 requête peut contenir les propriétés suivantes :

Propriété Description
name Obligatoire. Nom de la carte de synonymes. Un nom de carte de synonymes ne doit contenir que des minuscules, des chiffres ou des tirets, ne peut pas commencer ou se terminer par des tirets et est limité à 128 caractères.
format Obligatoire. Seul le format Apache Solr (solr) est actuellement pris en charge.
Synonymes Obligatoire. Règles de synonyme séparées par le nouveau caractère de ligne (« \n ») .
encryptionKey facultatif. Utilisé pour chiffrer une carte de synonymes, avec vos propres clés, gérée dans votre Key Vault Azure. Disponible pour les services de recherche facturables créés le ou après le 01/01/01/2019.

Une encryptionKey section contient un défini par keyVaultKeyName l’utilisateur (obligatoire), un généré par keyVaultKeyVersion le système (obligatoire) et un keyVaultUri fournissant la clé (obligatoire, également appelé nom DNS). Un exemple d’URI peut être « https://my-keyvault-name.vault.azure.net".

Si vous le souhaitez, vous pouvez spécifier accessCredentials si vous n’utilisez pas d’identité système managée. Propriétés de accessCredentials include applicationId (ID d’application Azure Active Directory qui a obtenu des autorisations d’accès à votre Key Vault Azure spécifié) et applicationSecret (clé d’authentification de l’application Azure AD spécifiée). Un exemple de la section suivante illustre la syntaxe.

response

Pour une requête réussie : « 201 Créé ».

Exemples

Exemple : Liste de synonymes avec des mappages équivalents et explicites.

Une règle de mappage équivalente répertorie les termes ou expressions équivalents séparés par des virgules (« USA, États-Unis, États-Unis of America »). La règle étend la recherche à tous les termes ou expressions équivalents. Par exemple, un document de recherche qui contient USA correspond aux requêtes qui contiennent le terme USA ou les expressions "United States", ou "United States of America".

Le mappage explicite est indiqué par une flèche => (« USA, U.S.A., U.S.S., États-Unis, États-Unis of America => USA »). Quand elle est spécifiée, une séquence de termes d’une requête de recherche qui correspond au côté gauche de => sera remplacée par les alternatives situées à droite. Étant donné la règle, les requêtes U.S. de recherche ou "United States" seront toutes réécrites en USA. Le mappage explicite s’applique uniquement dans le sens spécifié et ne réécrit pas la requête USA"United States" dans ce cas. Notez que « États-Unis » est une requête d’expressions entre guillemets. Si vous souhaitez une correspondance sur l’ensemble de l’expression, la chaîne de requête doit être placée entre guillemets doubles. Sinon, chaque terme« United » et « States » est évalué séparément.

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

Exemple : clés de chiffrement

Les clés de chiffrement sont des clés gérées par le client utilisées pour un chiffrement supplémentaire. Pour plus d’informations, consultez Chiffrement à l’aide de clés gérées par le client dans 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)"
      }
  }
}

Voir aussi