Criar ou atualizar fonte de dados (API REST de versão prévia)

aplica-se a: 2023-07-01-Preview. Não há mais suporte para essa versão. Atualizar imediatamente para uma versão mais recente.

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

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]    

O 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á substituído usando a nova definição.

Parâmetros de URI

Cabeçalhos de solicitação

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

Corpo da Solicitação

O corpo da solicitação contém uma definição de fonte de dados, que inclui o tipo da fonte de dados, credenciais para ler os dados, bem como uma detecção de alteração de dados opcional e políticas de detecção de exclusão de dados que são usadas para identificar dados alterados ou excluídos com eficiência 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)"}
      }
} 

A solicitação contém as seguintes propriedades:

Resposta

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

Exemplos

exemplo: funções do Azure e uma identidade gerenciada atribuída pelo 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 a ID de recurso exclusiva 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 (versão prévia)

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 detecção de alterações (Política de Detecção de Alterações de Marca D'água)

{   
    "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 de 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 com propriedades necessárias apenas

As 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: usando a opção de credencial inalterada ou redigida

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

Chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia adicional. Para obter mais informações, consulte Encryption 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 chaves 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 uma identidade gerenciada atribuída pelo usuário atribuída 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

recipiente

Especifica o contêiner, a coleção, a tabela ou a 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.

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 de cadeia de conexão: de Armazenamento do Azure, do Cosmos DB,banco 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 Active 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 "identidade" não for especificada ou nula, a conexão será por meio da identidade gerenciada pelo sistema.

dataChangeDetectionPolicy

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

dataDeletionDetectionPolicy

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

encryptionKey

Configura uma conexão com o Azure Key Vault para cmk (chaves de criptografia gerenciadas pelo cliente) complementares. A criptografia com chaves gerenciadas pelo cliente não está disponível para serviços gratuitos. Para serviços faturáveis, ele 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 (versão prévia). 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 "identidade" e "accessCredentials", e a solicitação será autenticada usando a identidade gerenciada. Se o serviço de pesquisa tiver atribuição de função e identidade atribuída pelo usuário, defina a propriedade "identity" como a ID do recurso dessa identidade.

Consulte também

• Visão geral dos Indexadores
• Criando indexadores
• de criptografia gerenciada pelo cliente