Data Sources - Create Or Update

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

PUT {endpoint}/datasources('{dataSourceName}')?api-version=2024-07-01

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.

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:

The data change detection policy for the datasource.

dataDeletionDetectionPolicy DataDeletionDetectionPolicy:

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.

Responses

Name Type Description
200 OK

SearchIndexerDataSource

201 Created

SearchIndexerDataSource

Other Status Codes

ErrorResponse

Error response.

Examples

SearchServiceCreateOrUpdateDataSource

Sample request

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


{
  "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

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

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

HighWaterMarkChangeDetectionPolicy

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

SearchIndexerDataContainer

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

SearchIndexerDataSource

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

SearchIndexerDataSourceType

Defines the type of a datasource.

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.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

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.

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.

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:

The data change detection policy for the datasource.

dataDeletionDetectionPolicy DataDeletionDetectionPolicy:

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.

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.

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.

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.