Partilhar via

Criar ou atualizar fonte de dados (API REST de visualização)

  • Artigo

Aplica-se a: 2023-07-01-Preview. Esta versão não é mais suportada. Atualize imediatamente para uma versão mais recente.

Importante

2023-07-01-Preview (sem alterações).

2021-04-30-Preview adiciona suporte de identidade gerenciada para conexões de indexador a outros recursos do Azure:

  • "credenciais" aceita uma ID de recurso do Azure como um valor, desde que o serviço de pesquisa seja executado sob uma identidade gerenciada e as atribuições de função do Azure concedam acesso de leitura aos dados.
  • "identidade" aceita uma identidade gerenciada atribuída pelo usuário. Esta propriedade é de primeiro nível para conexões de dados. Também está sob "encryptionKey" para recuperar uma chave gerenciada pelo cliente no Cofre de Chaves do Azure.
  • suporte a Arquivos do Azure está em visualização. Use uma API de visualização para indexar a partir dessa fonte de dados.

2020-06-30-Preview adiciona:

  • "dataDeletionDetectionPolicy" aceita "NativeBlobSoftDeleteDeletionDetectionPolicy" para indexadores de blob.
  • suporte a do Banco de Dados do Azure para MySQL está em visualização. Use uma API de visualização para indexar a partir dessa fonte de dados.
  • Cosmos DB, MongoDB API e Gremlin API suporte está em visualização. Use uma API de visualização para indexar a partir dessa fonte de dados.

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

Você pode usar POST ou PUT em uma solicitação de criação. Para qualquer um deles, o corpo da solicitação 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]

Para solicitações de atualização, use PUT e especifique o nome do indexador 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 já existir, é substituído usando a nova definição.

Observação

Depois que uma fonte de dados existe, você não pode alterar a propriedade type em uma solicitação de atualização. Em vez disso, você deve criar uma nova fonte de dados usando o tipo desejado.

Parâmetros de URI

Parâmetro Descrição
Nome do serviço Necessário. Defina isso como o nome exclusivo e definido pelo usuário do seu serviço de pesquisa.
Nome da fonte de dados Obrigató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. Depois de iniciar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.
API-versão Necessário. Consulte de versões da API para obter mais versões.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Campos Descrição
Tipo de conteúdo Necessário. Defina isso como application/json
Chave 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. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação no seu serviço de pesquisa. As solicitações de criação devem incluir um cabeçalho api-key definido para sua chave de administrador (em vez de uma chave de consulta). Consulte Conectar-se à Pesquisa de IA do Azure usando de autenticação de chave para obter detalhes.

Órgão do Pedido

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 uma deteção de alteração de dados opcional e políticas de deteção de exclusão de dados que são usadas para identificar eficientemente dados alterados ou excluídos na fonte de dados quando usados com um indexador agendado periodicamente

O JSON a seguir é 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" : (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 },
    "identity": (optional) {Sets the Resource ID of a managed identity. See below for details },
    "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.",
      "identity": "(Resource ID of a user-assigned managed identity, used for connecting to key vault)",
      "accessCredentials": (Credentials for connecting to key vault. Omit if using a managed identity) {
        "applicationId": "Azure AD Application ID that has access permissions to the key vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

Request contém as seguintes propriedades:

Propriedade Descrição
Designação Necessário. 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 começar ou terminar com traços e é limitado a 128 caracteres.
Descrição Uma descrição opcional.
tipo Necessário. Deve ser um dos tipos de fonte de dados suportados:

adlsgen2 para Azure Data Lake Storage Gen2
azureblob para Azure Blob Storage
azurefiles para Azure File Storage
azuresql para Banco de Dados SQL do Azure
azuretable para
cosmosdb de Armazenamento de Tabela do Azure para o Azure Cosmos DB API SQL, da API do MongoDB,
mysql da API Gremlin para Banco de Dados do Azure para MySQL
credenciais Necessário. Contém uma propriedade connectionString que especifica como se conectar.
contentor Necessário. Especifica o contêiner, coleção, tabela ou exibição que contém os dados a serem indexados.
dataChangeDetectionPolicy Opcional. Especifica o mecanismo fornecido pela plataforma de dados para identificar itens de dados alterados.
dataDeletionDetectionPolicy Opcional. Identifica como a plataforma de dados exclui dados.
encryptionKey Opcional. Usado para criptografia adicional de credenciais de fonte de dados, por meio de chaves de criptografia gerenciadas pelo cliente (CMK) no Cofre de Chaves do Azure. Disponível para serviços de pesquisa faturáveis criados em ou após 2019-01-01.
deficientes Opcional. Valor booleano que indica se o indexador é criado em um estado desabilitado, o que impede que ele seja executado imediatamente. Falso por padrão.
identidade Opcional. Ele contém uma userAssignedIdentity do tipo #Microsoft.Azure.Search.DataUserAssignedIdentity e especifica a de identidade gerenciada atribuída pelo usuário do recurso externo. Essa propriedade depende de credentials ter a cadeia de conexão no formato correto (uma ID de recurso) para conexões de identidade gerenciadas para cada tipo de fonte de dados.

Se a propriedade identity for nula, a conexão com uma ID de recurso será feita usando a propriedade gerenciada pelo sistema.

Se essa propriedade for atribuída ao tipo #Microsoft.Azure.Search.DataNoneIdentity, qualquer identidade explícita que tenha sido especificada anteriormente será limpa.

Resposta

Para uma solicitação bem-sucedida: 201 Criado se uma nova fonte de dados tiver sido criada e 204 Sem Conteúdo se uma fonte de dados existente tiver sido atualizada.

Exemplos

Exemplo: funções do Azure e uma identidade gerenciada atribuída ao sistema

Se o serviço de pesquisa tiver uma identidade gerenciada atribuída pelo sistema e uma atribuição de função, a conexão da fonte de dados poderá ser o ID de recurso exclusivo da sua conta de armazenamento.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
  }

Exemplo: funções do Azure e uma identidade gerenciada atribuída pelo usuário (visualização)

Este exemplo demonstra uma conexão autenticada do Azure AD para um serviço de pesquisa que tem uma identidade gerenciada atribuída pelo usuário.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]"
    }
  }

Exemplo: SQL do Azure com deteção de alterações (Política de Deteção de Alterações 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 deteção de alterações (Política Integrada de Controle de Alterações 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 exclusão

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

As propriedades opcionais relacionadas à deteção de alterações e exclusões podem ser omitidas se você pretender usar a fonte de dados apenas 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: Usando a opção de credencial inalterada ou editada

Se você pretende atualizar a fonte de dados, as credenciais não são necessárias. Os valores <unchanged> ou <redacted> podem ser usados no lugar da 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 adicional. 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 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)"}
      }
}

Exemplo: conexões de cofre de chave de criptografia por serviços de pesquisa com uma identidade gerenciada atribuída pelo usuário

Este exemplo omite accessCredentials. Para um recurso que tenha um identidade gerenciada atribuída pelo usuário atribuído a ele, você pode especificar a identidade em encryptionKey e recuperar a chave usando essa identidade e atribuições de função do Azure.

{
    "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",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-identity"
        }
    }
}

Definições

Ligação Descrição
contentor Especifica o contêiner, coleção, tabela ou exibição que contém os dados a serem indexados.
credenciais Contém uma propriedade connectionString que especifica como um indexador se conecta a um recurso do Azure.
dataChangeDetectionPolicy Especifica o mecanismo fornecido pela plataforma de dados para identificar dados alterados.
dataDeletionDetectionPolicy Especifica o mecanismo para detetar dados excluídos.
encryptionKey Configura uma conexão com o Cofre de Chaves do Azure para criptografia gerenciada pelo cliente.

contentor

Especifica o contêiner, coleção, tabela ou exibição que contém os dados a serem indexados.

Atributo Descrição
Designação Necessário. Para o Azure Cosmos DB, especifica a coleção de API SQL. Para o Armazenamento de Blobs do Azure, especifica o contêiner de armazenamento. Para o Azure SQL, especifica a tabela ou exibição. Você pode usar nomes qualificados por esquema, como [dbo].[mytable]. Para o Armazenamento de Tabela do Azure, especifica o nome da tabela.
consulta Opcional. Para o Azure Cosmos DB, permite especificar uma consulta que nivela um layout de documento JSON arbitrário em um esquema simples que o Azure AI Search pode indexar. Para o Armazenamento de Blobs do Azure, permite especificar uma pasta virtual dentro do contêiner de blob. Por exemplo, para o caminho de blob mycontainer/documents/blob.pdf, documents pode ser usado como a pasta virtual. Para o Armazenamento de Tabela do Azure, permite especificar uma consulta que filtra o conjunto de linhas a serem importadas. Para o Azure SQL, a consulta não é suportada (use modos de exibição em vez disso).

Credenciais

Contém uma propriedade "connectionString" que especifica como um indexador se conecta a um recurso do Azure.

Atributo Descrição
connectionString Necessário. Especifica uma conexão com uma fonte de dados do indexador. Se você estiver atualizando a definição da fonte de dados, a cadeia de conexão não será necessária. Os valores <unchanged> ou <redacted> podem ser usados no lugar da cadeia de conexão real.

Para conexões autenticadas usando chaves ou credenciais de entrada, esses valores são visíveis na cadeia de conexão. O formato da cadeia de conexão depende do tipo de fonte de dados:

Para o Banco de Dados SQL do Azure, essa é a cadeia de conexão usual do SQL Server. Se você estiver usando o portal do Azure para recuperar a cadeia de conexão, escolha a opção ADO.NET connection string.

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]". Todos os valores são obrigatórios. Você pode encontrá-los no portal do Azure.

Se você estiver usando uma identidade gerenciada para autenticar, poderá omitir credenciais na conexão.

Para conexões autenticadas usando uma identidade gerenciada, a cadeia de conexão especifica a ID do recurso do Azure (consulte estes links para o formato da cadeia de conexão: de Armazenamento do Azure, Cosmos DBBanco de Dados SQL).

As atribuições de função com escopo para a fonte de dados externa determinam se o indexador pode se conectar e o serviço de pesquisa deve ser configurado para ser executado como um serviço confiável no Azure Ative Directory.

Se a propriedade "identity" também for especificada, a conexão será feita usando a identidade gerenciada atribuída pelo usuário do serviço de pesquisa fornecida pela propriedade "identity". Caso contrário, se "identity" não for especificado ou nulo, a conexão será através da identidade gerenciada pelo sistema.

dataChangeDetectionPolicy

Especifica o mecanismo fornecido pela plataforma de dados para identificar dados alterados. As políticas suportadas variam de acordo com o tipo de fonte de dados.

Atributo Descrição
dataChangeDetectionPolicy Opcional. As políticas válidas incluem HighWatermarkChangeDetectionPolicy ou SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy 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 marca d'água), e a alteração no valor é maior.

SqlIntegratedChangeDetectionPolicy é usado para fazer referência aos recursos nativos de deteção de alterações no SQL Server. Esta política só pode ser usada com tabelas; ele não pode ser usado com visualizações. Tem de ativar o controlo de alterações para a tabela que está a utilizar antes de poder utilizar esta política. Consulte Ativar e desativar de controlo de alterações para obter instruções.
highWaterMarkColumnName Necessário para HighWatermarkChangeDetectionPolicy. Para o Cosmos DB, a coluna deve ser _ts propriedade. Para o Azure SQL, recomenda-se uma coluna rowversion indexada. Para o Armazenamento do Azure, a deteção de alterações é interna usando valores lastModified, eliminando qualquer necessidade de definir o dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Especifica o mecanismo fornecido pela plataforma de dados para identificar dados excluídos. As políticas suportadas variam de acordo com o tipo de fonte de dados.

Atributo Descrição
dataDeletionDetectionPolicy Opcional. Os valores válidos são SoftDeleteColumnDeletionDetectionPolicy ou NativeBlobSoftDeleteDeletionDetectionPolicy (consulte Native blob soft delete (preview)).

Atualmente, a única política geralmente disponível é aSoftDeleteColumnDeletionDetectionPolicy, que identifica itens excluídos com base no valor de uma coluna ou propriedade de 'exclusão suave' na fonte de dados.

softDeleteColumnName" Necessário. Nome de uma coluna na fonte de dados fornecendo um valor que especifica o status de exclusão de uma linha. Por exemplo, você pode criar uma coluna chamada "IsDeleted". Somente colunas com valores de cadeia de caracteres, inteiros ou booleanos são suportadas.
softDeleteMarkerValue Necessário. O valor da coluna soft delete. O valor usado como softDeleteMarkerValue deve ser uma cadeia de caracteres, mesmo que a coluna correspondente contenha inteiros ou booleanos. Por exemplo, se o valor que aparece na fonte de dados for 1, use "1" como o softDeleteMarkerValue. Se o indexador ler esse valor da coluna de exclusão flexível, ele excluirá o documento de pesquisa correspondente do índice de pesquisa.

encryptionKey [en]

Configura uma conexão com o Cofre de Chaves do Azure para chaves de criptografia (CMK) suplementares gerenciadas pelo cliente. A criptografia com chaves gerenciadas pelo cliente não está disponível para serviços gratuitos. Para serviços faturáveis, só está disponível para serviços de pesquisa criados em ou após 2019-01-01.

Uma conexão com o cofre de chaves deve ser autenticada. Você pode usar "accessCredentials" ou uma identidade gerenciada para essa finalidade.

As identidades gerenciadas podem ser atribuídas pelo sistema ou pelo usuário (visualização). Se o serviço de pesquisa tiver uma identidade gerenciada atribuída pelo sistema e uma atribuição de função que conceda acesso de leitura ao cofre de chaves, você poderá omitir "identity" e "accessCredentials", e a solicitação será autenticada usando a identidade gerenciada. Se o serviço de pesquisa tiver identidade atribuída pelo usuário e atribuição de função, defina a propriedade "identity" como a ID de recurso dessa identidade.

Atributo Descrição
keyVaultKeyName Necessário. Nome da chave do Cofre da Chave do Azure usada para criptografia.
keyVaultKeyVersion Necessário. Versão da chave do Cofre da Chave do Azure.
keyVaultUri Necessário. URI do Cofre da Chave do Azure (também conhecido como nome DNS) que fornece a chave. Um exemplo de URI pode ser https://my-keyvault-name.vault.azure.net.
accessCredenciais Omitir se estiver a utilizar uma identidade gerida. Caso contrário, as propriedades do accessCredentials incluem applicationId (uma ID de Aplicativo do Azure Ative Directory que tem permissões de acesso ao seu Cofre de Chaves do Azure especificado) e applicationSecret (a chave de autenticação do aplicativo do Azure AD especificado).
identidade Opcional, a menos que você esteja usando uma identidade gerenciada atribuída pelo usuário para a conexão do serviço de pesquisa com o Cofre da Chave do Azure. O formato é "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Ver também