스토리지에서 수집

이 .ingest into 명령은 하나 이상의 클라우드 스토리지 파일에서 데이터를 "끌어와서" 테이블로 데이터를 수집합니다. 예를 들어 명령은 Azure Blob Storage에서 1,000개의 CSV 형식 Blob을 검색하고, 구문 분석하고, 단일 대상 테이블로 수집할 수 있습니다. 데이터는 기존 레코드에 영향을 주지 않고 테이블의 스키마를 수정하지 않고 테이블에 추가됩니다.

참고 항목

이 수집 방법은 탐색 및 프로토타입 생성을 위한 것입니다. 프로덕션 또는 대용량 시나리오에서는 사용하지 마세요.

사용 권한

이 명령을 실행하려면 테이블 수집기 이상의 권한이 있어야 합니다.

구문

.ingest [async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	Type	필수	설명
async	string		지정한 경우 명령은 즉시 반환되고 백그라운드에서 수집을 계속합니다. 명령의 결과에는 수집 완료 상태 및 결과를 검색하기 위해 명령과 함께 .show operation 사용할 수 있는 값이 포함 OperationId 됩니다.
TableName	string	✔️	데이터를 수집할 테이블의 이름입니다. 테이블 이름은 항상 컨텍스트에서 데이터베이스를 기준으로 합니다. 스키마 매핑 개체가 제공되지 않으면 컨텍스트에서 데이터베이스의 스키마가 사용됩니다.
SourceDataLocator	string	✔️	스토리지 연결 문자열 단일 또는 쉼표로 구분된 목록입니다. 단일 연결 문자열 스토리지 계정에서 호스트하는 단일 파일을 참조해야 합니다. 여러 연결 문자열 지정하거나 외부 테이블의 쿼리에서 수집하여 여러 파일을 수집할 수 있습니다.

참고 항목

SourceDataLocators에 난독 제거된 문자열 리터럴을 사용하는 것이 좋습니다. 서비스는 내부 추적 및 오류 메시지에서 자격 증명을 스크러빙합니다.

수집 속성

Important

• 큐에 대기 중인 수집 데이터는 수집 속성을 사용하여 일괄 처리됩니다. 다른 ConstValue 값과 같이 사용되는 고유 수집 매핑 속성이 많을수록 수집이 조각화되어 성능이 저하될 수 있습니다.

다음 표에서는 Azure Data Explorer에서 지원하는 속성을 나열하고, 설명하고, 예제를 제공합니다.

속성	Description	예시
ingestionMapping	원본 파일의 데이터를 테이블의 실제 열에 매핑하는 방법을 나타내는 문자열 값입니다. 관련 매핑 유형을 사용하여 format 값을 정의합니다. 데이터 매핑을 참조하세요.	with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]") (사용되지 않음: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference	명명된 매핑 정책 개체를 사용하여 원본 파일에서 테이블의 실제 열로 데이터를 매핑하는 방법을 나타내는 문자열 값입니다. 관련 매핑 유형을 사용하여 format 값을 정의합니다. 데이터 매핑을 참조하세요.	with (format="csv", ingestionMappingReference = "Mapping1") (사용되지 않음: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime	수집되는 데이터 범위를 만드는 시간에 사용할 날짜/시간 값(ISO8601 문자열 형식)입니다. 지정하지 않으면 현재 값(now())이 사용됩니다. 보존 정책이 올바르게 적용되도록 이전 데이터를 수집할 때 기본값을 재정의하는 것이 유용합니다. 지정된 경우 대상 테이블의 유효한 익스텐트 병합 정책의 Lookback 속성이 지정된 값과 일치하는지 확인합니다.	with (creationTime="2017-02-13")
extend_schema	지정하면 테이블의 스키마를 확장하도록 명령에 지시하는 부울 값(기본값: false)입니다. 이 옵션은 .append 및 .set-or-append 명령에만 적용됩니다. 유일하게 허용되는 스키마 확장에는 테이블의 끝에 추가되는 추가 열이 있습니다.	원래 테이블 스키마가 (a:string, b:int)인 경우 유효한 스키마 확장은 (a:string, b:int, c:datetime, d:string)이지만 (a:string, c:datetime)은 유효하지 않습니다.
folder	ingest-from-query 명령의 경우 테이블에 할당할 폴더입니다. 테이블이 이미 있으면 이 속성은 테이블의 폴더를 재정의합니다.	with (folder="Tables/Temporary")
format	데이터 형식입니다(지원되는 데이터 형식 참조).	with (format="csv")
ingestIfNotExists	지정하면 동일한 값을 가진 ingest-by: 태그로 태그가 지정된 데이터가 테이블에 이미 있는 경우 수집하지 못하게 하는 문자열 값입니다. 이렇게 하면 idempotent(멱등원) 데이터 수집이 보장됩니다. 자세한 내용은 ingest-by: 태그를 참조하세요.	with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') 속성은 태그가 ingest-by:Part0001인 데이터가 이미 있는 경우 현재 수집을 완료하지 않음을 나타냅니다. 아직 없는 경우 이 새 수집에는 이 태그가 설정되어 있어야 합니다(이후 수집에서 동일한 데이터를 다시 수집하려고 하는 경우).
ignoreFirstRecord	true로 설정하면 수집에서 모든 파일의 첫 번째 레코드를 무시해야 함을 나타내는 부울 값입니다. 이 속성은 파일의 첫 번째 레코드가 열 이름인 경우 CSV와 유사한 형식의 파일에 유용합니다. 기본적으로 false로 가정됩니다.	with (ignoreFirstRecord=false)
policy_ingestiontime	지정하면 이 명령으로 만든 테이블에서 수집 시간 정책을 사용하도록 설정할지 여부를 설명하는 부울 값입니다. 기본값은 true입니다.	with (policy_ingestiontime=false)
recreate_schema	지정하면 명령에서 테이블의 스키마를 다시 만들 수 있는지 여부를 설명하는 부울 값입니다. 이 속성은 .set-or-replace 명령에만 적용됩니다. 이 속성과 extend_schema 속성이 모두 설정되면 이 속성이 우선 적용됩니다.	with (recreate_schema=true)
tags	수집된 데이터와 연결할 JSON 문자열 형식의 태그 목록입니다.	with (tags="['Tag1', 'Tag2']")
validationPolicy	CSV 형식을 사용하여 표시되는 데이터를 수집하는 동안 실행할 유효성 검사를 나타내는 JSON 문자열입니다. 다양한 옵션에 관한 설명은 데이터 수집을 참조하세요.	with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}')(실제로 기본 정책임).
zipPattern	ZIP 보관 파일이 있는 스토리지에서 데이터를 수집하는 경우 이 속성을 사용합니다. 이는 수집할 ZIP 보관 파일의 파일을 선택할 때 사용할 정규식을 나타내는 문자열 값입니다. 보관 파일의 다른 모든 파일은 무시됩니다.	with (zipPattern="*.csv")

인증 및 권한 부여

각 스토리지 연결 문자열 스토리지에 액세스하는 데 사용할 권한 부여 방법을 나타냅니다. 권한 부여 방법에 따라 수집을 수행하려면 보안 주체에게 외부 스토리지에 대한 권한을 부여해야 할 수 있습니다.

다음 표에서는 지원되는 인증 방법 및 외부 스토리지에서 데이터를 수집하는 데 필요한 권한을 나열합니다.

인증 방법	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
가장	Storage Blob 데이터 읽기 권한자	판독기
SAS(공유 액세스) 토큰	목록 + 읽기	이 인증 방법은 Gen1에서 지원되지 않습니다.
Microsoft Entra 액세스 토큰
스토리지 계정 액세스 키		이 인증 방법은 Gen1에서 지원되지 않습니다.
관리 ID	Storage Blob 데이터 읽기 권한자	판독기

반품

명령의 결과는 명령에서 생성된 데이터 분할("익스텐트")만큼 많은 레코드가 포함된 테이블입니다. 데이터 분할된 데이터베이스가 생성되지 않은 경우 빈(0값) 익스텐트 ID를 사용하여 단일 레코드가 반환됩니다.

속성	형식	설명
ExtentId	guid	명령으로 생성된 데이터 분할의 고유 식별자입니다.
ItemLoaded	string	이 레코드와 관련된 하나 이상의 스토리지 파일입니다.
기간	timespan	데이터 수집을 수행하는 데 걸리는 시간입니다.
HasErrors	bool	이 레코드가 수집 실패 여부를 나타낼지 지정합니다.
OperationId	guid	작업을 나타내는 고유 ID입니다. .show operation 명령과 함께 사용할 수 있습니다.

참고 항목

이 명령은 수집되는 테이블의 스키마를 수정하지 않습니다. 필요한 경우 데이터가 수집 중에 이 스키마로 "강제 변환"되며, 그 반대로는 변환되지 않습니다(추가 열은 무시되고 누락된 열은 Null 값으로 처리됨).

예제

공유 액세스 서명이 있는 Azure Blob Storage

다음 예제에서는 Azure Blob Storage에서 두 개의 Blob을 CSV 파일로 읽고 해당 내용을 테이블 T로 수집하도록 클러스터에 지시합니다. 각 ... Blob에 대한 읽기 액세스를 제공하는 Azure Storage SAS(공유 액세스 서명)를 나타냅니다. 또한 SAS가 기록되지 않도록 난독 분석된 문자열( h 문자열 값 앞)을 사용합니다.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

관리 ID가 있는 Azure Blob Storage

다음 예제에서는 관리 ID 인증을 사용하여 Azure Blob Storage에서 CSV 파일을 읽고 해당 내용을 테이블 T 로 수집하는 방법을 보여 줍니다. 관리 ID 인증 방법에 대한 자세한 내용은 관리 ID 인증 개요를 참조 하세요.

.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

다음 예제는 ADLSv2(Azure Data Lake Storage Gen 2)에서 데이터를 수집하는 것입니다. 여기서 사용되는 자격 증명(...)은 스토리지 계정 자격 증명(공유 키)이며, 연결 문자열 비밀 부분에 대해서만 문자열 난독화를 사용합니다.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

다음 예제에서는 ADLS(Azure Data Lake Storage)에서 단일 파일을 수집합니다. 사용자의 자격 증명을 사용하여 ADLS에 액세스합니다(따라서 스토리지 URI를 비밀을 포함하는 것으로 처리할 필요가 없음). 또한 수집 속성을 지정하는 방법도 보여줍니다.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

액세스 키가 있는 Amazon S3

다음 예제에서는 액세스 키 ID 및 비밀 액세스 키를 사용하여 Amazon S3에서 단일 파일을 수집합니다.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

미리 서명된 URL이 있는 Amazon S3

다음 예제에서는 미리 서명된 URL을 사용하여 Amazon S3에서 단일 파일을 수집합니다.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')