Data Sources - Create

Reference

Service:: Search Service

API Version:: 2023-11-01

Creates a new datasource.

POST {endpoint}/datasources?api-version=2023-11-01

URI Parameters

Name	In	Required	Type	Description
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.

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	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
201 Created	SearchIndexerDataSource
Other Status Codes	SearchError	Error response.

Examples

SearchServiceCreateDataSource

Sample Request

HTTP

POST https://myservice.search.windows.net/datasources?api-version=2023-11-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": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

Sample Response

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": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": 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.
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.
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 on your search service, 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.

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.

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: 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 on your search service, 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.