Knowledge Bases - Create Or Update

Service:: Search Service

Version d'API:: 2026-04-01

Crée une nouvelle base de connaissances ou met à jour une base de connaissances si elle existe déjà.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
endpoint	path	True	string (uri)	URL du point de terminaison du service de recherche.
knowledgeBaseName	path	True	string	Nom de la base de connaissances.
api-version	query	True	string minLength: 1	Version de l’API à utiliser pour cette opération.

En-tête de la demande

Nom	Obligatoire	Type	Description
Accept		Accept	L’en-tête Accept.
If-Match		string	Définit la condition If-Match. L’opération ne sera effectuée que si l’ETag sur le serveur correspond à cette valeur.
If-None-Match		string	Définit la condition If-None-Match. L’opération ne sera effectuée que si l’ETag sur le serveur ne correspond pas à cette valeur.
Prefer	True	Prefer	Pour les requêtes HTTP PUT, indique au service de renvoyer la ressource créée/mise à jour en cas de réussite.
x-ms-client-request-id		string (uuid)	Identificateur de chaîne opaque, globalement unique et généré par le client pour la requête.

Corps de la demande

Nom	Obligatoire	Type	Description
knowledgeSources	True	KnowledgeSourceReference[]	Sources de connaissances référencées par cette base de connaissances.
name	True	string	Nom de la base de connaissances.
@odata.etag		string	L’ETag de la base de connaissances.
description		string	La description de la base de connaissances.
encryptionKey		SearchResourceEncryptionKey	Description d’une clé de chiffrement que vous créez dans Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contient des options de configuration sur la façon de se connecter aux modèles d’IA.

Réponses

Nom	Type	Description
200 OK	KnowledgeBase	La demande a réussi.
201 Created	KnowledgeBase	La requête a réussi et une nouvelle ressource a été créée en conséquence.
Other Status Codes	ErrorResponse	Réponse d’erreur inattendue.

Sécurité

api-key

Type: apiKey
Dans: header

OAuth2Auth

Type: oauth2
Flux: implicit
URL d’autorisation: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Étendues

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

Exemples

SearchServiceCreateOrUpdateKnowledgeBase

Exemple de requête

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

Exemple de réponse

Code d’état:: 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>"
    }
  }
}

Code d’état:: 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>"
    }
  }
}

Définitions

Nom	Description
Accept	L’en-tête Accept.
AzureOpenAIModelName	Nom du modèle Azure Open AI qui sera appelé.
AzureOpenAIVectorizerParameters	Spécifie les paramètres de connexion à la ressource Azure OpenAI.
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse à l’erreur courante pour toutes les API Azure Resource Manager afin de renvoyer les détails d’erreur pour les opérations ratées. (Cela suit également le format de réponse d’erreur OData.).
KnowledgeBase	Représente une définition de base de connaissances.
KnowledgeBaseAzureOpenAIModel	Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.
KnowledgeBaseModelKind	Le modèle d’IA à utiliser pour la planification des requêtes.
KnowledgeSourceReference	Référence à une source de connaissances.
Prefer	Pour les requêtes HTTP PUT, indique au service de renvoyer la ressource créée/mise à jour en cas de réussite.
SearchIndexerDataNoneIdentity	Efface la propriété d’identité d’une source de données.
SearchIndexerDataUserAssignedIdentity	Spécifie l’identité d’une source de données à utiliser.
SearchResourceEncryptionKey	Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

Accept

Énumération

L’en-tête Accept.

Valeur	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Énumération

Nom du modèle Azure Open AI qui sera appelé.

Valeur	Description
text-embedding-ada-002	TextEmbeddingAda002 modèle.
text-embedding-3-large	TextEmbedding3Large modèle.
text-embedding-3-small	TextEmbedding3Small modèle.
gpt-5-mini	Modèle Gpt5Mini.
gpt-5-nano	Modèle Gpt5Nano.
gpt-5.4-mini	Modèle Gpt54Mini.
gpt-5.4-nano	Modèle Gpt54Nano.

AzureOpenAIVectorizerParameters

Objet

Spécifie les paramètres de connexion à la ressource Azure OpenAI.

Nom	Type	Description
apiKey	string	Clé API de la ressource Azure OpenAI désignée.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée affectée par l’utilisateur utilisée pour les connexions sortantes.
deploymentId	string	ID du déploiement du modèle Azure OpenAI sur la ressource désignée.
modelName	AzureOpenAIModelName	Nom du modèle d’incorporation déployé sur le chemin d’accès deploymentId fourni.
resourceUri	string (uri)	URI de ressource de la ressource Azure OpenAI.

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info		Informations supplémentaires.
type	string	Type d’informations supplémentaire.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations supplémentaires sur l’erreur.
code	string	Code d’erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse à l’erreur courante pour toutes les API Azure Resource Manager afin de renvoyer les détails d’erreur pour les opérations ratées. (Cela suit également le format de réponse d’erreur OData.).

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

KnowledgeBase

Objet

Représente une définition de base de connaissances.

Nom	Type	Description
@odata.etag	string	L’ETag de la base de connaissances.
description	string	La description de la base de connaissances.
encryptionKey	SearchResourceEncryptionKey	Description d’une clé de chiffrement que vous créez dans Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Sources de connaissances référencées par cette base de connaissances.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contient des options de configuration sur la façon de se connecter aux modèles d’IA.
name	string	Nom de la base de connaissances.

KnowledgeBaseAzureOpenAIModel

Objet

Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.

Nom	Type	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI paramètres.
kind	string: azureOpenAI	Le modèle d’IA à utiliser pour la planification des requêtes.

KnowledgeBaseModelKind

Énumération

Le modèle d’IA à utiliser pour la planification des requêtes.

Valeur	Description
azureOpenAI	Utilisez les modèles Azure Open AI pour la planification des requêtes.

KnowledgeSourceReference

Objet

Référence à une source de connaissances.

Nom	Type	Description
name	string	Nom de la source de connaissances.

Prefer

Énumération

Pour les requêtes HTTP PUT, indique au service de renvoyer la ressource créée/mise à jour en cas de réussite.

Valeur	Description
return=representation

SearchIndexerDataNoneIdentity

Objet

Efface la propriété d’identité d’une source de données.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment d’URI spécifiant le type d’identité.

SearchIndexerDataUserAssignedIdentity

Objet

Spécifie l’identité d’une source de données à utiliser.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment d’URI spécifiant le type d’identité.
userAssignedIdentity	string	Id de ressource Azure complet d’une identité managée affectée par l’utilisateur sous la forme « /subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId » qui doit avoir été affecté au service de recherche.

SearchResourceEncryptionKey

Objet

Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

Nom	Type	Description
accessCredentials.applicationId	string	ID d’application AAD qui a reçu les autorisations d’accès requises au coffre de clés Azure à utiliser lors du chiffrement de vos données au repos. L’ID d’application ne doit pas être confondu avec l’ID d’objet de votre application AAD.
accessCredentials.applicationSecret	string	Clé d’authentification de l’application AAD spécifiée.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée explicite à utiliser pour cette clé de chiffrement. Si elle n’est pas spécifiée et que la propriété d’informations d’identification d’accès est null, l’identité managée affectée par le système est utilisée. Lors de la mise à jour vers la ressource, si l’identité explicite n’est pas spécifiée, elle reste inchangée. Si « none » est spécifié, la valeur de cette propriété est effacée.
keyVaultKeyName	string	Nom de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultKeyVersion	string	Version de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultUri	string	URI de votre coffre de clés Azure, également appelé nom DNS, qui contient la clé à utiliser pour chiffrer vos données au repos. Un exemple d’URI peut être `https://my-keyvault-name.vault.azure.net`.