Criar Origem de Dados (API REST da Pesquisa de IA do Azure)

Artigo
02/28/2024

No Azure AI Search, é utilizada uma origem de dados com indexadores, fornecendo as informações de ligação para a atualização de dados a pedido ou agendada de um índice de destino, solicitando dados de origens de dados do Azure suportadas.

Pode utilizar POST ou PUT no pedido. Para qualquer um deles, o documento JSON no corpo do pedido fornece a definição do objeto.

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

Em alternativa, pode utilizar 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]

O HTTPS é necessário para todos os pedidos de serviço. Se o objeto não existir, é criado. Se já existir, será atualizado para a nova definição.

Nota

O número máximo de índices que pode criar varia consondo o escalão de preço. Para obter mais informações, veja Limites de serviço.

Parâmetros do URI

Parâmetro	Description
nome do serviço	Obrigatório. Defina-o como o nome exclusivo e definido pelo utilizador do seu serviço de pesquisa.
nome da origem de dados	Necessário no URI se utilizar PUT. O nome tem de ser minúscula, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. O nome tem de começar com uma letra ou número, mas o resto do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.
api-version	Obrigatório. Veja Versões da API para obter uma lista de versões suportadas.

Cabeçalhos do Pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Campos	Description
Content-Type	Obrigatório. Defina esta opção como `application/json`
api-key	Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Criar pedidos tem de incluir um `api-key` cabeçalho definido para a sua chave de administrador (em oposição a uma chave de consulta). Veja Ligar à Pesquisa de IA do Azure com a autenticação de chaves para obter detalhes.

Corpo do Pedido

O corpo do pedido contém uma definição de origem de dados, que inclui o tipo de origem de dados, credenciais para ler os dados, bem como uma deteção de alteração de dados opcional e políticas de deteção de eliminação de dados que são utilizadas para identificar dados alterados ou eliminados de forma eficiente na origem de dados quando utilizados com um indexador agendado periodicamente.

O seguinte JSON é uma representação de alto nível das partes principais 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) { }
}

O pedido contém as seguintes propriedades:

Propriedade	Descrição
name	Obrigatório. O nome da origem de dados. Um nome de origem de dados só tem de conter letras minúsculas, dígitos ou traços, não pode iniciar ou terminar com traços e está limitado a 128 carateres.
descrição	Uma descrição opcional.
tipo	Obrigatório. Tem de ser um dos tipos de origem de dados suportados: `azuresql` para SQL do Azure Base de Dados, Azure SQL Managed Instance ou SQL Server instância em execução na VM `cosmosdb` do Azure para o Azure Cosmos DB para NoSQL, Azure Cosmos DB para MongoDB (pré-visualização) ou Azure Cosmos DB para Apache Gremlin (pré-visualização) `azureblob` para Armazenamento de Blobs do Azure `adlsgen2` para Azure Data Lake Storage Gen2 `azuretable` para o Armazenamento `azurefile` de Tabelas do Azure para Ficheiros do Azure (pré-visualização) `mysql` para Base de Dados do Azure para MySQL (pré-visualização) `sharepoint` para o SharePoint no Microsoft 365(pré-visualização)
credenciais	Obrigatório. Contém uma `connectionString` propriedade que especifica a cadeia de ligação para a origem de dados. O formato do cadeia de ligação depende do tipo de origem de dados: para SQL do Azure Base de Dados, esta é a SQL Server cadeia de ligação habitual. Se estiver a utilizar portal do Azure para obter o cadeia de ligação, selecione a opção`ADO.NET connection string`. Para o Azure Cosmos DB, o cadeia de ligação tem de 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 necessários. Pode encontrá-los no portal do Azure. Para Armazenamento de Blobs do Azure, os formatos de cadeia de ligação são definidos na secção Credenciais de Como configurar a indexação de blobs no Azure AI Search. O Armazenamento do Azure, a Base de Dados SQL do Azure e o Azure Cosmos DB também suportam uma identidade gerida cadeia de ligação que não inclui uma chave de conta no cadeia de ligação. Para utilizar a identidade gerida cadeia de ligação formato, siga as instruções para Configurar uma ligação de indexador a uma origem de dados com uma identidade gerida. Se estiver a atualizar a origem de dados, a cadeia de ligação não é necessária. Os valores ou `<redacted>` podem ser utilizados `<unchanged>` em vez da cadeia de ligação real.
contentor	Obrigatório. Especifica os dados a indexar com as `name` propriedades (necessárias) e `query` (opcionais):`name` : Para SQL do Azure, especifica a tabela ou vista. Pode utilizar nomes qualificados para esquemas, como `[dbo].[mytable]`. Para o Azure Cosmos DB, especifica a coleção de API SQL. Para Armazenamento de Blobs do Azure, especifica o contentor de armazenamento. Para o Armazenamento de Tabelas do Azure, especifica o nome da tabela. `query`: Para o Azure Cosmos DB, permite-lhe especificar uma consulta que aplana um esquema de documento JSON arbitrário num esquema simples que o Azure AI Search pode indexar. Para Armazenamento de Blobs do Azure, permite-lhe especificar uma pasta virtual no contentor de blobs. Por exemplo, para o caminho `mycontainer/documents/blob.pdf`do blob, `documents` pode ser utilizado como a pasta virtual. Para o Armazenamento de Tabelas do Azure, permite-lhe especificar uma consulta que filtra o conjunto de linhas a importar. Para SQL do Azure, a consulta não é suportada. Em vez disso, utilize vistas.
dataChangeDetectionPolicy	Opcional. Utilizado para identificar itens de dados alterados. As políticas suportadas variam consoante o tipo de origem de dados. As políticas válidas são a Política de Deteção de Alterações de Marca d'Água Elevada e a Política de Deteção de Alterações Integrada do SQL. A Política de Deteção de Alterações de Marca d'Água elevada depende de uma coluna ou propriedade existente que é atualizada em conjunto com outras atualizações (todas as inserções resultam numa atualização para a coluna de marca d'água) e a alteração no valor é superior. Para origens de dados do Cosmos DB, tem de utilizar a `_ts` propriedade. Para SQL do Azure, uma coluna indexada `rowversion` é o candidato ideal para utilização com a política de marca de água elevada. Para o Armazenamento do Azure, a deteção de alterações é incorporada com valores lastModified, eliminando qualquer necessidade de definir dataChangeDetectionPolicy para armazenamento de blobs ou tabelas. A Política de Deteção de Alterações Integrada do SQL é utilizada para referenciar as funcionalidades de deteção de alterações nativas no SQL Server. Esta política só pode ser utilizada com tabelas; não pode ser utilizado com vistas. Tem de ativar o controlo de alterações para a tabela que está a utilizar antes de poder utilizar esta política. Veja Ativar e desativar o controlo de alterações para obter instruções. Para obter mais informações sobre o suporte de deteção de alterações no indexador, veja Ligar a e indexar conteúdo SQL do Azure.
dataDeletionDetectionPolicy	Opcional. Utilizado para identificar itens de dados eliminados. Atualmente, a única política suportada é a Política de Eliminação Recuperável, que identifica itens eliminados com base no valor de uma coluna ou propriedade de "eliminação recuperável" na origem de dados. Só são suportadas colunas com valores de cadeia, número inteiro ou booleano. O valor utilizado como `softDeleteMarkerValue` tem de ser uma cadeia, mesmo que a coluna correspondente contenha números inteiros ou booleanos. Por exemplo, se o valor que aparece na sua origem de dados for 1, utilize "1" como .`softDeleteMarkerValue`
encryptionKey	Opcional. Utilizado para encriptar a origem de dados inativa com as suas próprias chaves, geridas no seu Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou depois de 2019-01-01. Uma `encryptionKey` secção contém um definido pelo utilizador `keyVaultKeyName` (obrigatório), um gerado pelo `keyVaultKeyVersion` sistema (obrigatório) e uma `keyVaultUri` chave de fornecimento (obrigatório, também referido como nome DNS). Um URI de exemplo pode ser "https://my-keyvault-name.vault.azure.net". Opcionalmente, pode especificar `accessCredentials` se não estiver a utilizar uma identidade de sistema gerida. Propriedades de `accessCredentials` include `applicationId` (Microsoft Entra ID ID da aplicação a que foram concedidas permissões de acesso ao Key Vault do Azure especificado) e `applicationSecret` (chave de autenticação da aplicação registada). Um exemplo na secção seguinte ilustra a sintaxe.

Resposta

Para um pedido com êxito: 201 Criado.

Exemplos

Exemplo: SQL do Azure com a deteção de alterações (Política de Deteção de Alterações de Marca d'Água Elevada)

{   
    "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 a deteção de alterações (Política de Controlo 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 deteção de alterações com deteção de eliminação

Lembre-se de que as propriedades para deteção de eliminaçã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: origem de dados apenas com propriedades necessárias

As propriedades opcionais relacionadas com a deteção de alteração e eliminação podem ser omitidas se pretender utilizar apenas a origem de dados para uma 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: Omitir credenciais

Se pretender atualizar a origem de dados, as credenciais não são necessárias. Os valores ou <redacted> podem ser utilizados <unchanged> em vez do cadeia de ligação.

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

Exemplo: Chaves de encriptação

As chaves de encriptação são chaves geridas pelo cliente utilizadas para encriptação extra. Para obter mais informações, veja Encriptação com chaves geridas 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)"}
      }
}

Partilhar via