Knowledge Bases - Create Or Update

サービス:: Search Service

API バージョン:: 2026-04-01

新しいナレッジベースを作成したり、すでに存在しているナレッジベースを更新します。

PUT {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-04-01

URI パラメーター

名前	/	必須	型	説明
endpoint	path	True	string (uri)	検索サービスのエンドポイント URL。
knowledgeBaseName	path	True	string	ナレッジベースの名前。
api-version	query	True	string minLength: 1	この操作に使用する API バージョン。

要求ヘッダー

名前	必須	型	説明
Accept		Accept	Acceptヘッダーです。
If-Match		string	If-Match 条件を定義します。この操作は、サーバー上の ETag がこの値に一致する場合にのみ実行されます。
If-None-Match		string	If-None-Match 条件を定義します。この操作は、サーバー上の ETag がこの値と一致しない場合にのみ実行されます。
Prefer	True	Prefer	HTTP PUT 要求の場合、成功時に作成/更新されたリソースを返すようにサービスに指示します。
x-ms-client-request-id		string (uuid)	要求の非透過的なグローバルに一意のクライアント生成文字列識別子。

要求本文

名前	必須	型	説明
knowledgeSources	True	KnowledgeSourceReference[]	このナレッジベースで参照される知識源。
name	True	string	ナレッジベースの名前。
@odata.etag		string	ナレッジベースの ETag。
description		string	ナレッジベースの説明。
encryptionKey		SearchResourceEncryptionKey	Azure Key Vault で作成する暗号化キーの説明。
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	AI モデルへの接続方法に関する構成オプションが含まれています。

応答

名前	型	説明
200 OK	KnowledgeBase	要求は成功しました。
201 Created	KnowledgeBase	要求が成功し、結果として新しいリソースが作成されました。
Other Status Codes	ErrorResponse	予期しないエラー応答。

セキュリティ

api-key

型: apiKey
/: header

OAuth2Auth

型: oauth2
フロー: implicit
Authorization URL (承認 URL): https://login.microsoftonline.com/common/oauth2/v2.0/authorize

スコープ

名前	説明
https://search.azure.com/.default

例

SearchServiceCreateOrUpdateKnowledgeBase

要求のサンプル

HTTP

PUT https://exampleservice.search.windows.net/knowledgebases('base-example-index')?api-version=2026-04-01





{
  "name": "base-example-index",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      },
      "kind": "azureOpenAI"
    }
  ],
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the knowledge base."
}

応答のサンプル

状態コード:: 200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-example-index",
  "description": "Description of the knowledge base.",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

状態コード:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-example-index",
  "description": "Description of the knowledge base.",
  "knowledgeSources": [
    {
      "name": "ks-example-index"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-5-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

定義

名前	説明
Accept	Acceptヘッダーです。
AzureOpenAIModelName	呼び出される Azure Open AI モデル名。
AzureOpenAIVectorizerParameters	Azure OpenAI リソースに接続するためのパラメーターを指定します。
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	すべてのAzure Resource Manager APIで失敗した操作に対してエラー詳細を返す共通のエラー応答です。 (これは、OData エラー応答形式にも従います)。
KnowledgeBase	ナレッジベースの定義を表しています。
KnowledgeBaseAzureOpenAIModel	クエリ計画の実行に使用する Azure OpenAI リソースを指定します。
KnowledgeBaseModelKind	クエリ計画に使用される AI モデル。
KnowledgeSourceReference	知識源への言及。
Prefer	HTTP PUT 要求の場合、成功時に作成/更新されたリソースを返すようにサービスに指示します。
SearchIndexerDataNoneIdentity	データソースの ID プロパティをクリアします。
SearchIndexerDataUserAssignedIdentity	使用するデータソースの ID を指定します。
SearchResourceEncryptionKey	Azure Key Vault のカスタマーマネージド暗号化キー。作成および管理するキーを使用して、インデックスやシノニムマップなどの保存データの暗号化または暗号化解除を行うことができます。

Accept

列挙

Acceptヘッダーです。

値	説明
application/json;odata.metadata=minimal

AzureOpenAIModelName

列挙

呼び出される Azure Open AI モデル名。

値	説明
text-embedding-ada-002	TextEmbeddingAda002モデル。
text-embedding-3-large	TextEmbedding3Largeモデル。
text-embedding-3-small	TextEmbedding3Small モデル。
gpt-5-mini	GPT5Miniモデル。
gpt-5-nano	Gpt5Nanoモデルです。
gpt-5.4-mini	GPT54Miniモデル。
gpt-5.4-nano	Gpt54Nanoモデル。

AzureOpenAIVectorizerParameters

Object

Azure OpenAI リソースに接続するためのパラメーターを指定します。

名前	型	説明
apiKey	string	指定された Azure OpenAI リソースの API キー。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	送信接続に使用されるユーザー割り当てマネージド ID。
deploymentId	string	指定されたリソースに対する Azure OpenAI モデルデプロイの ID。
modelName	AzureOpenAIModelName	指定された deploymentId パスにデプロイされる埋め込みモデルの名前。
resourceUri	string (uri)	Azure OpenAI リソースのリソース URI。

ErrorAdditionalInfo

Object

リソース管理エラーの追加情報。

名前	型	説明
info		追加情報。
type	string	追加情報の種類。

ErrorDetail

Object

エラーの詳細。

名前	型	説明
additionalInfo	ErrorAdditionalInfo[]	エラーの追加情報。
code	string	エラーコード。
details	ErrorDetail[]	エラーの詳細。
message	string	エラーメッセージ。
target	string	エラーターゲット。

ErrorResponse

Object

すべてのAzure Resource Manager APIで失敗した操作に対してエラー詳細を返す共通のエラー応答です。 (これは、OData エラー応答形式にも従います)。

名前	型	説明
error	ErrorDetail	エラーオブジェクト。

KnowledgeBase

Object

ナレッジベースの定義を表しています。

名前	型	説明
@odata.etag	string	ナレッジベースの ETag。
description	string	ナレッジベースの説明。
encryptionKey	SearchResourceEncryptionKey	Azure Key Vault で作成する暗号化キーの説明。
knowledgeSources	KnowledgeSourceReference[]	このナレッジベースで参照される知識源。
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	AI モデルへの接続方法に関する構成オプションが含まれています。
name	string	ナレッジベースの名前。

KnowledgeBaseAzureOpenAIModel

Object

クエリ計画の実行に使用する Azure OpenAI リソースを指定します。

名前	型	説明
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAIパラメータ。
kind	string: azureOpenAI	クエリ計画に使用される AI モデル。

KnowledgeBaseModelKind

列挙

クエリ計画に使用される AI モデル。

値	説明
azureOpenAI	クエリ計画に Azure Open AI モデルを使用します。

KnowledgeSourceReference

Object

知識源への言及。

名前	型	説明
name	string	ナレッジソースの名前。

Prefer

列挙

HTTP PUT 要求の場合、成功時に作成/更新されたリソースを返すようにサービスに指示します。

値	説明
return=representation

SearchIndexerDataNoneIdentity

Object

データソースの ID プロパティをクリアします。

名前	型	説明
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	ID のタイプを指定する URI フラグメント。

SearchIndexerDataUserAssignedIdentity

Object

使用するデータソースの ID を指定します。

名前	型	説明
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	ID のタイプを指定する URI フラグメント。
userAssignedIdentity	string	通常、ユーザー割り当てマネージド ID の完全修飾 Azure リソース ID は、検索サービスに割り当てられている必要がある "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" の形式です。

SearchResourceEncryptionKey

Object

Azure Key Vault のカスタマーマネージド暗号化キー。作成および管理するキーを使用して、インデックスやシノニムマップなどの保存データの暗号化または暗号化解除を行うことができます。

名前	型	説明
accessCredentials.applicationId	string	保存データの暗号化時に使用される Azure Key Vault に対する必要なアクセス許可が付与された AAD アプリケーション ID。アプリケーション ID は、AAD アプリケーションのオブジェクト ID と混同しないでください。
accessCredentials.applicationSecret	string	指定した AAD アプリケーションの認証キー。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	この暗号化キーに使用する明示的なマネージド ID。指定されず、アクセス資格情報プロパティが null の場合は、システム割り当てマネージド ID が使用されます。リソースの更新時に、明示的な ID が指定されていない場合、変更されません。 "none" が指定されている場合、このプロパティの値はクリアされます。
keyVaultKeyName	string	保存データの暗号化に使用する Azure Key Vault キーの名前。
keyVaultKeyVersion	string	保存データの暗号化に使用する Azure Key Vault キーのバージョン。
keyVaultUri	string	保存データの暗号化に使用するキーを含む Azure Key Vault の URI (DNS 名とも呼ばれます)。 URI の例は、`https://my-keyvault-name.vault.azure.net`可能性があります。