Knowledge Bases - Create Or Update

Služba:
Search Service
Verze rozhraní API:
2026-04-01

Vytváří novou znalostní bázi nebo aktualizuje znalostní bázi, pokud už existuje.

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

Parametry identifikátoru URI

Name V Vyžadováno Typ Description
endpoint
 path True

string (uri)

Adresa URL koncového bodu vyhledávací služby.
knowledgeBaseName
 path True

string

Název znalostní báze.
api-version
 query True

string

minLength: 1

Verze rozhraní API, která se má použít pro tuto operaci.

Hlavička požadavku

Name Vyžadováno Typ Description
Accept

Accept

Hlavička Accept.
If-Match

string

Definuje podmínku If-Match. Operace bude provedena pouze v případě, že značka ETag na serveru odpovídá této hodnotě.
If-None-Match

string

Definuje podmínku If-None-Match. Operace bude provedena pouze v případě, že značka ETag na serveru neodpovídá této hodnotě.
Prefer True

Prefer

U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.
x-ms-client-request-id

string (uuid)

Neprůzrný globálně jedinečný identifikátor řetězce vygenerovaný klientem pro požadavek.

Text požadavku

Name Vyžadováno Typ Description
knowledgeSources True

KnowledgeSourceReference[]

Znalostní zdroje odkazující v této znalostní bázi.
name True

string

Název znalostní báze.
@odata.etag

string

Značka ETag znalostní báze.
description

string

Popis znalostní báze.
encryptionKey

SearchResourceEncryptionKey

Popis šifrovacího klíče, který vytvoříte v Azure Key Vault.
models KnowledgeBaseModel[]:

KnowledgeBaseAzureOpenAIModel[]

Obsahuje možnosti konfigurace, jak se připojit k modelům AI.

Odpovědi

Name Typ Description
200 OK

KnowledgeBase

Požadavek byl úspěšný.
201 Created

KnowledgeBase

Požadavek byl úspěšný a v důsledku toho byl vytvořen nový prostředek.
Other Status Codes

ErrorResponse

Neočekávaná chybová odpověď

Zabezpečení

api-key

Typ: apiKey
V: header

OAuth2Auth

Typ: oauth2
Tok: implicit
URL autorizace: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Rozsahy

Name Description
https://search.azure.com/.default

Příklady

SearchServiceCreateOrUpdateKnowledgeBase

Ukázkový požadavek

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

Ukázková odpověď

Stavový kód:
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>"
    }
  }
}
Stavový kód:
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>"
    }
  }
}

Definice

Name Description
Accept

Hlavička Accept.
AzureOpenAIModelName

Název modelu Azure Open AI, který se bude volat.
AzureOpenAIVectorizerParameters

Určuje parametry pro připojení k prostředku Azure OpenAI.
ErrorAdditionalInfo

Další informace o chybě správy prostředků
ErrorDetail

Podrobnosti o chybě.
ErrorResponse

Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)
KnowledgeBase

Představuje definici znalostní báze.
KnowledgeBaseAzureOpenAIModel

Určuje prostředek Azure OpenAI používaný k plánování dotazů.
KnowledgeBaseModelKind

Model umělé inteligence, který se má použít pro plánování dotazů.
KnowledgeSourceReference

Odkaz na zdroj znalostí.
Prefer

U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.
SearchIndexerDataNoneIdentity

Vymaže vlastnost identity zdroje dat.
SearchIndexerDataUserAssignedIdentity

Určuje identitu zdroje dat, která se má použít.
SearchResourceEncryptionKey

Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

Accept

Výčet

Hlavička Accept.

Hodnota Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Výčet

Název modelu Azure Open AI, který se bude volat.

Hodnota Description
text-embedding-ada-002

Model TextEmbeddingAda002.
text-embedding-3-large

TextEmbedding3Large model.
text-embedding-3-small

Model TextEmbedding3Small.
gpt-5-mini

Model Gpt5Mini.
gpt-5-nano

Model Gpt5Nano.
gpt-5.4-mini

Model Gpt54Mini.
gpt-5.4-nano

Model Gpt54Nano.

AzureOpenAIVectorizerParameters

Objekt

Určuje parametry pro připojení k prostředku Azure OpenAI.

Name Typ Description
apiKey

string

Klíč rozhraní API určeného prostředku Azure OpenAI
authIdentity SearchIndexerDataIdentity:

Spravovaná identita přiřazená uživatelem používaná pro odchozí připojení.
deploymentId

string

ID nasazení modelu Azure OpenAI v určeném prostředku
modelName

AzureOpenAIModelName

Název modelu vložení, který je nasazený na zadané cestě deploymentId.
resourceUri

string (uri)

Identifikátor URI prostředku Azure OpenAI.

ErrorAdditionalInfo

Objekt

Další informace o chybě správy prostředků

Name Typ Description
info

Další informace.
type

string

Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Name Typ Description
additionalInfo

ErrorAdditionalInfo[]

Další informace o chybě.
code

string

Kód chyby.
details

ErrorDetail[]

Podrobnosti o chybě.
message

string

Chybová zpráva.
target

string

Cíl chyby.

ErrorResponse

Objekt

Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)

Name Typ Description
error

ErrorDetail

Objekt chyby.

KnowledgeBase

Objekt

Představuje definici znalostní báze.

Name Typ Description
@odata.etag

string

Značka ETag znalostní báze.
description

string

Popis znalostní báze.
encryptionKey

SearchResourceEncryptionKey

Popis šifrovacího klíče, který vytvoříte v Azure Key Vault.
knowledgeSources

KnowledgeSourceReference[]

Znalostní zdroje odkazující v této znalostní bázi.
models KnowledgeBaseModel[]:

KnowledgeBaseAzureOpenAIModel[]

Obsahuje možnosti konfigurace, jak se připojit k modelům AI.
name

string

Název znalostní báze.

KnowledgeBaseAzureOpenAIModel

Objekt

Určuje prostředek Azure OpenAI používaný k plánování dotazů.

Name Typ Description
azureOpenAIParameters

AzureOpenAIVectorizerParameters

Azure OpenAI parametry.
kind string:

azureOpenAI

Model umělé inteligence, který se má použít pro plánování dotazů.

KnowledgeBaseModelKind

Výčet

Model umělé inteligence, který se má použít pro plánování dotazů.

Hodnota Description
azureOpenAI

K plánování dotazů používejte modely Azure Open AI.

KnowledgeSourceReference

Objekt

Odkaz na zdroj znalostí.

Name Typ Description
name

string

Název zdroje znalostí.

Prefer

Výčet

U požadavků HTTP PUT dává pokyn službě, aby v případě úspěchu vrátila vytvořený/aktualizovaný prostředek.

Hodnota Description
return=representation

SearchIndexerDataNoneIdentity

Objekt

Vymaže vlastnost identity zdroje dat.

Name Typ Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

Fragment identifikátoru URI určující typ identity.

SearchIndexerDataUserAssignedIdentity

Objekt

Určuje identitu zdroje dat, která se má použít.

Name Typ Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

Fragment identifikátoru URI určující typ identity.
userAssignedIdentity

string

Plně kvalifikované ID prostředku Azure spravované identity přiřazené uživatelem obvykle ve formátu /subscriptions/12345678-1234-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId, které by měly být přiřazeny vyhledávací službě.

SearchResourceEncryptionKey

Objekt

Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

Name Typ Description
accessCredentials.applicationId

string

ID aplikace AAD, kterému byla udělena požadovaná přístupová oprávnění ke službě Azure Key Vault, která se má použít při šifrování neaktivních uložených dat. ID aplikace by nemělo být zaměňováno s ID objektu pro vaši aplikaci AAD.
accessCredentials.applicationSecret

string

Ověřovací klíč zadané aplikace AAD.
identity SearchIndexerDataIdentity:

Explicitní spravovaná identita, která se má použít pro tento šifrovací klíč. Pokud není zadána vlastnost přihlašovacích údajů přístupu null, použije se spravovaná identita přiřazená systémem. Při aktualizaci prostředku zůstane explicitní identita beze změny. Pokud je zadána hodnota "none", hodnota této vlastnosti je vymazána.
keyVaultKeyName

string

Název klíče služby Azure Key Vault, který se má použít k šifrování neaktivních uložených dat.
keyVaultKeyVersion

string

Verze klíče služby Azure Key Vault, která se má použít k šifrování neaktivních uložených dat.
keyVaultUri

string

Identifikátor URI služby Azure Key Vault, označovaný také jako název DNS, který obsahuje klíč, který se má použít k šifrování neaktivních uložených dat. Příkladem identifikátoru URI může být https://my-keyvault-name.vault.azure.net.