Ingestão de armazenamento
O comando .ingest into
ingere dados em uma tabela "efetuando pull" de dados de um ou mais arquivos de armazenamento em nuvem.
Por exemplo, o comando pode recuperar 1.000 blobs no formato CSV do Armazenamento de Blobs do Azure, depois analisar e ingerir todos eles em conjunto em uma tabela de destino única.
Os dados são acrescentados à tabela sem afetar as linhas existentes nem alterar o esquema da tabela.
Observação
Esse método de ingestão destina-se à exploração e à prototipagem. 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 este comando.
Syntax
.ingest
[async
] into
table
TableNameSourceDataLocator [with
(
IngestionPropertyName=
IngestionPropertyValue [,
...] )
]
Saiba mais sobre as convenções de sintaxe.
Parâmetros
Nome | Tipo | Obrigató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 OperationId valor que pode ser usado com o .show operation comando para recuperar a 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 única ou separada por vírgulas de cadeias de conexão de armazenamento. Uma cadeia de conexão única deverá fazer referência a um arquivo único hospedado por uma conta de armazenamento. A ingestão de vários arquivos pode ser feita especificando várias cadeias de conexão ou ingerindo de uma consulta de uma tabela externa. |
Observação
É recomendável usar literais de cadeia de caracteres ofuscados para o SourceDataPointer. O serviço limpará as credenciais em rastreamentos internos e mensagens de erro.
Propriedades da ingestão
Importante
- Em dados de ingestão enfileirados são agrupados usando as propriedades ingestão. As propriedades de mapeamento de ingestão mais 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 as propriedades com suporte pelo Azure Data Explorer, descreve-as 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. Confira os 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. Confira os mapeamentos de dados. |
with (format="csv", ingestionMappingReference = "Mapping1") (preterido: avroMappingReference , csvMappingReference , jsonMappingReference ) |
creationTime |
O valor de datetime (formatado como uma cadeia de caracteres ISO8601) a ser usado na hora de criação das extensões dos dados ingeridos. Se não for especificado, o valor atual (now() ) será usado. Substituir o padrão é útil ao ingerir dados mais antigos, para que a política de retenção seja aplicada corretamente. Quando especificado, verifique se a propriedade Lookback na Política de mesclagem de extensões efetivas da tabela de destino está alinhada com o valor especificado. |
with (creationTime="2017-02-13") |
extend_schema |
Um valor booliano que, se especificado, instruirá 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 colunas adicionais inseridas no final da tabela. |
Se o esquema da tabela original fosse (a:string, b:int) , uma extensão de esquema válida seria (a:string, b:int, c:datetime, d:string) , mas (a:string, c:datetime) não seria válido |
folder |
Para comandos ingest-from-query, 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 dos dados (confira os formatos de dados suportados). | with (format="csv") |
ingestIfNotExists |
um valor de cadeia de caracteres que, se especificado, impede que a ingestão tenha sucesso se a tabela já tiver dados marcados com uma marcação ingest-by: com o mesmo valor. Isso garante uma ingestão de dados idempotente. Para obter mais informações, veja ingest-by: tags. |
As propriedades with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indicam que se os dados com a marcação ingest-by:Part0001 já existirem, você não deverá concluir a ingestão atual. Se eles não existirem ainda, essa nova ingestão deverá ter esse conjunto de marcações (no caso de tentativas de ingestão futuras dos mesmos dados novamente.) |
ignoreFirstRecord |
Um valor booliano que, se definido como true , indicará que a ingestão deve ignorar o primeiro registro de cada arquivo. Essa propriedade é útil para arquivos em CSV e formatos semelhantes caso o primeiro registro no arquivo for o nome da 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 deve ser habilitada em uma tabela criada por esse comando. O padrão é true . |
with (policy_ingestiontime=false) |
recreate_schema |
Um valor booliano que, se especificado, descreverá se o comando pode recriar o esquema da tabela. Esta propriedade só se aplica ao comando .set-or-replace . Essa propriedade tem precedência sobre a propriedade extend_schema se ambas estiverem definidas. |
with (recreate_schema=true) |
tags |
Uma lista de marcações a serem associadas aos dados ingeridos, formatados como uma cadeia de caracteres JSON | with (tags="['Tag1', 'Tag2']") |
validationPolicy |
Uma cadeia de caracteres JSON que indica quais validações executar durante a ingestão de dados representados usando o formato CSV. Consulte Ingestão de dados para obter uma explicação das diferentes opções. | with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (essa é, na verdade, a política padrão) |
zipPattern |
Use essa propriedade ao ingerir dados do armazenamento que tenha 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 serã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 |
---|---|---|
Representação | Leitor de Dados do Blob de Armazenamento | Leitor |
Token SAS (Acesso Compartilhado) | Listar + Ler | Não há suporte para esse método de autenticação no Gen1. |
token de acesso Microsoft Entra | ||
Chave de acesso da conta de armazenamento | Não há suporte para esse método de autenticação no Gen1. | |
Identidade gerenciada | Leitor de Dados do Blob de Armazenamento | Leitor |
Retornos
O resultado do comando será uma tabela com o mesmo número de linhas e fragmentos de dados ("extensões") gerados pelo comando. Caso os fragmentos de dados não sejam gerados, uma linha única será retornada com uma ID de extensão vazia (valor zero).
Nome | Tipo | Descrição |
---|---|---|
ExtentId | guid |
O identificador exclusivo do fragmento de dados gerado pelo comando. |
ItemLoaded | string |
Um ou mais arquivos de armazenamento relacionados a essa linha. |
Duração | timespan |
O tempo gasto para executar a ingestão. |
HasErrors | bool |
Indica se esta linha representa ou não uma falha de ingestão. |
OperationId | guid |
Uma ID exclusiva representando a operação. É possível usá-la com o comando .show operation . |
Observação
Esse comando não modifica o esquema da tabela que está sendo ingerida. Caso seja necessário, os dados são "impostos" nesse esquema durante a ingestão, não o contrário (as colunas adicionais são ignoradas e as colunas ausentes são tratadas como valores nulos).
Exemplos
Armazenamento de Blobs do Azure com assinatura de acesso compartilhado
O exemplo a seguir instrui o cluster a ler dois blobs de Armazenamento de Blobs do Azure como arquivos CSV e ingerir seu conteúdo na tabela T
. Os ...
representam uma SAS (Assinatura de Acesso Compartilhado) do Armazenamento do Azure que fornece acesso de leitura a cada blob. Observe também o uso de cadeias de caracteres ocultas (o h
na frente dos valores da cadeia de caracteres) 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 de Armazenamento de Blobs do Azure e ingerir seu conteúdo na tabela T
usando a autenticação de identidade gerenciada. Para obter informações adicionais sobre o método de autenticação de identidade gerenciada, consulte Visão geral da autenticação de identidade gerenciada.
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
O exemplo a seguir é para ingerir dados de Azure Data Lake Storage Gen 2 (ADLSv2). As credenciais usadas aqui (...
) são credenciais da conta de armazenamento (chave compartilhada). Além disso, usamos a ofuscação de cadeia de caracteres somente na 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 de Azure Data Lake Storage (ADLS). Ele vai usar as credenciais do usuário para acessar o ADLS. Portanto, não é preciso considerar que o URI contém um segredo. Ele também vai mostrar de que modo especificar as 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 de 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=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
Amazon S3 com uma URL pré-atribuída
O exemplo a seguir ingere um único arquivo do Amazon S3 usando uma URL pré-atribuída.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de