Criar fonte de dados (API REST do Azure Pesquisa Cognitiva)Create Data Source (Azure Cognitive Search REST API)

No Azure Pesquisa Cognitiva, uma fonte de dados é usada com indexadores, fornecendo as informações de conexão para a atualização de dados ad hoc ou agendada de um índice de destino, obtendo dados de fontes de dados do Azure com suporte.In Azure Cognitive Search, a data source is used with indexers, providing the connection information for ad hoc or scheduled data refresh of a target index, pulling data from supported Azure data sources.

Você pode usar POST ou PUT na solicitação.You can use either POST or PUT on the request. Para qualquer um, o documento JSON no corpo da solicitação fornece a definição do objeto.For either one, the JSON document in the request body provides the object definition.

POST https://[service name].search.windows.net/datasources?api-version=[api-version]  
    Content-Type: application/json  
    api-key: [admin key]  

Como alternativa, você pode usar PUT e especificar o nome no URI.Alternatively, you can use PUT and specify the name on the URI.

PUT https://[service name].search.windows.net/datasources/[data source name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]    

HTTPS é necessário para todas as solicitações de serviço.HTTPS is required for all service requests. Se o objeto não existir, ele será criado.If the object doesn't exist, it is created. Se já existir, ela será atualizada para a nova definição.If it already exists, it is updated to the new definition

Observação

O número máximo de índices que você pode criar varia de acordo com a faixa de preços.The maximum number of indexes that you can create varies by pricing tier. Para obter mais informações, consulte limites de serviço para o Azure pesquisa cognitiva.For more information, see Service limits for Azure Cognitive Search.

Parâmetros de URIURI Parameters

ParâmetroParameter DescriçãoDescription
nome do serviçoservice name Obrigatórios.Required. Defina isso para o nome exclusivo definido pelo usuário do seu serviço de pesquisa.Set this to the unique, user-defined name of your search service.
nome da fonte de dadosdata source name Necessário no URI, se estiver usando PUT.Required on the URI if using PUT. O nome deve estar em letras minúsculas, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 caracteres.The name must be lower case, start with a letter or number, have no slashes or dots, and be fewer than 128 characters. Depois de iniciar o nome com uma letra ou número, o restante do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.After starting the name with a letter or number, the rest of the name can include any letter, number and dashes, as long as the dashes are not consecutive.
api-versionapi-version Obrigatórios.Required. A versão atual é api-version=2020-06-30.The current version is api-version=2020-06-30. Consulte versões de API no Azure pesquisa cognitiva para obter uma lista de versões disponíveis.See API versions in Azure Cognitive Search for a list of available versions.

Cabeçalhos de solicitaçãoRequest Headers

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionaisThe following table describes the required and optional request headers.

CamposFields DescriçãoDescription
Tipo de conteúdoContent-Type Obrigatórios.Required. Defina-o como application/jsonSet this to application/json
chave de APIapi-key Obrigatórios.Required. A api-key é usada para autenticar a solicitação para o serviço Search.The api-key is used to authenticate the request to your Search service. É um valor de cadeia de caracteres exclusivo de seu serviço.It is a string value, unique to your service. Solicitações de criação devem incluir um api-key cabeçalho definido para sua chave de administração (em oposição a uma chave de consulta).Create requests must include an api-key header set to your admin key (as opposed to a query key).

Você pode obter o api-key do seu painel de serviço no portal do Azure.You can get the api-key from your service dashboard in the Azure portal. Para obter mais informações, consulte Localizar chaves existentes.For more information, see Find existing keys.

Corpo da solicitaçãoRequest Body

O corpo da solicitação contém uma definição da fonte de dados, que inclui o tipo de fonte de dados, credenciais para ler os dados, bem como uma detecção de alterações de dados opcionais e as políticas de detecção de exclusão de dados que são usadas para identificar com eficiência dados alterados ou excluídos na fonte de dados quando usada com um indexador periodicamente agendadoThe body of the request contains a data source definition, which includes type of the data source, credentials to read the data, as well as an optional data change detection and data deletion detection policies that are used to efficiently identify changed or deleted data in the data source when used with a periodically scheduled indexer

O JSON a seguir é uma representação de alto nível das partes principais da definição.The following JSON is a high-level representation of the main parts of the definition.

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },  
    "container" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}  

A contém as seguintes propriedades:Request contains the following properties:

PropriedadeProperty DescriçãoDescription
namename Obrigatórios.Required. O nome da fonte de dados.The name of the data source. Um nome de fonte de dados deve conter apenas letras minúsculas, dígitos ou traços, não pode começar ou terminar com traços e está limitado a 128 caracteres.A data source name must only contain lowercase letters, digits or dashes, cannot start or end with dashes and is limited to 128 characters.
descriçãodescription Uma descrição opcional.An optional description.
tipotype Obrigatórios.Required. Deve ser um dos tipos de fonte de dados com suporte:Must be one of the supported data source types:

azuresql para o banco de dados SQL do Azureazuresql for Azure SQL Database
cosmosdb para a API do Azure Cosmos DB SQLcosmosdb for the Azure Cosmos DB SQL API
azureblob para o armazenamento de BLOBs do Azureazureblob for Azure Blob Storage
azuretable para o armazenamento de tabelas do Azureazuretable for Azure Table Storage
credenciaiscredentials Obrigatórios.Required. Ele contém uma connectionString propriedade que especifica a cadeia de conexão para a fonte de dados.It contains a connectionString property that specifies the connection string for the data source. O formato da cadeia de conexão depende do tipo de fonte de dados:The format of the connection string depends on the data source type:

Para o Banco de Dados SQL do Azure, essa é a cadeia de caracteres de conexão do SQL Server normal.For Azure SQL Database, this is the usual SQL Server connection string. Se você estiver usando portal do Azure para recuperar a cadeia de conexão, escolha a ADO.NET connection string opção.If you're using Azure portal to retrieve the connection string, choose the ADO.NET connection string option.

Para o Azure Cosmos DB, a cadeia de conexão deve estar no seguinte formato: "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]".For Azure Cosmos DB, the connection string must be in the following format: "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]". Todos os valores são obrigatórios.All of the values are required. Você pode encontrá-los no Portal do Azure.You can find them in the Azure portal.

Para o armazenamento de BLOBs do Azure, os formatos de cadeia de conexão são definidos na seção credenciais de como configurar a indexação de blob no pesquisa cognitiva.For Azure Blob Storage, the connection string formats are defined in the Credentials section of How to configure blob indexing in Cognitive Search.

O armazenamento do Azure, o banco de dados SQL do Azure e o Azure Cosmos DB também oferecem suporte a uma cadeia de conexão de identidade gerenciada que não inclui uma chave de conta na cadeia de conexão.Azure Storage, Azure SQL Database, and Azure Cosmos DB also support a managed identity connection string that does not include an account key in the connection string. Para usar o formato da cadeia de conexão de identidade gerenciada, siga as instruções para configurar uma conexão de indexador com uma fonte de dados usando uma identidade gerenciada.To use the managed identity connection string format, follow the instructions for Setting up an indexer connection to a data source using a managed identity.

Se você estiver atualizando a fonte de dados, a cadeia de conexão não será necessária.If you are updating the data source, the connection string is not required. Os valores <unchanged> ou <redacted> podem ser usados no lugar da cadeia de conexão real.The values <unchanged> or <redacted> can be used in place of the actual connection string.
contêinercontainer Obrigatórios.Required. Especifica os dados a serem indexados usando as name Propriedades (obrigatório) e query (opcional):Specifies the data to index using the name (required) and query (optional) properties:

name:name:
Para o SQL do Azure, especifica a tabela ou a exibição.For Azure SQL, specifies the table or view. Você pode usar nomes qualificados pelo esquema, como [dbo].[mytable].You can use schema-qualified names, such as [dbo].[mytable].
Por Azure Cosmos DB, especifica a coleção de API do SQL.For Azure Cosmos DB, specifies the SQL API collection.
Para o armazenamento de BLOBs do Azure, especifica o contêiner de armazenamento.For Azure Blob Storage, specifies the storage container.
Para o armazenamento de tabelas do Azure, especifica o nome da tabela.For Azure Table Storage, specifies the name of the table.

query:query:
Por Azure Cosmos DB, permite que você especifique uma consulta que nivela um layout de documento JSON arbitrário em um esquema simples que o Azure Pesquisa Cognitiva pode indexar.For Azure Cosmos DB, allows you to specify a query that flattens an arbitrary JSON document layout into a flat schema that Azure Cognitive Search can index.
Para o armazenamento de BLOBs do Azure, permite que você especifique uma pasta virtual dentro do contêiner de BLOB.For Azure Blob Storage, allows you to specify a virtual folder within the blob container. Por exemplo, para o caminho de blob mycontainer/documents/blob.pdf, documents pode ser usada como a pasta virtual.For example, for blob path mycontainer/documents/blob.pdf, documents can be used as the virtual folder.
Para o armazenamento de tabelas do Azure, permite que você especifique uma consulta que filtra o conjunto de linhas a ser importado.For Azure Table Storage, allows you to specify a query that filters the set of rows to be imported.
Para o Azure SQL, não há suporte para consulta.For Azure SQL, query is not supported. Use views em vez disso.Use views instead.
dataChangeDetectionPolicydataChangeDetectionPolicy Opcional.Optional. Usado para identificar itens de dados alterados.Used to identify changed data items. As políticas com suporte variam com base no tipo de fonte de dados.Supported policies vary based on the data source type. Políticas válidas são política de detecção de alteração de marca d' água alta e política de detecção de alteração integrada do SQL.Valid policies are High Watermark Change Detection Policy and SQL Integrated Change Detection Policy.

A política de detecção de alteração de marca d' água alta depende de uma coluna ou propriedade existente que é atualizada em conjunto com outras atualizações (todas as inserções resultam em uma atualização para a coluna de marca d' água) e a alteração no valor é maior.High Watermark Change Detection Policy depends on an existing column or property that is updated in tandem with other updates (all inserts result in an update to the watermark column), and the change in value is higher. Para Cosmos DB fontes de dados, você deve usar a _ts propriedade.For Cosmos DB data sources, you must use the _ts property. Para o SQL do Azure, uma coluna indexada rowversion é o candidato ideal para uso com a política de marca d' água alta.For Azure SQL, an indexed rowversion column is the ideal candidate for use with the high water mark policy. Para o armazenamento do Azure, a detecção de alteração é interna usando valores de lastModified, eliminando qualquer necessidade de definir o dataChangeDetectionPolicy para o armazenamento de BLOB ou de tabela.For Azure Storage, change detection is built-in using lastModified values, eliminating any need to set the dataChangeDetectionPolicy for blob or table storage.

A política de detecção de alteração integrada do SQL é usada para fazer referência aos recursos nativos de detecção de alterações no SQL Server.SQL Integrated Change Detection Policy is used to reference the native change detection features in SQL Server. Essa política só pode ser usada com tabelas; ela não pode ser usada com exibições.This policy can only be used with tables; it cannot be used with views. Você precisa habilitar o controle de alterações para a tabela que está usando antes de poder usar essa política.You need to enable change tracking for the table you're using before you can use this policy. Confira Habilitar e desabilitar o controle de alterações para obter instruções.See Enable and disable change tracking for instructions. Para obter mais informações sobre o suporte à detecção de alterações no indexador, consulte conectar e indexar conteúdo SQL do Azure.For more information about change detection support in the indexer, see Connect to and index Azure SQL content.
dataDeletionDetectionPolicydataDeletionDetectionPolicy Opcional.Optional. Usado para identificar itens de dados excluídos.Used to identify deleted data items. Atualmente, a única política com suporte é a política de exclusão reversível, que identifica itens excluídos com base no valor de uma coluna ou propriedade ' exclusão reversível ' na fonte de dados.Currently, the only supported policy is the Soft Delete Policy, which identifies deleted items based on the value of a 'soft delete' column or property in the data source.

Somente colunas com valores de cadeia de caracteres, inteiros ou boolianos são suportados.Only columns with string, integer, or boolean values are supported. O valor usado como softDeleteMarkerValue deve ser uma cadeia de caracteres, mesmo que a coluna correspondente contenha números inteiros ou boolianos.The value used as softDeleteMarkerValue must be a string, even if the corresponding column holds integers or booleans. Por exemplo, se o valor que aparece na fonte de dados for 1, use "1" como o softDeleteMarkerValue .For example, if the value that appears in your data source is 1, use "1" as the softDeleteMarkerValue.
encryptionKeyencryptionKey Opcional.Optional. Usado para criptografar a fonte de dados em repouso com suas próprias chaves, gerenciadas em seu Azure Key Vault.Used to encrypt the data source at rest with your own keys, managed in your Azure Key Vault. Disponível para serviços de pesquisa cobráveis criados em ou depois de 2019-01-01.Available for billable search services created on or after 2019-01-01.

Uma encryptionKey seção contém um definido pelo usuário keyVaultKeyName (obrigatório), um gerado pelo sistema keyVaultKeyVersion (obrigatório) e um keyVaultUri fornecendo a chave (obrigatória, também conhecida como nome DNS).An encryptionKey section contains a user-defined keyVaultKeyName (required), a system-generated keyVaultKeyVersion (required), and a keyVaultUri providing the key (required, also referred to as DNS name). Um URI de exemplo pode ser " https://my-keyvault-name.vault.azure.net ".An example URI might be "https://my-keyvault-name.vault.azure.net".

Opcionalmente, você pode especificar accessCredentials se não estiver usando uma identidade do sistema gerenciado.Optionally, you can specify accessCredentials if you are not using a managed system identity. As propriedades de accessCredentials include applicationId (Azure Active Directory ID do aplicativo que recebeu permissões de acesso para o Azure Key Vault especificado) e applicationSecret (chave de autenticação do aplicativo do Azure ad especificado).Properties of accessCredentials include applicationId (Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault), and applicationSecret (authentication key of the specified Azure AD application). Um exemplo na próxima seção ilustra a sintaxe.An example in the next section illustrates the syntax.
desabilitadodisabled Opcional.Optional. Valor booliano que indica se o indexador está desabilitado.Boolean value indicating whether the indexer is disabled. Falso por padrão.False by default.

RespostaResponse

Para uma solicitação bem-sucedida: "201 Criado".For a successful request: 201 Created.

ExemplosExamples

Exemplo: SQL do Azure com detecção de alteração (política de detecção de alteração de marca d' água alta)Example: Azure SQL with change detection (High Watermark Change Detection Policy)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}  

Exemplo: SQL do Azure com detecção de alteração (política de Controle de Alterações integrada do SQL)Example: Azure SQL with change detection (SQL Integrated Change Tracking Policy)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}  

Exemplo: SQL do Azure com detecção de alteração com detecção de exclusãoExample: Azure SQL with change detection with deletion detection

Lembre-se de que as propriedades de detecção de exclusão são softDeleteColumnName e softDeleteMarkerValue .Recall that the properties for deletion detection are softDeleteColumnName and softDeleteMarkerValue.

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}  

Exemplo: fonte de dados somente com propriedades obrigatóriasExample: Data source with required properties only

As propriedades opcionais relacionadas à detecção de alteração e exclusão podem ser omitidas se você pretende usar apenas a fonte de dados para uma cópia única dos dados:Optional properties related to change and deletion detection can be omitted if you only intend to use the data source for one-time copy of the data:

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}   

Exemplo: omitindo credenciaisExample: Omitting credentials

Se você pretende atualizar a fonte de dados, as credenciais não são necessárias.If you intend to update the data source, the credentials are not required. Os valores <unchanged> ou <redacted> podem ser usados no lugar da cadeia de conexão.The values <unchanged> or <redacted> can be used in place of the connection string.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

Exemplo: chaves de criptografiaExample: Encryption keys

Chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia adicional.Encryption keys are customer-managed keys used for additional encryption. Para obter mais informações, consulte criptografia usando chaves gerenciadas pelo cliente no Azure Key Vault.For more information, see Encryption using customer-managed keys in Azure Key Vault.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

Consulte tambémSee also