Eş Anlamlı Eşlemesi Oluşturma (Azure AI Arama REST API'si)

  • Makale

Azure AI Search'te eş anlamlı eşlem, arama sorgusunu eşdeğer terimlere genişletmeye veya yeniden yazmaya yönelik kuralların listesini içerir.

İstekte POST veya PUT kullanabilirsiniz. Her ikisinde de, istek gövdesindeki JSON belgesi nesne tanımını sağlar.

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

Alternatif olarak PUT kullanabilir ve URI'de eş anlamlı eşlem adını belirtebilirsiniz.

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

Tüm hizmet istekleri için HTTPS gereklidir. Eş anlamlı eşlemesi yoksa oluşturulur. Zaten varsa, yeni tanıma güncelleştirilir.

Not

Oluşturabileceğiniz en fazla eş anlamlı eşleme sayısı fiyatlandırma katmanına göre değişir. Daha fazla bilgi için bkz . Hizmet sınırları.

URI Parametreleri

Parametre Açıklama
hizmet adı Gereklidir. Bunu arama hizmetinizin benzersiz, kullanıcı tanımlı adı olarak ayarlayın.
eş anlamlı eşlem adı PUT kullanılıyorsa URI'de gereklidir. Ad küçük harfli olmalı, harf veya sayıyla başlamalıdır, eğik çizgi veya nokta içermemelidir ve 128 karakterden az olmalıdır. Adı bir harf veya sayıyla başlattıktan sonra, tireler ardışık olmadığından, adın geri kalanı herhangi bir harf, sayı ve kısa çizgi içerebilir.
api-sürümü Gereklidir. Geçerli kararlı sürüm şudur: api-version=2020-06-30. Daha fazla sürüm için bkz. API sürümleri.

İstek Üst Bilgileri

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.

Alanlar Description
İçerik Türü Gereklidir. Bunu olarak ayarlayın application/json
api-key İsteğe bağlı olarak, Azure rollerini kullanıyorsanız ve istekte taşıyıcı belirteç sağlanırsa, aksi takdirde bir anahtar gereklidir. Api anahtarı, arama hizmetinizde isteğin kimliğini doğrulayan, sistem tarafından oluşturulan benzersiz bir dizedir. Oluşturma istekleri, yönetici anahtarınıza ayarlanmış bir api-key üst bilgi içermelidir (sorgu anahtarının aksine). Ayrıntılar için bkz. Anahtar kimlik doğrulamasını kullanarak Azure AI Search'e bağlanma .

İstek Gövdesi

İsteğin gövdesi, eş anlamlı eşlem biçimini ve belirtilen biçimdeki kuralların listesini içeren bir eş anlamlı eşleme tanımı içerir.

Aşağıdaki JSON, tanımın ana bölümlerinin üst düzey bir gösterimidir.

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

İstek aşağıdaki özellikleri içerir:

Özellik Açıklama
name Gereklidir. Eş anlamlı eşlemesinin adı. Eş anlamlı eşlem adı yalnızca küçük harf, rakam veya tire içermelidir, tirelerle başlayamaz veya bitemez ve 128 karakterle sınırlıdır.
biçim Gereklidir. Şu anda yalnızca Apache Solr biçimi (solr) desteklenmektedir.
Eşanlamlı Gereklidir. Yeni satır ('\n') karakteriyle ayrılmış eş anlamlı kurallar.
encryptionKey İsteğe bağlı. Azure Key Vault yönetilen kendi anahtarlarınızla bir eş anlamlı eşlemeyi şifrelemek için kullanılır. 2019-01-01 veya sonrasında oluşturulan faturalanabilir arama hizmetleri için kullanılabilir.

Bir encryptionKey bölüm kullanıcı tanımlı keyVaultKeyName (gerekli), sistem tarafından oluşturulan keyVaultKeyVersion (gerekli) ve anahtarı sağlayan bir keyVaultUri (DNS adı olarak da adlandırılır) içerir. Örnek bir URI"https://my-keyvault-name.vault.azure.net".

İsteğe bağlı olarak, yönetilen sistem kimliği kullanıp kullanmayabileceğinizi belirtebilirsiniz accessCredentials . accessCredentials include applicationId özellikleri (belirtilen Azure Key Vault erişim izinleri verilmiş Azure Active Directory Uygulama Kimliği) ve applicationSecret (belirtilen Azure AD uygulamanın kimlik doğrulama anahtarı). Sonraki bölümdeki bir örnek söz dizimini gösterir.

Yanıt

Başarılı bir istek için: 201 Oluşturuldu.

Örnekler

Örnek: Eşdeğer ve açık eşlemelere sahip eş anlamlıların listesi.

Eşdeğer bir eşleme kuralı, virgülle ayrılmış eşdeğer terimleri veya tümcecikleri listeler ("ABD, Birleşik Devletler, Birleşik Devletler Amerika"). Kural, aramayı tüm eşdeğer terimlere veya tümceciklere genişletir. Örneğin, içeren USA bir arama belgesi terimini USA veya tümceciklerini içeren sorgularda "United States"veya "United States of America"ile eşleşecektir.

Açık eşleme bir okla => belirtilir ("ABD, ABD, ABD, Birleşik Devletler, Birleşik Devletler of America => ABD"). Belirtildiğinde, arama sorgusunun sol tarafıyla => eşleşen terim dizisi sağ taraftaki alternatiflerle değiştirilir. Kural göz önüne alındığında, arama sorguları U.S. veya "United States" tümü öğesine USAyeniden yazılır. Açık eşleme yalnızca belirtilen yönde geçerlidir ve bu durumda sorguyu USA"United States" yeniden yazmaz. "Birleşik Devletler" ifadesinin tırnak içine alınmış bir tümcecik sorgusu olduğuna dikkat edin. Tümceciğinin tamamında eşleşme olmasını istiyorsanız, sorgu dizesi çift tırnak içine alınmalıdır. Aksi takdirde, "Abd" ve "Eyaletler" terimleri ayrı ayrı değerlendirilir.

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

Örnek: Şifreleme anahtarları

Şifreleme anahtarları, ek şifreleme için kullanılan müşteri tarafından yönetilen anahtarlardır. Daha fazla bilgi için bkz. Azure Key Vault'de müşteri tarafından yönetilen anahtarları kullanarak şifreleme.

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

Ayrıca bkz.