Data Sources - Create Or Update

Service:

Search Service

API Version:

2023-10-01-Preview

Creates a new datasource or updates a datasource if it already exists.

PUT {endpoint}/datasources('{dataSourceName}')?api-version=2023-10-01-Preview

With optional parameters:

PUT {endpoint}/datasources('{dataSourceName}')?api-version=2023-10-01-Preview&ignoreResetRequirements={ignoreResetRequirements}

URI Parameters

Name	In	Required	Type	Description
dataSourceName	path	True	string	The name of the datasource to create or update.
endpoint	path	True	string	The endpoint URL of the search service.
api-version	query	True	string	Client Api Version.
ignoreResetRequirements	query		boolean	Ignores cache reset requirements.

Request Header

Name	Required	Type	Description
x-ms-client-request-id		string uuid	The tracking ID sent with the request to help with debugging.
If-Match		string	Defines the If-Match condition. The operation will be performed only if the ETag on the server matches this value.
If-None-Match		string	Defines the If-None-Match condition. The operation will be performed only if the ETag on the server does not match this value.
Prefer	True	string	For HTTP PUT requests, instructs the service to return the created/updated resource on success.

Request Body

Name	Required	Type	Description
container	True	SearchIndexerDataContainer	The data container for the datasource.
credentials	True	DataSourceCredentials	Credentials for the datasource.
name	True	string	The name of the datasource.
type	True	SearchIndexerDataSourceType	The type of the datasource.
@odata.etag		string	The ETag of the data source.
dataChangeDetectionPolicy		DataChangeDetectionPolicy: HighWaterMarkChangeDetectionPolicy SqlIntegratedChangeTrackingPolicy	The data change detection policy for the datasource.
dataDeletionDetectionPolicy		DataDeletionDetectionPolicy: SoftDeleteColumnDeletionDetectionPolicy NativeBlobSoftDeleteDeletionDetectionPolicy	The data deletion detection policy for the datasource.
description		string	The description of the datasource.
encryptionKey		SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your datasource definition when you want full assurance that no one, not even Microsoft, can decrypt your data source definition. Once you have encrypted your data source definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your datasource definition will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.
identity		SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	An explicit managed identity to use for this datasource. If not specified and the connection string is a managed identity, the system-assigned managed identity is used. If not specified, the value remains unchanged. If "none" is specified, the value of this property is cleared.

Responses

Name	Type	Description
200 OK	SearchIndexerDataSource
201 Created	SearchIndexerDataSource
Other Status Codes	SearchError	Error response.

Examples

SearchServiceCreateOrUpdateDataSource

Sample request

HTTP

PUT https://myservice.search.windows.net/datasources('mydatasource')?api-version=2023-10-01-Preview


{
  "name": "mydocdbdatasource",
  "description": "My Cosmos DB data source.",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": "AccountEndpoint=https://myDocDbEndpoint.documents.azure.com;AccountKey=myDocDbAuthKey;Database=myDocDbDatabaseId"
  },
  "container": {
    "name": "myDocDbCollectionId",
    "query": "SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts"
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName": "isDeleted",
    "softDeleteMarkerValue": "true"
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

Sample response

Status code:

200

{
  "name": "mydocdbdatasource",
  "description": "My Cosmos DB data source.",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "myDocDbCollectionId",
    "query": "SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts"
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName": "isDeleted",
    "softDeleteMarkerValue": "true"
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

Status code:

201

{
  "name": "mydocdbdatasource",
  "description": "My Cosmos DB data source.",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "myDocDbCollectionId",
    "query": "SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts"
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName": "isDeleted",
    "softDeleteMarkerValue": "true"
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

Definitions

Name	Description
AzureActiveDirectoryApplicationCredentials	Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.
DataSourceCredentials	Represents credentials that can be used to connect to a datasource.
HighWaterMarkChangeDetectionPolicy	Defines a data change detection policy that captures changes based on the value of a high water mark column.
NativeBlobSoftDeleteDeletionDetectionPolicy	Defines a data deletion detection policy utilizing Azure Blob Storage's native soft delete feature for deletion detection.
SearchError	Describes an error condition for the API.
SearchIndexerDataContainer	Represents information about the entity (such as Azure SQL table or CosmosDB collection) that will be indexed.
SearchIndexerDataNoneIdentity	Clears the identity property of a datasource.
SearchIndexerDataSource	Represents a datasource definition, which can be used to configure an indexer.
SearchIndexerDataSourceType	Defines the type of a datasource.
SearchIndexerDataUserAssignedIdentity	Specifies the identity for a datasource to use.
SearchResourceEncryptionKey	A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps.
SoftDeleteColumnDeletionDetectionPolicy	Defines a data deletion detection policy that implements a soft-deletion strategy. It determines whether an item should be deleted based on the value of a designated 'soft delete' column.
SqlIntegratedChangeTrackingPolicy	Defines a data change detection policy that captures changes using the Integrated Change Tracking feature of Azure SQL Database.

AzureActiveDirectoryApplicationCredentials

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.

Name	Type	Description
applicationId	string	An AAD Application ID that was granted the required access permissions to the Azure Key Vault that is to be used when encrypting your data at rest. The Application ID should not be confused with the Object ID for your AAD Application.
applicationSecret	string	The authentication key of the specified AAD application.

DataSourceCredentials

Represents credentials that can be used to connect to a datasource.

Name	Type	Description
connectionString	string	The connection string for the datasource. Set to <unchanged> (with brackets) if you don't want the connection string updated. Set to <redacted> if you want to remove the connection string value from the datasource.

HighWaterMarkChangeDetectionPolicy

Defines a data change detection policy that captures changes based on the value of a high water mark column.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy	A URI fragment specifying the type of data change detection policy.
highWaterMarkColumnName	string	The name of the high water mark column.

NativeBlobSoftDeleteDeletionDetectionPolicy

Defines a data deletion detection policy utilizing Azure Blob Storage's native soft delete feature for deletion detection.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.NativeBlobSoftDeleteDeletionDetectionPolicy	A URI fragment specifying the type of data deletion detection policy.

SearchError

Describes an error condition for the API.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	SearchError[]	An array of details about specific errors that led to this reported error.
message	string	A human-readable representation of the error.

SearchIndexerDataContainer

Represents information about the entity (such as Azure SQL table or CosmosDB collection) that will be indexed.

Name	Type	Description
name	string	The name of the table or view (for Azure SQL data source) or collection (for CosmosDB data source) that will be indexed.
query	string	A query that is applied to this data container. The syntax and meaning of this parameter is datasource-specific. Not supported by Azure SQL datasources.

SearchIndexerDataNoneIdentity

Clears the identity property of a datasource.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	A URI fragment specifying the type of identity.

SearchIndexerDataSource

Represents a datasource definition, which can be used to configure an indexer.

Name	Type	Description
@odata.etag	string	The ETag of the data source.
container	SearchIndexerDataContainer	The data container for the datasource.
credentials	DataSourceCredentials	Credentials for the datasource.
dataChangeDetectionPolicy	DataChangeDetectionPolicy: HighWaterMarkChangeDetectionPolicy SqlIntegratedChangeTrackingPolicy	The data change detection policy for the datasource.
dataDeletionDetectionPolicy	DataDeletionDetectionPolicy: NativeBlobSoftDeleteDeletionDetectionPolicy SoftDeleteColumnDeletionDetectionPolicy	The data deletion detection policy for the datasource.
description	string	The description of the datasource.
encryptionKey	SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your datasource definition when you want full assurance that no one, not even Microsoft, can decrypt your data source definition. Once you have encrypted your data source definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your datasource definition will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	An explicit managed identity to use for this datasource. If not specified and the connection string is a managed identity, the system-assigned managed identity is used. If not specified, the value remains unchanged. If "none" is specified, the value of this property is cleared.
name	string	The name of the datasource.
type	SearchIndexerDataSourceType	The type of the datasource.

SearchIndexerDataSourceType

Defines the type of a datasource.

Name	Type	Description
adlsgen2	string	Indicates an ADLS Gen2 datasource.
azureblob	string	Indicates an Azure Blob datasource.
azuresql	string	Indicates an Azure SQL datasource.
azuretable	string	Indicates an Azure Table datasource.
cosmosdb	string	Indicates a CosmosDB datasource.
mysql	string	Indicates a MySql datasource.

SearchIndexerDataUserAssignedIdentity

Specifies the identity for a datasource to use.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	A URI fragment specifying the type of identity.
userAssignedIdentity	string	The fully qualified Azure resource Id of a user assigned managed identity typically in the form "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" that should have been assigned to the search service.

SearchResourceEncryptionKey

A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps.

Name	Type	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Optional Azure Active Directory credentials used for accessing your Azure Key Vault. Not required if using managed identity instead.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	An explicit managed identity to use for this encryption key. If not specified and the access credentials property is null, the system-assigned managed identity is used. On update to the resource, if the explicit identity is unspecified, it remains unchanged. If "none" is specified, the value of this property is cleared.
keyVaultKeyName	string	The name of your Azure Key Vault key to be used to encrypt your data at rest.
keyVaultKeyVersion	string	The version of your Azure Key Vault key to be used to encrypt your data at rest.
keyVaultUri	string	The URI of your Azure Key Vault, also referred to as DNS name, that contains the key to be used to encrypt your data at rest. An example URI might be https://my-keyvault-name.vault.azure.net.

SoftDeleteColumnDeletionDetectionPolicy

Defines a data deletion detection policy that implements a soft-deletion strategy. It determines whether an item should be deleted based on the value of a designated 'soft delete' column.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy	A URI fragment specifying the type of data deletion detection policy.
softDeleteColumnName	string	The name of the column to use for soft-deletion detection.
softDeleteMarkerValue	string	The marker value that identifies an item as deleted.

SqlIntegratedChangeTrackingPolicy

Defines a data change detection policy that captures changes using the Integrated Change Tracking feature of Azure SQL Database.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy	A URI fragment specifying the type of data change detection policy.