Criar fonte de dados (API REST do Azure AI Search)

Artigo
11/13/2023

No Azure AI Search, uma fonte de dados é usada com indexadores, fornecendo as informações de conexão para a atualização de dados sob demanda ou agendada de um índice de destino, extraindo dados de fontes de dados do Azure com suporte.

Você pode usar POST ou PUT na solicitação. Para qualquer um deles, o documento JSON no corpo da solicitação fornece a definição de objeto.

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.

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. Se o objeto não existir, ele será criado. Se ele já existir, ele será atualizado para a nova definição.

Observação

O número máximo de índices que você pode criar varia de acordo com a faixa de preços. Para saber mais, confira Limites do serviço.

Parâmetros de URI

Parâmetro	Descrição
nome do serviço	Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
nome da fonte de dados	Necessário no URI se estiver usando PUT. O nome deve ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 caracteres. O nome deve começar com uma letra ou número, mas o restante do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.
api-version	Obrigatórios. Confira Versões de API para obter uma lista de versões com suporte.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos	Descrição
Tipo de conteúdo	Obrigatórios. Defina-o como `application/json`
chave de API	Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. As solicitações de criação devem incluir um `api-key` cabeçalho definido como sua chave de administrador (em vez de uma chave de consulta). Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Corpo da solicitação

O corpo da solicitação contém uma definição de fonte de dados, que inclui o tipo de fonte de dados, credenciais para ler os dados, bem como políticas de detecção de alterações de dados opcionais e 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 usadas com um indexador agendado periodicamente.

O JSON a seguir é uma representação de alto nível das partes main da definição.

{   
    "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": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

A contém as seguintes propriedades:

Propriedade	Descrição
name	Obrigatórios. O nome da fonte de dados. Um nome de fonte de dados deve conter apenas letras minúsculas, dígitos ou traços, não pode iniciar ou terminar com traços e está limitado a 128 caracteres.
descrição	Uma descrição opcional.
type	Obrigatórios. Deve ser um dos tipos de fonte de dados com suporte: `azuresql` para SQL do Azure banco de dados, Instância Gerenciada de SQL do Azure ou SQL Server instância em execução na VM `cosmosdb` do Azure para o Azure Cosmos DB for NoSQL, Azure Cosmos DB for MongoDB (versão prévia) ou Azure Cosmos DB for Apache Gremlin (versão prévia) `azureblob` para Armazenamento de Blobs do Azure `adlsgen2` para Azure Data Lake Storage Gen2 `azuretable` para o Armazenamento `azurefile` de Tabelas do Azure para Arquivos do Azure (versão prévia) `mysql` para Banco de Dados do Azure para MySQL (versão prévia) `sharepoint` para SharePoint no Microsoft 365(versão prévia)
credenciais	Obrigatórios. Ele contém uma `connectionString` propriedade que especifica o cadeia de conexão para a fonte de dados. O formato da cadeia de conexão depende do tipo de fonte de dados: para SQL do Azure Banco de Dados, essa é a SQL Server cadeia de conexão usual. Se você estiver usando portal do Azure para recuperar o cadeia de conexão, escolha a opção `ADO.NET connection string` . Para o Azure Cosmos DB, o 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]"`. Todos os valores são obrigatórios. Você pode encontrá-los no Portal do Azure. Para 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 blobs no Azure AI Search. O Armazenamento do Azure, o Banco de Dados SQL do Azure e o Azure Cosmos DB também dão suporte a uma identidade gerenciada cadeia de conexão que não incluem uma chave de conta no cadeia de conexão. Para usar a identidade gerenciada cadeia de conexão formato, siga as instruções para Configurar uma conexão de indexador com uma fonte de dados usando uma identidade gerenciada. Se você estiver atualizando a fonte de dados, o cadeia de conexão não será necessário. Os valores ou `<redacted>` podem ser usados `<unchanged>` no lugar do cadeia de conexão real.
contêiner	Obrigatórios. Especifica os dados a serem indexados usando as `name` propriedades (obrigatório) e `query` (opcional):`name` para SQL do Azure, especifica a tabela ou exibição. Você pode usar nomes qualificados pelo esquema, como `[dbo].[mytable]`. Para o Azure Cosmos DB, especifica a coleção de API do SQL. Para Armazenamento de Blobs do Azure, especifica o contêiner de armazenamento. Para o Armazenamento de Tabelas do Azure, especifica o nome da tabela. `query`: para o 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 AI Search pode indexar. Para Armazenamento de Blobs do Azure, permite que você especifique uma pasta virtual dentro do contêiner de blob. Por exemplo, para o caminho de blob `mycontainer/documents/blob.pdf`, `documents` pode ser usada como a pasta virtual. Para o Armazenamento de Tabelas do Azure, permite que você especifique uma consulta que filtra o conjunto de linhas a ser importado. Para SQL do Azure, não há suporte para consulta. Em vez disso, use modos de exibição.
dataChangeDetectionPolicy	Opcional. Usado para identificar itens de dados alterados. As políticas com suporte variam com base no tipo de fonte de dados. As políticas válidas são Política de Detecção de Alterações de Marca D'água Alta e Política de Detecção de Alterações Integrada do SQL. 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. Para fontes de dados do Cosmos DB, você deve usar a `_ts` propriedade . Para SQL do Azure, uma coluna indexada `rowversion` é o candidato ideal para uso com a política de marca d'água alta. Para o Armazenamento do Azure, a detecção de alterações é interna usando valores lastModified, eliminando qualquer necessidade de definir dataChangeDetectionPolicy para armazenamento de blobs ou tabelas. A Política de Detecção de Alterações Integrada do SQL é usada para referenciar os recursos nativos de detecção de alterações no SQL Server. Essa política só pode ser usada com tabelas; ele não pode ser usado com exibições. Você precisa habilitar o controle de alterações para a tabela que está usando antes de poder usar essa política. Confira Habilitar e desabilitar o controle de alterações para obter instruções. Para obter mais informações sobre o suporte à detecção de alterações no indexador, consulte Conectar e indexar SQL do Azure conteúdo.
dataDeletionDetectionPolicy	Opcional. Usado para identificar itens de dados excluídos. 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 de "exclusão temporária" na fonte de dados. Há suporte apenas para colunas com valores de cadeia de caracteres, inteiros ou boolianos. O valor usado como `softDeleteMarkerValue` deve ser uma cadeia de caracteres, mesmo que a coluna correspondente contenha números inteiros ou boolianos. Por exemplo, se o valor exibido na fonte de dados for 1, use "1" como o `softDeleteMarkerValue`.
encryptionKey	Opcional. Usado para criptografar a fonte de dados em repouso com suas próprias chaves, gerenciadas no Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou após 01-01/2019. Uma `encryptionKey` seção contém um definido `keyVaultKeyName` pelo usuário (obrigatório), um gerado pelo `keyVaultKeyVersion` sistema (obrigatório) e um `keyVaultUri` que fornece a chave (obrigatório, também conhecido como nome DNS). Um exemplo de URI pode ser "https://my-keyvault-name.vault.azure.net". Opcionalmente, você pode especificar `accessCredentials` se não está usando uma identidade do sistema gerenciado. Propriedades de `accessCredentials` include `applicationId` (Microsoft Entra ID ID do aplicativo que recebeu permissões de acesso para o Key Vault do Azure especificado) e `applicationSecret` (chave de autenticação do aplicativo registrado). Um exemplo na próxima seção ilustra a sintaxe.

Resposta

Para uma solicitação bem-sucedida: "201 Criado".

Exemplos

Exemplo: SQL do Azure com detecção de alterações (política de detecção de alteração de marca d'água alta)

{   
    "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ções (Política de Controle de Alterações Integrada do SQL)

{   
    "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ções com detecção de exclusão

Lembre-se de que as propriedades para detecção de exclusão são softDeleteColumnName e 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 necessárias

Propriedades opcionais relacionadas à detecção de alteração e exclusão poderão ser omitidas se você pretende usar apenas a fonte de dados para cópia única dos dados:

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

Se você pretende atualizar a fonte de dados, as credenciais não são necessárias. Os valores ou <redacted> podem ser usados <unchanged> no lugar do cadeia de conexão.

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

Exemplo: chaves de criptografia

As chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia extra. Para obter mais informações, consulte Criptografia usando chaves gerenciadas pelo cliente no 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": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}