Criar ou Atualizar Origem de Dados (API REST de Pré-visualização)

  • Artigo

Aplica-se a: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Importante

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

04-2021-04-30-Preview adiciona suporte de identidade gerida para ligações de indexador a outros recursos do Azure:

  • As "credenciais" aceitam um ID de recurso do Azure como um valor, desde que o serviço de pesquisa seja executado numa identidade gerida e as atribuições de funções do Azure concedam acesso de leitura aos dados.
  • A "identidade" aceita uma identidade gerida atribuída pelo utilizador. Esta propriedade é de primeiro nível para ligações de dados. Também está em "encryptionKey" para obter uma chave gerida pelo cliente no Azure Key Vault.
  • Ficheiros do Azure suporte está em pré-visualização. Utilize uma API de pré-visualização para indexar a partir desta origem de dados.

2020-06-30-Preview adiciona:

  • "dataDeletionDetectionPolicy" aceita "NativeBlobSoftDeleteDeletionDetectionPolicy" para indexadores de blobs.
  • Base de Dados do Azure para MySQL suporte está em pré-visualização. Utilize uma API de pré-visualização para indexar a partir desta origem de dados.
  • O suporte da API do MongoDB e da API do Gremlin do Cosmos DB está em pré-visualização. Utilize uma API de pré-visualização para indexar a partir desta origem de dados.

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 suportadas.

Pode utilizar POST ou PUT num pedido de criação. Para qualquer um deles, o 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]

Para pedidos de atualização, utilize 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]

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

Nota

Depois de existir uma origem de dados, não pode alterar a propriedade do tipo num pedido de atualização. Em vez disso, deve criar uma nova origem de dados com o tipo que pretende.

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 de pré-visualização atual é 2023-07-01-Preview. 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" : (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)"}
      }
}

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:

adlsgen2 para Azure Data Lake Storage Gen2
azureblob para Armazenamento de Blobs do Azure
azurefiles para o Armazenamento
azuresql de Ficheiros do Azure para a Base
azuretable de Dados SQL do Azure para o Armazenamento de Tabelas do Azure
cosmosdb para a API SQL do Azure Cosmos DB, a API do MongoDB e a API
mysql do Gremlin para Base de Dados do Azure para MySQL
credenciais Obrigatório. Contém uma connectionString propriedade que especifica como ligar.
contentor Obrigatório. Especifica o contentor, coleção, tabela ou vista que contém os dados a indexar.
dataChangeDetectionPolicy Opcional. Especifica o mecanismo fornecido pela plataforma de dados para identificar itens de dados alterados.
dataDeletionDetectionPolicy Opcional. Identifica como a plataforma de dados elimina dados.
encryptionKey Opcional. Utilizado para encriptação adicional de credenciais de origem de dados, através de chaves de encriptação geridas pelo cliente (CMK) no Azure Key Vault. Disponível para serviços de pesquisa faturáveis criados em ou depois de 2019-01-01.
desativado Opcional. Valor booleano que indica se o indexador é criado num estado desativado, o que o impede de ser executado imediatamente. Falso por predefinição.
identidade Opcional. Contém um userAssignedIdentity tipo #Microsoft.Azure.Search.DataUserAssignedIdentity e especifica a identidade gerida atribuída pelo utilizador do recurso externo. Esta propriedade depende de credentials ter o cadeia de ligação no formato certo (um ID de Recurso) para ligações de identidade gerida para cada tipo de origem de dados.

Se a identity propriedade for nula, a ligação a um ID de recurso é efetuada com a propriedade gerida pelo sistema.

Se esta propriedade estiver atribuída ao tipo #Microsoft.Azure.Search.DataNoneIdentity, qualquer identidade explícita especificada anteriormente será desmarcada.

Resposta

Para um pedido com êxito: 201 Criado se tiver sido criada uma nova origem de dados e 204 Sem Conteúdo se uma origem de dados existente tiver sido atualizada.

Exemplos

Exemplo: funções do Azure e uma identidade gerida atribuída pelo sistema

Se o seu serviço de pesquisa tiver uma identidade gerida atribuída pelo sistema e uma atribuição de função, a ligação de origem de dados pode 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 gerida atribuída pelo utilizador (pré-visualização)

Este exemplo demonstra uma ligação autenticada Azure AD para um serviço de pesquisa com uma identidade gerida atribuída pelo utilizador.

{
    "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 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: utilizar a opção de credencial não inalterada ou redigida

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 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: Ligações do cofre de chaves de encriptação por serviços de pesquisa com uma identidade gerida atribuída pelo utilizador

Este exemplo omite accessCredentials. Para um recurso com uma identidade gerida atribuída pelo utilizador , pode especificar a identidade em encryptionKey e obter a chave com essa identidade e atribuições de funções 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 Description
contentor Especifica o contentor, coleção, tabela ou vista que contém os dados a indexar.
credenciais Contém uma connectionString propriedade que especifica como um indexador se liga 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 eliminados.
encryptionKey Configura uma ligação ao Azure Key Vault para encriptação gerida pelo cliente.

contentor

Especifica o contentor, coleção, tabela ou vista que contém os dados a indexar.

Atributo Descrição
name Obrigatório. Para o Azure Cosmos DB, especifica a coleção de API SQL. Para Armazenamento de Blobs do Azure, especifica o contentor de armazenamento. Para SQL do Azure, especifica a tabela ou vista. Pode utilizar nomes qualificados para esquemas, como [dbo].[mytable]. Para o Armazenamento de Tabelas do Azure, especifica o nome da tabela.
query Opcional. 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.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 vez disso, utilize vistas).

credenciais

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

Atributo Descrição
connectionString Obrigatório. Especifica uma ligação a uma origem de dados do indexador. Se estiver a atualizar a definição da 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.

Para ligações que são autenticadas através de chaves ou credenciais de início de sessão, esses valores são visíveis no cadeia de ligação. 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çãoADO.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.

Se estiver a utilizar uma identidade gerida para autenticar, pode omitir credenciais na ligação.

Para ligações autenticadas com uma identidade gerida, o cadeia de ligação especifica o ID de recurso do Azure (veja estas ligações para cadeia de ligação formato: Armazenamento do Azure, Cosmos DB, Base de Dados SQL).

As atribuições de funções no âmbito da origem de dados externa determinam se o indexador se consegue ligar e o serviço de pesquisa tem de ser configurado para ser executado como um serviço fidedigno no Azure Active Directory.

Se a propriedade "identity" também for especificada, a ligação é efetuada com a identidade gerida atribuída pelo utilizador pelo serviço de pesquisa fornecida pela propriedade "identity". Caso contrário, se "identidade" não for especificada ou nula, a ligação será através da identidade gerida pelo sistema.

dataChangeDetectionPolicy

Especifica o mecanismo fornecido pela plataforma de dados para identificar dados alterados. As políticas suportadas variam consoante o tipo de origem 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 numa atualização para a coluna de marca d'água) e a alteração no valor é superior.

SqlIntegratedChangeDetectionPolicyé utilizado 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.
highWaterMarkColumnName Necessário para HighWatermarkChangeDetectionPolicy. Para o Cosmos DB, a coluna tem de ser _ts propriedade. Para SQL do Azure, é recomendada uma coluna indexadarowversion. Para o Armazenamento do Azure, a deteção de alterações é incorporada com valores lastModified, eliminando qualquer necessidade de definir os dadosChangeDetectionPolicy.

dataDeletionDetectionPolicy

Especifica o mecanismo fornecido pela plataforma de dados para identificar dados eliminados. As políticas suportadas variam consoante o tipo de origem de dados.

Atributo Descrição
dataDeletionDetectionPolicy Opcional. Os valores válidos são SoftDeleteColumnDeletionDetectionPolicy ou NativeBlobSoftDeleteDeletionDetectionPolicy (veja Eliminação recuperável de blobs nativos (pré-visualização)).

Atualmente, a única política disponível geralmente éSoftDeleteColumnDeletionDetectionPolicy, que identifica itens eliminados com base no valor de uma coluna ou propriedade de "eliminação recuperável" na origem de dados.

softDeleteColumnName" Obrigatório. Nome de uma coluna na origem de dados que fornece um valor que especifica o estado de eliminação de uma linha. Por exemplo, pode criar uma coluna com o nome "IsDeleted". Só são suportadas colunas com valores de cadeia, número inteiro ou booleano.
softDeleteMarkerValue Obrigatório. O valor da coluna de eliminação recuperável. 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 Se o indexador ler este valor da coluna de eliminação recuperável, elimina o documento de pesquisa correspondente do índice de pesquisa.

encryptionKey

Configura uma ligação ao Azure Key Vault para chaves de encriptação geridas pelo cliente (CMK) suplementares. A encriptação com chaves geridas 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 depois de 2019-01-01.

Uma ligação ao cofre de chaves tem de ser autenticada. Pode utilizar "accessCredentials" ou uma identidade gerida para esta finalidade.

As identidades geridas podem ser atribuídas pelo sistema ou pelo utilizador (pré-visualização). Se o serviço de pesquisa tiver uma identidade gerida atribuída pelo sistema e uma atribuição de função que conceda acesso de leitura ao cofre de chaves, pode omitir "identidade" e "accessCredentials" e o pedido será autenticado com a identidade gerida. Se o serviço de pesquisa tiver a atribuição de identidade e função atribuída pelo utilizador, defina a propriedade "identidade" para o ID de recurso dessa identidade.

Atributo Descrição
keyVaultKeyName Obrigatório. Nome da chave de Key Vault do Azure utilizada para encriptação.
keyVaultKeyVersion Obrigatório. Versão da chave de Key Vault do Azure.
keyVaultUri Obrigatório. URI do Azure Key Vault (também conhecido como nome DNS) que fornece a chave. Um URI de exemplo pode ser https://my-keyvault-name.vault.azure.net.
accessCredentials Omitir se estiver a utilizar uma identidade gerida. Caso contrário, as propriedades de incluir applicationId (um ID de accessCredentials Aplicação do Azure Active Directory que tenha permissões de acesso ao Azure Key Vault especificado) e applicationSecret (a chave de autenticação da aplicação Azure AD especificada).
identidade Opcional, a menos que esteja a utilizar uma identidade gerida atribuída pelo utilizador para a ligação do serviço de pesquisa ao Azure Key Vault. O formato é "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Ver também