Ingestão de armazenamento
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer
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
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.
Permissões
Você deve ter pelo menos permissões de Table Ingestor para executar este comando.
Sintaxe
.ingest [async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]
Saiba mais sobre as convenções de sintaxe.
Parâmetros
| Nome | Digitar | Obrigatória | 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 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 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
Recomendamos o uso de literais de cadeia de caracteres ofuscados para os SourceDataLocators. O serviço limpará credenciais em rastreamentos internos e mensagens de erro.
Propriedades da ingestão
Importante
Na ingestão enfileirada, os dados são agrupados em lote usando as propriedades de assimilação. Quanto mais propriedades de mapeamento de ingestão distintas forem usadas, como valores ConstValue diferentes, mais fragmentada a ingestão se tornará, 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. 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()) é 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 mais colunas adicionadas à tabela no final. |
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']") |
TreatGzAsUncompressed |
Um valor booleano que, se definido como true, indica que os arquivos com a extensão .gz não estã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 devem ser executadas 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}') (esta é 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 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 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 de Acesso Compartilhado (SAS) | Listar + Ler | Não há suporte para esse método de autenticação no Gen1. |
| 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. | |
| Identidade gerenciada | Leitor de Dados do Blob de Armazenamento | Leitor |
Devoluções
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. |
| Duration | 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 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. 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 do 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 do 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 do ADLS (Azure Data Lake Storage). 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 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')