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

Na Pesquisa de IA do Azure, é utilizada uma origem de dados com indexadores, fornecendo as informações de ligação para 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 de acordo com 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 definido pelo utilizador do seu serviço de pesquisa.
nome da origem de dados	Necessário no URI se estiver a utilizar PUT. O nome tem de ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. Depois de iniciar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e travessões, desde que os traços não sejam consecutivos.
api-version	Obrigatório. A versão estável atual é api-version=2020-06-30. Veja Versões da API para obter mais versões.

Cabeçalhos de 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. Uma chave de API é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. A opção Criar pedidos tem de incluir um api-key cabeçalho definido para a chave de administrador (em oposição a uma chave de consulta). Veja Connect to Azure AI Search using key authentication (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 da 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 utilizadas para identificar dados alterados ou eliminados de forma eficiente na origem de dados quando utilizado 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ó pode conter letras minúsculas, dígitos ou travessões, não pode iniciar ou terminar com travessões 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, este é o 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. Por 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 de esquema, como [dbo].[mytable]. Para o Azure Cosmos DB, especifica a coleção da 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. Por Armazenamento de Blobs do Azure, permite-lhe especificar uma pasta virtual no contentor de blobs. Por exemplo, para o caminho mycontainer/documents/blob.pdfdo 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 alternativa, utilize as vistas.
dataChangeDetectionPolicy	Opcional. Utilizado para identificar itens de dados alterados. As políticas suportadas variam com base no 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 da 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 . Por SQL do Azure, uma coluna indexada rowversion é a candidata 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 SQL do Azure conteúdo.
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 uma definição do keyVaultKeyName utilizador (necessária), uma gerada pelo keyVaultKeyVersion sistema (necessária) e uma keyVaultUri chave fornecida (necessária, também referida como nome DNS). Um URI de exemplo pode ser "https://my-keyvault-name.vault.azure.net". Opcionalmente, pode especificar accessCredentials se não está a utilizar uma identidade de sistema gerida. Propriedades de inclusão applicationId (ID da accessCredentials Aplicação do Azure Active Directory a quem foram concedidas permissões de acesso à sua Key Vault do Azure especificada) e applicationSecret (chave de autenticação da aplicação Azure AD especificada). 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 a deteção de alterações com a 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ções e eliminação podem ser omitidas se apenas pretender utilizar 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 adicional. 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": "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)"}
      }
}

Ver também

• Descrição geral do Indexador
• Criar indexadores
• Galeria de origens de dados