Ingerir a partir do armazenamento
Aplica-se a: ✅Microsoft Fabric✅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.
Observação
Este 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.
Observação
Este 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. Para obter mais informações sobre as opções de ingestão, consulte Visão geral da ingestão de dados.
Permissões
Você deve ter pelo menos Ingestor de Tabela permissões para executar esse comando.
Sintaxe
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Saiba mais sobre convenções de sintaxe.
Parâmetros
| Designação | 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 de OperationId que pode ser usado com o comando .show operation para recuperar o status e os resultados de conclusão da ingestão. |
|
| TableName | string |
✔️ | O nome da tabela na qual os dados serão ingeridos. 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 ú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 a partir de uma consulta de uma tabela externa . |
Observação
Recomendamos o uso de literais de cadeia de caracteres ofuscados para o SourceDataLocators. O serviço irá limpar credenciais em rastreamentos internos e mensagens de erro.
Propriedades de ingestão
Importante
Na ingestão em fila, dados são agrupados em lote usando as propriedades de ingestão. Quanto mais distintas forem as propriedades de mapeamento de ingestão usadas, como diferentes valores de ConstValue, mais fragmentada a ingestão se torna, o que pode levar à degradação do desempenho.
A tabela a seguir lista e descreve as propriedades suportadas 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()) é 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 |
with (creationTime="2017-02-13") |
extend_schema |
Um valor booleano que, se especificado, instrui o comando a estender o esquema da tabela (o padrão é false). Esta opção aplica-se apenas 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 será válida |
folder |
Para comandos de 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 de dados (consulte formatos de dados suportados). | 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 idempotente de dados. Para obter mais informações, consulte ingest-by: tags. |
As propriedades with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indicam que, se os dados com a tag ingest-by:Part0001 já existirem, não concluam a ingestão atual. Se ainda não existir, esta nova ingestão deve ter esta etiqueta definida (no caso de uma ingestão futura tentar ingerir os mesmos dados novamente). |
ignoreFirstRecord |
Um valor booleano que, se definido como true, indica que a ingestão deve ignorar o primeiro registro de cada arquivo. Esta propriedade é útil para arquivos em CSVe formatos semelhantes, se o primeiro registro no arquivo são os nomes das colunas. Por padrão, false é assumido. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Um valor booleano que, se especificado, descreve se a Diretiva de Tempo de Ingestão de deve ser habilitada em uma tabela criada por esse comando. O padrão é true. |
with (policy_ingestiontime=false) |
recreate_schema |
Um valor booleano que, se especificado, descreve se o comando pode recriar o esquema da tabela. Esta propriedade aplica-se apenas ao comando .set-or-replace. Esta propriedade tem precedência sobre a propriedade extend_schema se ambas estiverem definidas. |
with (recreate_schema=true) |
tags |
Uma lista de tags associar aos dados ingeridos, formatados como uma cadeia de caracteres JSON | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Um valor booleano 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 ser ingerido a partir do Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Uma cadeia de caracteres JSON que indica quais validações devem ser 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}') (esta é a política padrão) |
zipPattern |
Use essa propriedade ao ingerir dados do armazenamento que tenha um arquivo ZIP. Este é um valor de cadeia de caracteres que indica a expressão regular a ser usada ao selecionar quais arquivos no arquivo ZIP devem ser 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 acessar o 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 suportados e as permissões necessárias para ingerir dados do armazenamento externo.
| Método de autenticação | Azure Blob Storage / Data Lake Storage Gen2 | Armazenamento Data Lake Gen1 |
|---|---|---|
| de falsificação de identidade | Leitor de dados de Blob de armazenamento | Leitor |
| de token de Acesso Compartilhado (SAS) | Lista + Ler | Este método de autenticação não é suportado no Gen1. |
| de token de acesso do Microsoft Entra | ||
| Chave de acesso da conta de armazenamento | Este método de autenticação não é suportado no Gen1. | |
| Identidade gerenciada | Leitor de dados de Blob de armazenamento | Leitor |
Devoluções
O resultado do comando é uma tabela com tantos registros quantos forem fragmentos de dados ("extents") gerados pelo comando. Se nenhum fragmento de dados tiver sido gerado, um único registro será retornado com um ID de extensão vazio (valor zero).
| Designação | Tipo | Descrição |
|---|---|---|
| ExtentId | guid |
O identificador exclusivo para o fragmento de dados que foi gerado pelo comando. |
| ItemLoaded | string |
Um ou mais ficheiros de armazenamento relacionados com este registo. |
| Duração | timespan |
Quanto tempo demorou a realizar a ingestão. |
| HasErrors | bool |
Se este registo representa ou não uma falha de ingestão. |
| OperationId | guid |
Um ID exclusivo que representa a operação. Pode ser usado com o comando .show operation. |
Observação
Este comando não modifica o esquema da tabela que está sendo ingerida. Se necessário, os dados são "coagidos" a este esquema durante a ingestão, e 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 na tabela T. O ... representa uma assinatura de acesso compartilhado (SAS) do Armazenamento do Azure que dá acesso de leitura a cada blob. Strings ofuscadas (o h na frente dos valores de string) são usadas para garantir que o SAS nunca seja gravado.
.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 em T de tabela usando a autenticação de identidade gerenciada. A autenticação usa a ID de identidade gerenciada (ID do objeto) atribuída ao Armazenamento de Blob 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 Gen 2
O exemplo a seguir é para a ingestão de 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 Azure Data Lake
O exemplo a seguir ingere um único arquivo do Azure Data Lake Storage (ADLS). Ele usa as credenciais do usuário para acessar o ADLS (portanto, não há necessidade de tratar o URI de armazenamento como contendo um segredo). Também mostra como 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 um 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 um URL pré-assinado
O exemplo a seguir ingere um único arquivo do Amazon S3 usando um URL pré-assinado .
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')