LightIngest를 사용 하 여 Azure 데이터 탐색기에 데이터 수집Use LightIngest to ingest data to Azure Data Explorer

LightIngest는 Azure 데이터 탐색기에 대 한 임시 데이터 수집을 위한 명령줄 유틸리티입니다.LightIngest is a command-line utility for ad-hoc data ingestion into Azure Data Explorer. 유틸리티는 로컬 폴더 또는 Azure blob 저장소 컨테이너에서 원본 데이터를 끌어올 수 있습니다.The utility can pull source data from a local folder or from an Azure blob storage container. LightIngest는 수집 기간에 시간 제한이 없기 때문에 많은 양의 데이터를 수집 하려는 경우에 가장 유용 합니다.LightIngest is most useful when you want to ingest a large amount of data, because there is no time constraint on ingestion duration. 이는 나중에 생성 된 시간에 따라 레코드를 쿼리 하 고 수집 시간이 아닌 경우에도 유용 합니다.It's also useful when you want to later query records according to the time they were created, and not the time they were ingested.

사전 요구 사항Prerequisites

LightIngest 설치Install LightIngest

  1. LightIngest를 다운로드 한 컴퓨터의 위치로 이동 합니다.Navigate to the location on your computer where you downloaded LightIngest.
  2. WinRAR를 사용 하 여 도구 디렉터리를 컴퓨터에 추출 합니다.Using WinRAR, extract the tools directory to your computer.

LightIngest 실행Run LightIngest

  1. 컴퓨터에서 추출 된 tools 디렉터리로 이동 합니다.Navigate to the extracted tools directory on your computer.

  2. 위치 표시줄에서 기존 위치 정보를 삭제 합니다.Delete the existing location information from the location bar.

    Azure 데이터 탐색기에서 LightIngest에 대 한 기존 위치 정보 삭제

  3. cmd을 입력하고 Enter 키를 누릅니다.Enter cmd and press Enter.

  4. 명령 프롬프트에서를 입력 한 LightIngest.exe 다음 관련 명령줄 인수를 입력 합니다.At the command prompt, enter LightIngest.exe followed by the relevant command-line argument.

    지원 되는 명령줄 인수 목록을 보려면를 입력 하십시오 LightIngest.exe /help .For a list of supported command-line arguments, enter LightIngest.exe /help.

    LightIngest에 대 한 명령줄 도움말

  5. ingest-그런 다음 수집을 관리할 Azure 데이터 탐색기 클러스터에 대 한 연결 문자열을 입력 합니다.Enter ingest- followed by the connection string to the Azure Data Explorer cluster that will manage the ingestion. 연결 문자열을 큰따옴표로 묶고 Kusto 연결 문자열 사양을따릅니다.Enclose the connection string in double quotes and follow the Kusto connection strings specification.

    다음은 그 예입니다. For example:

    ingest-{Cluster name and region}.kusto.windows.net;AAD Federated Security=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
    

권장 사항Recommendations

  • LightIngest가에서 수집 끝점을 사용 하는 것이 좋습니다 https://ingest-{yourClusterNameAndRegion}.kusto.windows.net .The recommended method is for LightIngest to work with the ingestion endpoint at https://ingest-{yourClusterNameAndRegion}.kusto.windows.net. 이러한 방식으로 Azure 데이터 탐색기 서비스는 수집 부하를 관리할 수 있으며 일시적인 오류를 쉽게 복구할 수 있습니다.This way, the Azure Data Explorer service can manage the ingestion load, and you can easily recover from transient errors. 그러나 엔진 엔드포인트 ()로 직접 작업 하도록 LightIngest를 구성할 수도 있습니다 https://{yourClusterNameAndRegion}.kusto.windows.net .However, you can also configure LightIngest to work directly with the engine endpoint (https://{yourClusterNameAndRegion}.kusto.windows.net).

    참고

    엔진 끝점을 사용 하 여 직접 수집 하는 경우에는를 포함할 필요가 없습니다 ingest- .If you ingest directly with the engine endpoint, you don't need to include ingest-. 그러나 엔진을 보호 하 고 수집 성공률을 높이기 위한 DM 기능은 없습니다.However, there won't be a DM feature to protect the engine and improve the ingestion success rate.

  • 최적의 수집 성능을 위해 LightIngest는 로컬 파일의 압축 되지 않은 크기를 예상할 수 있도록 원시 데이터 크기가 필요 합니다.For optimal ingestion performance, the raw data size is needed so LightIngest can estimate the uncompressed size of local files. 그러나 LightIngest는 먼저 파일을 다운로드 하지 않고 압축 된 blob의 원시 크기를 정확 하 게 추정 하지 못할 수 있습니다.However, LightIngest might not be able to correctly estimate the raw size of compressed blobs without first downloading them. 따라서 압축 된 blob을 수집 때 rawSizeBytes blob 메타 데이터의 속성을 압축 되지 않은 데이터 크기 (바이트)로 설정 합니다.Therefore, when ingesting compressed blobs, set the rawSizeBytes property on the blob metadata to uncompressed data size in bytes.

명령줄 인수Command-line arguments

인수 이름Argument name 유형Type DescriptionDescription 필수/선택 사항Mandatory/Optional
문자열string 수집을 처리 하는 Kusto 끝점을 지정 하는 Azure 데이터 탐색기 연결 문자열 입니다.Azure Data Explorer Connection String specifying the Kusto endpoint that will handle the ingestion. 큰따옴표로 묶어야 합니다.Should be enclosed in double quotes 필수Mandatory
-database,-db-database, -db 문자열string 대상 Azure 데이터 탐색기 데이터베이스 이름Target Azure Data Explorer database name 선택 사항Optional
-테이블-table 문자열string 대상 Azure 데이터 탐색기 테이블 이름Target Azure Data Explorer table name 필수Mandatory
-sourcePath,-source-sourcePath, -source 문자열string Blob 컨테이너의 원본 파일 또는 루트 URI에 대 한 경로입니다.Path to source files or root URI of the blob container. 데이터가 blob에 있는 경우에는 저장소 계정 키 또는 SAS를 포함 해야 합니다.If the data is in blobs, must contain storage account key or SAS. 큰따옴표로 묶는 것이 좋습니다.Recommended to enclose in double quotes 필수Mandatory
-접두사-prefix 문자열string 수집할 원본 데이터가 blob 저장소에 있는 경우이 URL 접두사는 컨테이너 이름을 제외 하 고 모든 blob에서 공유 됩니다.When the source data to ingest resides on blob storage, this URL prefix is shared by all blobs, excluding the container name.
예를 들어 데이터가에 있으면 MyContainer/Dir1/Dir2 접두사는 여야 합니다 Dir1/Dir2 .For example, if the data is in MyContainer/Dir1/Dir2, then the prefix should be Dir1/Dir2. 큰따옴표로 묶기를 권장 합니다.Enclosing in double quotes is recommended
선택 사항Optional
-패턴-pattern 문자열string 원본 파일/b s i d를 선택 하는 패턴입니다.Pattern by which source files/blobs are picked. 와일드 카드를 지원 합니다.Supports wildcards. 예: "*.csv".For example, "*.csv". 큰따옴표로 묶는 것이 좋습니다.Recommended to enclose in double quotes 선택 사항Optional
-zipPattern-zipPattern 문자열string 수집할 ZIP 보관 파일에서 파일을 선택할 때 사용할 정규식입니다.Regular expression to use when selecting which files in a ZIP archive to ingest.
보관 파일의 다른 모든 파일은 무시됩니다.All other files in the archive will be ignored. 예: "*.csv".For example, "*.csv". 큰따옴표로 묶는 것이 좋습니다.It's recommended to surround it in double quotes
선택 사항Optional
-format,-f-format, -f 문자열string 원본 데이터 형식입니다.Source data format. 지원 되는 형식 중 하나 여야 합니다.Must be one of the supported formats 선택 사항Optional
-ingestionMappingPath, -mappingPath-ingestionMappingPath, -mappingPath 문자열string 수집 열 매핑의 로컬 파일 경로입니다.Path to local file for ingestion column mapping. Json 및 Avro 형식의 필수 항목입니다.Mandatory for Json and Avro formats. 데이터 매핑 참조See data mappings 선택 사항Optional
-ingestionMappingRef, -mappingRef-ingestionMappingRef, -mappingRef 문자열string 테이블에 대해 이전에 만든 수집 열 매핑의 이름입니다.Name of an ingestion column mapping that was previously created on the table. Json 및 Avro 형식의 필수 항목입니다.Mandatory for Json and Avro formats. 데이터 매핑 참조See data mappings 선택 사항Optional
-creationTimePattern-creationTimePattern 문자열string 설정 되 면 파일 또는 blob 경로에서 CreationTime 속성을 추출 하는 데 사용 됩니다.When set, is used to extract the CreationTime property from the file or blob path. 을 사용 하 여 CreationTime 데이터를 수집 하는 방법을 참조 하세요.See How to ingest data using CreationTime 선택 사항Optional
-ignoreFirstRow,-ignoreFirst-ignoreFirstRow, -ignoreFirst boolbool 설정 하는 경우 각 파일/b i d의 첫 번째 레코드가 무시 됩니다 (예: 원본 데이터에 헤더가 있는 경우).If set, the first record of each file/blob is ignored (for example, if the source data has headers) 선택 사항Optional
-태그-tag 문자열string 수집 데이터와 연결할 태그 입니다.Tags to associate with the ingested data. 여러 번 발생할 수 있습니다.Multiple occurrences are permitted 선택 사항Optional
-dontWait-dontWait boolbool ' T r u e '로 설정 되 면 수집 완료를 기다리지 않습니다.If set to 'true', doesn't wait for ingestion completion. 많은 양의 파일/b s 수집 경우 유용 합니다.Useful when ingesting large amounts of files/blobs 선택 사항Optional
-압축,-cr-compression, -cr doubledouble 압축률 힌트입니다.Compression ratio hint. Azure 데이터 탐색기 원시 데이터 크기를 평가 하는 데 도움이 되는 압축 된 파일/a p i를 수집 때 유용 합니다.Useful when ingesting compressed files/blobs to help Azure Data Explorer assess the raw data size. 원래 크기를 압축 크기로 나눈 값Calculated as original size divided by compressed size 선택 사항Optional
-limit,-l-limit , -l integerinteger 설정 하는 경우 수집을 처음 N 개 파일로 제한 합니다.If set, limits the ingestion to first N files 선택 사항Optional
-listOnly,-list-listOnly, -list boolbool 설정 되 면 수집 하도록 선택 된 항목만 표시 됩니다.If set, only displays the items that would have been selected for ingestion 선택 사항Optional
-ingestTimeout-ingestTimeout integerinteger 모든 수집 작업 완료에 대 한 시간 제한 (분)입니다.Timeout in minutes for all ingest operations completion. 기본값은 60입니다.Defaults to 60 선택 사항Optional
-forceSync-forceSync boolbool 설정 되 면 동기 수집을 강제로 수행 합니다.If set, forces synchronous ingestion. 기본값은 false입니다.Defaults to false 선택 사항Optional
-dataBatchSize-dataBatchSize integerinteger 각 수집 작업의 총 크기 제한 (MB, 압축 되지 않음)을 설정 합니다.Sets the total size limit (MB, uncompressed) of each ingest operation 선택 사항Optional
-filesInBatch-filesInBatch integerinteger 각 수집 작업의 파일/b a p 수 제한을 설정 합니다.Sets the file/blob count limit of each ingest operation 선택 사항Optional
-devTracing,-trace-devTracing, -trace 문자열string 설정 하는 경우에는 기본적으로 현재 디렉터리에 있는 로컬 디렉터리에 진단 로그가 기록 RollingLogs 되거나 스위치 값을 설정 하 여 수정할 수 있습니다.If set, diagnostic logs are written to a local directory (by default, RollingLogs in the current directory, or can be modified by setting the switch value) 선택 사항Optional

Azure blob 관련 기능Azure blob-specific capabilities

Azure blob과 함께 사용 하는 경우 LightIngest는 특정 blob 메타 데이터 속성을 사용 하 여 수집 프로세스를 보강 합니다.When used with Azure blobs, LightIngest will use certain blob metadata properties to augment the ingestion process.

Metadata 속성Metadata property 사용량Usage
rawSizeBytes, kustoUncompressedSizeBytesrawSizeBytes, kustoUncompressedSizeBytes 설정 하는 경우 압축 되지 않은 데이터 크기로 해석 됩니다.If set, will be interpreted as the uncompressed data size
kustoCreationTime, kustoCreationTimeUtckustoCreationTime, kustoCreationTimeUtc UTC 타임 스탬프로 해석 됩니다.Interpreted as UTC timestamp. 설정 하는 경우 Kusto에서 만든 시간을 재정의 하는 데 사용 됩니다.If set, will be used to override the creation time in Kusto. 백필 시나리오에 유용Useful for backfilling scenarios

사용 예Usage examples

CreationTime를 사용 하 여 데이터를 수집 하는 방법How to ingest data using CreationTime

기존 시스템에서 Azure 데이터 탐색기로 기록 데이터를 로드 하는 경우 모든 레코드가 수집 날짜와 동일 하 게 수신 됩니다.When you load historical data from existing system to Azure Data Explorer, all records receive the same the ingestion date. 수집 시간이 아니라 생성 시간을 기준으로 데이터를 분할할 수 있도록 하기 위해 인수를 사용할 수 있습니다 -creationTimePattern .To enable partitioning your data by creation time and not ingestion time, you can use the -creationTimePattern argument. -creationTimePattern인수는 CreationTime 파일 또는 blob 경로에서 속성을 추출 합니다.The -creationTimePattern argument extracts the CreationTime property from the file or blob path. 패턴은 전체 항목 경로를 반영 하지 않아도 되며, 사용 하려는 타임 스탬프를 포함 하는 섹션에 불과합니다.The pattern doesn't need to reflect the entire item path, just the section enclosing the timestamp you want to use.

인수 값은 다음을 포함 해야 합니다.The argument values must include:

  • 작은따옴표 (접두사)로 묶인 타임 스탬프 형식 바로 앞에 있는 상수 텍스트Constant text immediately preceding the timestamp format, enclosed in single quotes (prefix)
  • 표준 .Net DateTime 표기법 의 타임 스탬프 형식The timestamp format, in standard .NET DateTime notation
  • 타임 스탬프 (접미사) 바로 다음에 오는 상수 텍스트입니다.Constant text immediately following the timestamp (suffix).

Examples

  • 다음과 같이 날짜/시간을 포함 하는 blob 이름. historicalvalues19840101.parquet (타임 스탬프는 연도에 대 한 4 자리, 월의 경우 두 자리, 월의 경우 두 자리)입니다.A blob name that contains the datetime as follows: historicalvalues19840101.parquet (the timestamp is four digits for the year, two digits for the month, and two digits for the day of month),

    인수 값은 -creationTimePattern 파일 이름 "' historicalvalues'yyyyMMdd '. parquet '" 의 일부입니다.The value for -creationTimePattern argument is part of the filename: "'historicalvalues'yyyyMMdd'.parquet'"

    ingest-{Cluster name and region}.kusto.windows.net;AAD Federated Security=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
    
  • 계층 구조 폴더 구조를 참조 하는 blob URI (예:) https://storageaccount/container/folder/2002/12/01/blobname.extensionFor a blob URI that refers to hierarchical folder structure, like https://storageaccount/container/folder/2002/12/01/blobname.extension,

    인수 값은 -creationTimePattern 폴더 구조 "' folder/' YYYY/MM/dd '/blob '" 의 일부입니다.The value for -creationTimePattern argument is part of the folder structure: "'folder/'yyyy/MM/dd'/blob'"

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

저장소 계정 키 또는 SAS 토큰을 사용 하 여 blob 수집Ingesting blobs using a storage account key or a SAS token

  • 지정 된 저장소 계정 ACCOUNT , 폴더 DIR , 컨테이너 아래 CONT 및 패턴과 일치 하는 10 개의 blob을 수집 합니다. *.csv.gzIngest 10 blobs under specified storage account ACCOUNT, in folder DIR, under container CONT, and matching the pattern *.csv.gz
  • Destination은 database DB , table 이며 TABLE 대상에서 수집 매핑이 MAPPING 사전 생성 됩니다.Destination is database DB, table TABLE, and the ingestion mapping MAPPING is precreated on the destination
  • 이 도구는 수집 작업이 완료 될 때까지 대기 합니다.The tool will wait until the ingest operations complete
  • 대상 데이터베이스와 저장소 계정 키 및 SAS 토큰을 지정 하는 다양 한 옵션을 확인 합니다.Note the different options for specifying the target database and storage account key vs. SAS token
LightIngest.exe "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.exe "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

헤더 행을 제외 하 고 컨테이너의 모든 blob을 수집 합니다.Ingesting all blobs in a container, not including header rows

  • 지정 된 저장소 계정 ACCOUNT , 폴더 DIR1/DIR2 , 컨테이너 아래 CONT 및 패턴과 일치 하는 모든 blob을 수집 합니다. *.csv.gzIngest all blobs under specified storage account ACCOUNT, in folder DIR1/DIR2, under container CONT, and matching the pattern *.csv.gz
  • Destination은 database DB , table 이며 TABLE 대상에서 수집 매핑이 MAPPING 사전 생성 됩니다.Destination is database DB, table TABLE, and the ingestion mapping MAPPING is precreated on the destination
  • 원본 blob에는 헤더 줄이 포함 되어 있으므로 각 blob의 첫 번째 레코드를 삭제 하도록 도구에 지시 합니다.Source blobs contain header line, so the tool is instructed to drop the first record of each blob
  • 이 도구는 수집을 위해 데이터를 게시 하 고 수집 작업이 완료 될 때까지 기다리지 않습니다.The tool will post the data for ingestion and won't wait for the ingest operations to complete
LightIngest.exe "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

경로에서 모든 JSON 파일 수집Ingesting all JSON files from a path

  • 경로 아래에 있는 모든 파일 PATH 을 수집 합니다. 패턴과 일치 합니다. *.jsonIngest all files under path PATH, matching the pattern *.json
  • Destination이 데이터베이스 DB , 테이블 TABLE 및 수집 매핑이 로컬 파일에 정의 되어 있습니다. MAPPING_FILE_PATHDestination is database DB, table TABLE, and the ingestion mapping is defined in local file MAPPING_FILE_PATH
  • 이 도구는 수집을 위해 데이터를 게시 하 고 수집 작업이 완료 될 때까지 기다리지 않습니다.The tool will post the data for ingestion and won't wait for the ingest operations to complete
LightIngest.exe "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

파일 수집 및 진단 추적 파일 쓰기Ingesting files and writing diagnostic trace files

  • 경로 아래에 있는 모든 파일 PATH 을 수집 합니다. 패턴과 일치 합니다. *.jsonIngest all files under path PATH, matching the pattern *.json
  • Destination이 데이터베이스 DB , 테이블 TABLE 및 수집 매핑이 로컬 파일에 정의 되어 있습니다. MAPPING_FILE_PATHDestination is database DB, table TABLE, and the ingestion mapping is defined in local file MAPPING_FILE_PATH
  • 이 도구는 수집을 위해 데이터를 게시 하 고 수집 작업이 완료 될 때까지 기다리지 않습니다.The tool will post the data for ingestion and won't wait for the ingest operations to complete
  • 진단 추적 파일은 폴더에 로컬로 기록 됩니다. LOGS_PATHDiagnostics trace files will be written locally under folder LOGS_PATH
LightIngest.exe "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"