.ingestão em

Aplica-se a: ✅Microsoft Fabric✅ do Azure Data Explorer

O comando .ingest into ingere dados em uma tabela "extraindo" os dados de um ou mais arquivos de armazenamento em nuvem. Por exemplo, o comando pode recuperar 1.000 blobs formatados em CSV do Armazenamento de Blobs do Azure, analisá-los e ingeri-los juntos em uma única tabela de destino. Os dados são acrescentados à tabela sem afetar os registros existentes e sem modificar o esquema da tabela.

Nota

Esse método de ingestão destina-se à exploração e à criação de protótipos. Não o use em cenários de produção ou de alto volume.

Permissões

Você deve ter pelo menos permissões de ingestor de tabela para executar esse comando.

Sintaxe

.ingest [async] intotableSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Saiba mais sobre convenções de sintaxe.

Parâmetros

Nome	Tipo	Necessário	Descrição
async	string		Se especificado, o comando retorna imediatamente e continua a ingestão em segundo plano. Os resultados do comando incluem um valor OperationId que pode ser usado com o comando .show operation para recuperar o status de conclusão da ingestão e os resultados.
TableName	string	✔️	O nome da tabela na qual ingerir dados. O nome da tabela é sempre relativo ao banco de dados no contexto. Se nenhum objeto de mapeamento de esquema for fornecido, o esquema do banco de dados no contexto será usado.
SourceDataLocator	string	✔️	Uma lista separada por vírgulas ou única de cadeias de conexão de armazenamento . Uma única cadeia de conexão deve se referir a um único arquivo hospedado por uma conta de armazenamento. A ingestão de vários arquivos pode ser feita especificando várias cadeias de conexão ou ingestão de uma de consulta de uma tabela externa .

Nota

É recomendável usar literais de cadeia de caracteres ofuscados para o SourceDataLocators. O serviço limpará as credenciais em rastreamentos internos e mensagens de erro.

Propriedades de ingestão

Importante

Na ingestão na fila, dados são agrupados em lote usando as propriedades de ingestão. Quanto mais propriedades de mapeamento de ingestão distintas usadas, como valores constvalue diferentes, mais fragmentada a ingestão se torna, o que pode levar à degradação do desempenho.

A tabela a seguir lista e descreve as propriedades com suporte e fornece exemplos:

Propriedade	Descrição	Exemplo
ingestionMapping	Um valor de cadeia de caracteres que indica como mapear dados do arquivo de origem para as colunas reais na tabela. Defina o valor format com o tipo de mapeamento relevante. Consulte mapeamentos de dados.	with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]") (preterido: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference	Um valor de cadeia de caracteres que indica como mapear dados do arquivo de origem para as colunas reais na tabela usando um objeto de política de mapeamento nomeado. Defina o valor format com o tipo de mapeamento relevante. Consulte mapeamentos de dados.	with (format="csv", ingestionMappingReference = "Mapping1") (preterido: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime	O valor datetime (formatado como uma cadeia de caracteres ISO8601) a ser usado no momento da criação das extensões de dados ingeridas. Se não for especificado, o valor atual (now()) será usado. Substituir o padrão é útil ao ingerir dados mais antigos, de modo que a política de retenção seja aplicada corretamente. Quando especificado, verifique se a propriedade Lookback na política de mesclagem de extents efetiva da tabela de destino está alinhada com o valor especificado.	with (creationTime="2017-02-13")
extend_schema	Um valor booliano que, se especificado, instrui o comando a estender o esquema da tabela (o padrão é false). Essa opção se aplica somente aos comandos .append e .set-or-append. As únicas extensões de esquema permitidas têm mais colunas adicionadas à tabela no final.	Se o esquema de tabela original for (a:string, b:int), uma extensão de esquema válida será (a:string, b:int, c:datetime, d:string), mas (a:string, c:datetime) não seria válida
folder	Para comandos de ingestão de consulta, a pasta a ser atribuída à tabela. Se a tabela já existir, essa propriedade substituirá a pasta da tabela.	with (folder="Tables/Temporary")
format	O formato de dados (consulte formatos de dados com suporte).	with (format="csv")
ingestIfNotExists	Um valor de cadeia de caracteres que, se especificado, impede que a ingestão seja bem-sucedida se a tabela já tiver dados marcados com uma marca ingest-by: com o mesmo valor. Isso garante a ingestão de dados idempotente. Para obter mais informações, consulte ingestão por: marcas.	As propriedades with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indicam que, se os dados com a marca ingest-by:Part0001 já existirem, não conclua a ingestão atual. Se ainda não existir, essa nova ingestão deverá ter esse conjunto de marcas (caso uma ingestão futura tente ingerir os mesmos dados novamente).)
ignoreFirstRecord	Um valor booliano que, se definido como true, indica que a ingestão deve ignorar o primeiro registro de cada arquivo. Essa propriedade será útil para arquivos em CSVe formatos semelhantes, se o primeiro registro no arquivo for os nomes de coluna. Por padrão, false é assumido.	with (ignoreFirstRecord=false)
policy_ingestiontime	Um valor booliano que, se especificado, descreve se a Política de Tempo de Ingestão em uma tabela criada por esse comando. O padrão é true.	with (policy_ingestiontime=false)
recreate_schema	Um valor booliano que, se especificado, descreve se o comando pode recriar o esquema da tabela. Essa propriedade se aplica somente ao comando .set-or-replace. Essa propriedade terá precedência sobre a propriedade extend_schema se ambas estiverem definidas.	with (recreate_schema=true)
tags	Uma lista de marcas para associar aos dados ingeridos, formatados como uma cadeia de caracteres JSON	with (tags="['Tag1', 'Tag2']")
TreatGzAsUncompressed	Um valor booliano que, se definido como true, indica que os arquivos com a extensão .gz não são compactados. Às vezes, esse sinalizador é necessário ao ingerir do Amazon AWS S3.	with (treatGzAsUncompressed=true)
validationPolicy	Uma cadeia de caracteres JSON que indica quais validações serão executadas durante a ingestão de dados representados usando o formato CSV. Consulte de ingestão de dados para obter uma explicação das diferentes opções.	with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (essa é a política padrão)
zipPattern	Use essa propriedade ao ingerir dados do armazenamento que têm um arquivo ZIP. Esse é um valor de cadeia de caracteres que indica a expressão regular a ser usada ao selecionar quais arquivos no arquivo ZIP serão ingeridos. Todos os outros arquivos no arquivo são ignorados.	with (zipPattern="*.csv")

Autenticação e autorização

Cada cadeia de conexão de armazenamento indica o método de autorização a ser usado para acesso ao armazenamento. Dependendo do método de autorização, a entidade de segurança pode precisar receber permissões no armazenamento externo para executar a ingestão.

A tabela a seguir lista os métodos de autenticação com suporte e as permissões necessárias para ingerir dados do armazenamento externo.

Método de autenticação	Armazenamento de Blobs do Azure/Data Lake Storage Gen2	Data Lake Storage Gen1
de representação	Leitor de Dados do Blob de Armazenamento	Leitor
token SAS (Acesso Compartilhado)	Lista + Leitura	Não há suporte para esse método de autenticação no Gen1.
de token de acesso do Microsoft Entra
chave de acesso da conta de armazenamento		Não há suporte para esse método de autenticação no Gen1.
de identidade gerenciada	Leitor de Dados do Blob de Armazenamento	Leitor

Retorna

O resultado do comando é uma tabela com tantos registros quanto fragmentos de dados ("extensões") gerados pelo comando. Se nenhum fragmento de dados tiver sido gerado, um único registro será retornado com uma ID de extensão vazia (com valor zero).

Nome	Tipo	Descrição
ExtentId	guid	O identificador exclusivo do fragmento de dados que foi gerado pelo comando.
ItemLoaded	string	Um ou mais arquivos de armazenamento relacionados a esse registro.
Duração	timespan	Quanto tempo levou para executar a ingestão.
HasErrors	bool	Se esse registro representa ou não uma falha de ingestão.
OperationId	guid	Uma ID exclusiva que representa a operação. Pode ser usado com o comando .show operation.

Nota

Esse comando não modifica o esquema da tabela que está sendo ingerida. Se necessário, os dados são "coagidos" para esse esquema durante a ingestão, não o contrário (colunas extras são ignoradas e colunas ausentes são tratadas como valores nulos).

Exemplos

Armazenamento de Blobs do Azure com assinatura de acesso compartilhado

O exemplo a seguir instrui seu banco de dados a ler dois blobs do Armazenamento de Blobs do Azure como arquivos CSV e ingerir seu conteúdo em Tde tabela. O ... representa uma SAS (assinatura de acesso compartilhado) do Armazenamento do Azure que fornece acesso de leitura a cada blob. Cadeias de caracteres ofuscadas (a h na frente dos valores da cadeia de caracteres) são usadas para garantir que a SAS nunca seja registrada.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Armazenamento de Blobs do Azure com identidade gerenciada

O exemplo a seguir mostra como ler um arquivo CSV do Armazenamento de Blobs do Azure e ingerir seu conteúdo na tabela T usando a autenticação de identidade gerenciada. A autenticação usa a ID de identidade gerenciada (ID do objeto) atribuída ao Armazenamento de Blobs do Azure no Azure. Para obter mais informações, consulte Criar uma identidade gerenciada para contêineres de armazenamento.

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen2

O exemplo a seguir é para ingerir dados do Azure Data Lake Storage Gen 2 (ADLSv2). As credenciais usadas aqui (...) são as credenciais da conta de armazenamento (chave compartilhada) e usamos ofuscação de cadeia de caracteres apenas para a parte secreta da cadeia de conexão.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Armazenamento do Azure Data Lake

O exemplo a seguir ingere um único arquivo do ADLS (Azure Data Lake Storage). Ele usa as credenciais do usuário para acessar o ADLS (portanto, não é necessário tratar o URI de armazenamento como contendo um segredo). Ele também mostra como especificar propriedades de ingestão.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 com uma chave de acesso

O exemplo a seguir ingere um único arquivo do Amazon S3 usando uma ID da chave de acesso e uma chave de acesso secreta.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=EXAMPLEKEY')
  with (format='csv')

Amazon S3 com uma URL pré-atribuída

O exemplo a seguir ingere um único arquivo do Amazon S3 usando umde URL pré-atribuído .

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')

Conteúdo relacionado

• formatos de dados com suporte para de ingestão
• .ingestão embutida
• Ingestão da consulta (.set, .append, .set-or-append, .set-or-replace)
• comando .show de falhas de ingestão
• .show de mapeamento de ingestão