シノニム マップの作成 (Azure AI Search REST API)
Azure AI Search では、シノニム マップには、検索クエリを同等の用語に拡張または書き換えるルールの一覧が含まれています。
要求に対して POST または PUT を使用できます。 どちらの場合も、要求本文の JSON ドキュメントによってオブジェクト定義が提供されます。
POST https://[service name].search.windows.net/synonymmaps?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
または、PUT を使用し、URI にシノニム マップ名を指定できます。
PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS はすべてのサービス要求に必要です。 シノニム マップが存在しない場合は、作成されます。 既に存在する場合は、新しい定義に更新されます。
注意
作成できるシノニム マップの最大数は、価格レベルによって異なります。 詳細については、サービスの制限に関する記事を参照してください。
URI パラメーター
| パラメーター | 説明 |
|---|---|
| サービス名 | 必須。 これを検索サービスの一意のユーザー定義名に設定します。 |
| シノニム マップ名 | PUT を使用する場合は、URI で必須です。 名前は小文字で、文字または数字で始まり、スラッシュやドットがなく、128 文字未満である必要があります。 名前を文字または数字で開始した後、ダッシュが連続していない限り、名前の残りの部分には任意の文字、数字、ダッシュを含めることができます。 |
| api-version | 必須。 現在の安定バージョンは です api-version=2020-06-30。 その他 のバージョンについては、「API のバージョン 」を参照してください。 |
要求ヘッダー
次の表では、必須と省略可能の要求ヘッダーについて説明します。
| フィールド | 説明 |
|---|---|
| Content-Type | 必須。 これを application/json |
| api-key |
Azure ロールを使用していて、要求でベアラー トークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。 要求の作成には、(クエリ キーではなく) 管理者キーに設定されたヘッダーを含める api-key 必要があります。 詳細については、「 キー認証を使用して Azure AI Search に接続 する」を参照してください。 |
要求本文
要求の本文にはシノニム マップ定義が含まれます。これには、シノニム マップの形式と、指定した形式のルールの一覧が含まれます。
次の JSON は、定義のメイン部分の大まかな表現です。
{
"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 }
}
要求には次のプロパティが含まれます。
| プロパティ | 説明 |
|---|---|
| name | 必須。 シノニム マップの名前。 シノニム マップ名には、小文字、数字、またはダッシュのみを含める必要があり、ダッシュで開始または終了することはできません。128 文字に制限されています。 |
| format | 必須。 現在、Apache Solr 形式 (solr) のみがサポートされています。 |
| シノニム | 必須。 改行 ('\n') 文字で区切られたシノニム規則。 |
| encryptionKey | 省略可能。 Azure Key Vaultで管理されている独自のキーを使用してシノニム マップを暗号化するために使用されます。 2019-01-01 以降に作成された課金対象の検索サービスで使用できます。
encryptionKeyセクションには、ユーザー定義 keyVaultKeyName (必須)、システムによって生成された keyVaultKeyVersion (必須)、およびkeyVaultUriキーを指定する (必須、DNS 名とも呼ばれます) が含まれます。 URI の例としては、"https://my-keyvault-name.vault.azure.net"" があります。
必要に応じて、マネージド システム ID を使用していないかどうかを指定 accessCredentials できます。 のaccessCredentialsプロパティには、(指定した Azure Key Vaultへのアクセス許可が付与された Azure Active Directory アプリケーション ID)、および applicationSecret (指定した Azure AD アプリケーションの認証キー) が含まれますapplicationId。 次のセクションの例は、構文を示しています。 |
Response
要求成功の場合: 201 作成されました。
例
例: 同等のマッピングと明示的なマッピングを持つシノニムの一覧。
同等のマッピング 規則では、コンマ ("USA、米国、米国 of America") で区切られた同等の用語または語句が一覧表示されます。 ルールは、検索を同等のすべての用語または語句に展開します。 たとえば、 を含む USA 検索ドキュメントは、用語 USA または語句 "United States"、または "United States of America"を含むクエリと一致します。
明示的なマッピングは、矢印 => ("USA、米国、米国、米国、米国 of America => USA") で示されます。 指定すると、 の左側 => に一致する検索クエリの用語シーケンスが、右側の代替に置き換えられます。 ルールを指定すると、検索クエリ U.S. または "United States" はすべて に USA書き換えられます。 明示的なマッピングは、指定された方向にのみ適用され、この場合はクエリ USA を に "United States" 書き換えません。 "米国" は引用符で囲まれた語句クエリであることに注意してください。 語句全体で一致する場合は、クエリ文字列を二重引用符で囲む必要があります。 それ以外の場合、"United" と "States" の各用語は個別に評価されます。
{
"name" : "synonymmap1",
"format" : "solr",
"synonyms" : "United States, United States of America, USA\n
Washington, Wash. => WA"
}
例: 暗号化キー
暗号化キーは、追加の暗号化に使用されるカスタマー マネージド キーです。 詳細については、「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)"
}
}
}