Aracılığıyla paylaş

Azure Veri Gezgini'ne veri almak için LightIngest'i kullanma

LightIngest, Azure Veri Gezgini'a geçici veri alımı için bir komut satırı yardımcı programıdır. Yardımcı program yerel bir klasörden, Azure blob depolama kapsayıcısından veya Amazon S3 demetinden kaynak verileri çekebilir.

Alım süresinde zaman kısıtlaması olmadığından, en çok büyük miktarda veri almak istediğinizde LightIngest kullanışlıdır. Ayrıca, kayıtları daha sonra oluşturuldukları zamana göre sorgulamak istediğinizde ve alındıkları zamana göre sorgulamak istediğinizde de yararlıdır.

LightIngest komutunu otomatik olarak oluşturma örneği için bkz . Geçmiş verileri alma.

Not

Veri alımı en fazla 6 GB'lık dosya boyutunu destekler. Öneri, 100 MB ile 1 GB arasında dosya almaktır.

Önkoşullar

  • En açık. İki yoldan biriyle LightIngest'i edinin:

    • İşletim sisteminiz için En Basit ikili dosyaları indirin. İndirdikten sonra ikili dosyaların sıkıştırmasını kaldırdığından emin olun.

    • LightIngest'i .NET aracı olarak yükleyin. Bu yöntem, makinenizde .NET SDK 6.0 veya üzeri bir sürümün yüklü olmasını gerektirir. Ardından şu komutu çalıştırın:

      dotnet tool install -g Microsoft.Azure.Kusto.LightIngest

Not

Yazılım yüklemeyi gerektirmediğinden kuyruğa alınan erişim komutlarını kullanmayı göz önünde bulundurun.

LightIngest'i çalıştırma

LightIngest'i çalıştırmak için:

  1. Komut isteminde, ardından ilgili komut satırı bağımsız değişkenini girin LightIngest .

    İpucu

    Desteklenen komut satırı bağımsız değişkenlerinin listesi için girin LightIngest /help.

  2. ingest- ardından, alımı yöneten Azure Veri Gezgini kümesine bağlantı dizesini girin. bağlantı dizesi çift tırnak içine alın ve Kusto bağlantı dizesi s belirtimini izleyin.

    Örneğin:

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Performans önerileri

  • Alım yükünü en iyi şekilde yönetmek ve geçici hatalardan kurtarmak için konumundaki https://ingest-{yourClusterNameAndRegion}.kusto.windows.netalım uç noktasını kullanın.

  • En iyi alım performansı için LightIngest'in yerel dosyaların sıkıştırılmamış boyutunu tahmin edebilmesi için ham veri boyutuna ihtiyacı vardır. Ancak LightIngest, sıkıştırılmış blobların ham boyutunu ilk indirmeden doğru tahminde bulunamayabilir. Bu nedenle, sıkıştırılmış blobları alırken blob meta verilerindeki özelliğini bayt cinsinden sıkıştırılmamış veri boyutuna ayarlayın rawSizeBytes .

Komut satırı bağımsız değişkenleri

Bağımsız değişken Türü Açıklama Gerekli
string Kusto bağlantı dizesi alımı işleyen Kusto uç noktasını belirtir. Bu değeri çift tırnak içine alın. ✔️
-veritabanı, -db string Hedef Azure Veri Gezgini veritabanı adı.
-masa string Hedef Azure Veri Gezgini tablo adı. ✔️
-sourcePath, -source string Yerel dosya yolu, Azure blob kapsayıcısının kök URI'si veya Amazon S3 demetinin URI'si olabilecek kaynak verilerin konumu. Veriler Azure bloblarında depolanıyorsa, URI depolama hesabı anahtarını veya Paylaşılan Erişim İmzası'nı (SAS) içermelidir. Veriler bir S3 demetindeyse, URI'nin kimlik bilgisi anahtarını içermesi gerekir. Bu değeri çift tırnak içine alın. Daha fazla bilgi için bkz. Depolama bağlantı dizesi. Pass -sourcePath:; kullanıcı izinleri (kullanıcı istemi yetkilendirmesi) ile Azure depolama öğelerini listelemek için kimliğe bürünme. ✔️
-yönetilenKimlik, -yk string Bağlanmak için kullanılacak yönetilen kimliğin (kullanıcı tarafından atanan veya sistem tarafından atanan) istemci kimliği. Sistem tarafından atanan kimlik için "system" kullanın.
-azCli bool Ayarlanırsa, Kusto hizmetinde kimlik doğrulaması yapmak için Azure CLI'yı kullanır. Azure CLI yüklü ve oturum açmış olmalıdır.
-ingestWithManagedIdentity, -ingestmi (yönetilen kimlikle içerik yükleme, kısayol) string Depolama alanından indirilmesi için Kusto hizmetinde yüklü yönetilen kimliğin (kullanıcı tarafından atanan veya sistem tarafından atanan) istemci kimliği. Sistem tarafından atanan kimlik için "system" kullanın.
-connectToStorageWithManagedIdentity, -storageMi string Depolama alanından listelenecek istemci tarafında yüklü yönetilen kimliğin (kullanıcı tarafından atanan veya sistem tarafından atanan) istemci kimliği.
-connectToStorageWithUserAuth, -storageUserAuth string Kullanıcı kimlik bilgileriyle veri kaynağı depolama hizmetinde kimlik doğrulaması. Bu değerin seçenekleri veya PROMPTşeklindedirDEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Ayarlanırsa -connectToStorageWithUserAuth , isteğe bağlı olarak bir Microsoft Entra Id oturum açma URI'si sağlayabilirsiniz.
-önek string Alınacak kaynak veriler blob depolamada bulunduğunda, bu URL ön eki kapsayıcı adı hariç tüm bloblar tarafından paylaşılır.
Örneğin, veriler içindeyse MyContainer/Dir1/Dir2ön ek olmalıdır Dir1/Dir2. Bu değeri çift tırnak içine alın.
-desen string Kaynak dosyaların ve blobların seçildiği desen. Joker karakterleri destekler. Örneğin, "*.csv". Bu değeri çift tırnak içine alın.
-zipPattern string Zip arşivinde hangi dosyaların alınıp alınamayacaını seçerken kullanılacak normal ifade. Arşivdeki diğer tüm dosyalar yoksayılır. Örneğin, "*.csv". Bu değeri çift tırnak içine alın.
-format, -f string Kaynak veri biçimi. Desteklenen biçimlerden biri olmalıdır
-ingestionMappingPath, -mappingPath string Alma sütunu eşlemesi için yerel bir dosyanın yolu. Bkz. veri eşlemeleri.
-ingestionMappingRef, -mappingRef string Tabloda daha önce oluşturduğunuz bir alma sütunu eşlemesinin adı. Bkz. veri eşlemeleri.
-creationTimePattern string Ayarlandığında, dosya veya blob yolundan CreationTime özelliğini ayıklamak için kullanılır. Bkz . kullanarak CreationTimeverileri alma.
-ignoreFirstRow, -ignoreFirst bool Ayarlanırsa, her dosyanın veya veri bloğunun ilk kaydı yoksayılır. Örneğin, kaynak verilerde üst bilgiler varsa.
-etiket string Alınan verilerle ilişkilendirilecek etiketler . Birden çok oluşuma izin verilir
-dontWait bool olarak ayarlanırsa true, alımın tamamlanmasını beklemez. Büyük miktarlarda dosya ve blob yüklerken kullanışlıdır.
-sıkıştırma, -cr çift Sıkıştırma oranı ipucu. Azure Veri Gezgini'nin ham veri boyutunu değerlendirmesine yardımcı olmak için sıkıştırılmış dosyaları ve blobları alırken kullanışlıdır. Özgün boyut sıkıştırılmış boyuta bölünmüş olarak hesaplanır.
-limit, -sınır integer Ayarlanırsa, alımı ilk N dosyalarıyla sınırlar.
-listOnly, -list bool Ayarlanırsa, yalnızca alım için seçilecek öğeleri görüntüler.
-ingestTimeout integer Tüm alma işlemlerinin tamamlanması için dakika cinsinden zaman aşımı. varsayılan değeridir 60.
-forceSync bool Ayarlanırsa, zaman uyumlu alımı zorlar. varsayılan değeridir false.
-Etkileşimli bool olarak ayarlanırsa false, bağımsız değişkenlerin onaylanmasını istemez. Katılımsız akışlar ve etkileşimli olmayan ortamlar için. Varsayılan true değeridir.
-dataBatchSize integer Her alma işleminin toplam boyut sınırını (MB, sıkıştırılmamış) ayarlar.
-filesInBatch integer Her alma işleminin dosya ve blob sayısı sınırını ayarlar.
-devİzleme, -izleme string Ayarlanırsa, tanılama günlükleri yerel bir dizine yazılır (varsayılan olarak, RollingLogs geçerli dizinde veya anahtar değeri ayarlanarak değiştirilebilir).

Azure blob'a özgü özellikler

Azure bloblarıyla LightIngest kullandığınızda, alım işlemini geliştirmek için belirli blob meta veri özelliklerini kullanır.

Meta veri özelliği Kullanım
rawSizeBytes, kustoUncompressedSizeBytes Ayarlanırsa, LightIngest bu özellikleri sıkıştırılmamış veri boyutu olarak yorumlar
kustoCreationTime, kustoCreationTimeUtc LightIngest bu özellikleri UTC zaman damgası olarak yorumlar. Ayarlanırsa, Kusto'da oluşturma süresini geçersiz kılmak için bu özellikleri kullanır. Bu özellik, geri doldurma senaryoları için kullanışlıdır

Kullanım örnekleri

Aşağıdaki örneklerde, işletim sisteminiz için LightIngest ikili dosyalarını yüklediğiniz varsayılır. LightIngest'i bir .NET aracı olarak yüklediyseniz, örneklerde LightIngest yerine LightIngest kullanın.

CreationTime özelliğiyle geçmiş verileri alma

Mevcut bir sistemden Azure Veri Gezgini'ne geçmiş verileri yüklediğinizde, tüm kayıtlar aynı alım tarihine sahip olur. Verilerinizi alma zamanı yerine oluşturma zamanına göre bölümlendirmek için -creationTimePattern argümanını kullanın. -creationTimePattern bağımsız değişkeni, dosya veya blob yolundan özelliğini ayıklarCreationTime. Desenin, yalnızca kullanmak istediğiniz zaman damgasını kapsayan bölümün tüm öğe yolunu yansıtması gerekmez.

Bağımsız değişken değerleri şunları içermelidir:

Önemli

Oluşturma zamanının geçersiz kılınması gerektiğini belirttiğinizde, hedef tablonun etkili Lookback özelliğin dosya veya blob yollarındaki değerlerle uyumlu olduğundan emin olun.

Örnekler

  • Tarih saatini aşağıdaki gibi içeren bir blob adı: historicalvalues19840101.parquet (zaman damgası yıl için dört basamak, ay için iki basamak ve ay günü için iki basamaktır),

    Bağımsız değişkeninin değeri -creationTimePattern dosya adının bir parçasıdır: "'historicalvalues'yyyyMMdd'.parquet'"

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • gibi https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extensionhiyerarşik klasör yapısına başvuran bir blob URI'sinde

    Bağımsız değişkeninin değeri -creationTimePattern klasör yapısının bir parçasıdır: "'folder/'yyyy/MM/dd'/blob'"

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Depolama hesabı anahtarı veya SAS belirteci kullanarak blobları alma

  • Belirtilen depolama hesabı ACCOUNTaltında, klasöründe DIR, kapsayıcı CONTaltında ve desenle eşleşen 10 blob alın *.csv.gz
  • Hedef veritabanı DB, tablo TABLEve alma eşlemesi MAPPING hedefte önceden oluşturulur
  • Araç alma işlemleri tamamlanana kadar bekler
  • Hedef veritabanı ve depolama hesabı anahtarını ve SAS belirtecini belirtmek için farklı seçeneklere dikkat edin
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Üst bilgi satırları dahil olmak üzere kapsayıcıdaki tüm blobları alma

  • Belirtilen depolama hesabı ACCOUNTaltında, klasöründe DIR1/DIR2, kapsayıcı CONTaltında ve desenle eşleşen tüm blobları alın *.csv.gz
  • Hedef veritabanı DB, tablo TABLEve alma eşlemesi MAPPING hedefte önceden oluşturulur
  • Kaynak bloblar üst bilgi satırı içerdiğinden, araç her blobun ilk kaydını bırakması istenir
  • Araç, veri alımı için verileri gönderip alma işlemlerinin tamamlanmasını beklemez
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Tüm JSON dosyalarını bir yoldan alma

  • Desen PATH ile eşleşen *.json yolunun altındaki tüm dosyaları içeri aktar
  • Hedefi veritabanı DB, tablo TABLE ve yerel dosyada MAPPING_FILE_PATH alım eşlemesi olarak ayarlayın.
  • Araç, veri alımı için verileri gönderip alma işlemlerinin tamamlanmasını beklemez
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Dosyaları içe aktarma ve tanılama izi dosyaları yazma

  • Desen PATH ile eşleşen *.json yolunun altındaki tüm dosyaları içeri aktar
  • Hedefi veritabanı DB, tablo TABLE ve yerel dosyada MAPPING_FILE_PATH alım eşlemesi olarak ayarlayın.
  • Araç, veri alımı için verileri gönderip alma işlemlerinin tamamlanmasını beklemez
  • Tanılama izleme dosyalarını LOGS_PATH klasörü altında yerel olarak yazın.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"

Yönetilen kimlikle kimlik doğrulaması

LightIngest, kimlik doğrulaması için yönetilen kimliği kullanabilen üç eylem gerçekleştirir. Her adımda yönetilen kimlik kullanımı, diğer adımlarda yönetilen kimliğin kullanılmasını gerektirmez. Her eylem için ilgili komut satırı bağımsız değişkeni verilir.

  • Kusto kümesine bağlanma: Alımı kuyruğa almak için araç bir bağlantı dizesi kullanır. hedef veritabanında alma ayrıcalıklarına sahip istemci VM'sinde yüklü bir yönetilen kimlik belirtmek için "-mi" bağımsız değişkenini kullanın.

  • Blobları indirmek için Azure Depolama'ya bağlanın: Depolama kapsayıcısı üzerinde okuma ayrıcalıklarına sahip Kusto hizmetinde yüklü bir yönetilen kimlik belirtmek için "-ingestmi" kullanın.

  • Kapsayıcı bloblarını listelemek için Azure Depolama'ya bağlanın: depolama kapsayıcısı üzerinde liste ayrıcalıklarına sahip istemci VM'sinde yüklü bir yönetilen kimlik belirtmek için "-storageMi" bağımsız değişkenini kullanın. Bu yöntemi kullanıyorsanız ancak önceki yöntemi (blobları indirmek için Azure depolamaya bağlanmak) kullanmıyorsanız, yönetilen kimliğin okuma ayrıcalıklarına sahip olması gerekir ve Kusto hizmetine verilerin içe aktarılması için kullanılacak bir belirteç iletilir. Üç argümanı da ayarlayın.

  • Last updated on