다음을 통해 공유

스토리지에서 수집

  • 아티클

적용 대상: ✅Microsoft Fabric✅Azure Data Explorer

이 .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 값과 같이 사용되는 고유 수집 매핑 속성이 많을수록 수집이 조각화되어 성능이 저하될 수 있습니다.

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

속성 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']")
TreatGzAsUncompressed 확장 .gz 이 있는 파일이 압축되지 않음을 true나타내는 부울 값입니다. Amazon AWS S3에서 수집할 때 이 플래그가 필요한 경우도 있습니다. with (treatGzAsUncompressed=true)
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')