Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 HTTP 엔드포인트에서 데이터 복사

아티클
02/25/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!

이 문서에서는 Azure Data Factory 및 Azure Synapse의 복사 작업을 사용하여 HTTP 엔드포인트에서 데이터를 복사하는 방법을 간략히 설명합니다. 이 문서는 복사 작업에 대한 일반적인 개요를 제공하는 복사 작업을 기준으로 합니다.

HTTP 커넥터인 REST 커넥터와 웹 테이블 커넥터 간의 차이점은 다음과 같습니다.

REST 커넥터는 특히 RESTful API에서 데이터를 복사하는 것을 지원합니다.
HTTP 커넥터는 일반적으로 모든 HTTP 엔드포인트에서 데이터를 검색합니다(예: 파일 다운로드). REST 커넥터를 사용할 수 있게 되기 전에는 HTTP 커넥터를 사용하여 RESTful API에서 데이터를 복사할 수 있습니다. REST 커넥터에 비해 지원은 되지만 기능은 떨어집니다.
웹 테이블 커넥터는 HTML 웹 페이지에서 테이블 콘텐츠를 추출합니다.

지원되는 기능

이 HTTP 커넥터는 다음 기능에 대해 지원됩니다.

지원되는 기능	IR
복사 작업(원본/-)	① ②
조회 작업	① ②

① Azure 통합 런타임 ② 자체 호스팅 통합 런타임

원본/싱크로 지원되는 데이터 저장소의 목록은 지원되는 데이터 저장소를 참조하세요.

이 HTTP 커넥터를 사용하여 다음을 수행할 수 있습니다.

HTTP GET 또는 POST 메서드를 사용하여 HTTP/S 엔드포인트에서 데이터를 검색합니다.
Anonymous, Basic, Digest, Windows 또는 ClientCertificate 인증 중 하나를 사용하여 데이터를 검색합니다.
HTTP 응답을 그대로 복사하거나 지원되는 파일 형식과 압축 코덱을 사용하여 구문 분석합니다.

팁

HTTP 커넥터를 구성하기 전에 데이터 검색을 위한 HTTP 요청을 테스트하려면 헤더 및 본문 요구 사항의 API 사양을 알아봅니다. Postman 또는 웹 브라우저와 같은 도구를 사용하여 유효성을 검사할 수 있습니다.

필수 조건

데이터 저장소가 온-프레미스 네트워크, Azure 가상 네트워크 또는 Amazon Virtual Private Cloud 내에 있는 경우 자체 호스팅된 통합 런타임을 구성하여 연결해야 합니다.

데이터 저장소가 관리형 클라우드 데이터 서비스인 경우 Azure Integration Runtime을 사용할 수 있습니다. 액세스가 방화벽 규칙에서 승인된 IP로 제한되는 경우 허용 목록에 Azure Integration Runtime IP를 추가할 수 있습니다.

또한 Azure Data Factory의 관리형 가상 네트워크 통합 런타임 기능을 사용하면 자체 호스팅 통합 런타임을 설치하고 구성하지 않고도 온-프레미스 네트워크에 액세스할 수 있습니다.

Data Factory에서 지원하는 네트워크 보안 메커니즘 및 옵션에 대한 자세한 내용은 데이터 액세스 전략을 참조하세요.

시작하기

파이프라인에 복사 작업을 수행하려면 다음 도구 또는 SDK 중 하나를 사용하면 됩니다.

UI를 사용하여 HTTP 원본에 대한 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 HTTP 원본에 대한 연결된 서비스를 만듭니다.

Azure Data Factory 또는 Synapse 작업 영역에서 관리 탭으로 이동하여 연결된 서비스를 선택하고 새로 만들기를 클릭합니다.
- Azure Data Factory
- Azure Synapse
HTTP를 검색하고 HTTP 커넥터를 선택합니다.
서비스 세부 정보를 구성하고, 연결을 테스트하고, 새로운 연결된 서비스를 만듭니다.

커넥터 구성 세부 정보

다음 섹션에서는 HTTP 커넥터에 한정된 엔터티를 정의하는 데 사용되는 속성에 대해 자세히 설명합니다.

연결된 서비스 속성

HTTP 연결된 서비스에 다음 속성이 지원됩니다.

속성	설명	필수
type	type 속성은 HttpServer로 설정해야 합니다.	예
URL	웹 서버의 기본 URL입니다.	예
enableServerCertificateValidation	HTTP 엔드포인트에 연결할 때 서버 TLS/SSL 인증서 유효성 검사를 사용할지 지정합니다. HTTPS 서버에서 자체 서명된 인증서를 사용하는 경우 이 속성을 false로 설정합니다.	아니요 (기본값: true)
authenticationType	인증 유형을 지정합니다. 허용되는 값은 Anonymous, Basic, Digest, Windows 및 ClientCertificate입니다. `authHeader` 속성에서 인증 헤더를 추가로 구성할 수 있습니다. 이러한 인증 형식의 더 많은 속성 및 JSON 샘플은 이 표 뒤의 섹션을 참조하세요.	예
authHeaders	인증을 위한 추가 HTTP 요청 헤더입니다. 예를 들어 API 키 인증을 사용하려면 인증 유형을 “익명”으로 선택하고 헤더에 API 키를 지정할 수 있습니다.	아니요
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 필수 구성 요소 섹션에서 자세히 알아보세요. 지정하지 않으면 기본 Azure Integration Runtime이 사용됩니다.	아니요

Basic, Digest 또는 Windows 인증 사용

authenticationType 속성을 Basic, Digest 또는 Windows로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
userName	HTTP 엔드포인트에 액세스하는 데 사용할 사용자 이름입니다.	예
password	사용자(userName 값)의 암호입니다. 이 필드를 SecureString 형식으로 표시하여 안전하게 저장합니다. Azure Key Vault에 저장된 비밀을 참조할 수도 있습니다.	예

예제

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<HTTP endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

ClientCertificate 인증 사용

ClientCertificate 인증을 사용하려면 authenticationType 속성을 ClientCertificate로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
embeddedCertData	Base64로 인코딩된 인증서 데이터입니다.	embeddedCertData 또는 certThumbprint를 지정합니다.
certThumbprint	자체 호스팅 통합 런타임 머신의 인증서 저장소에 설치된 인증서의 지문입니다. 자체 호스팅 형식의 통합 런타임이 connectVia 속성에 지정된 경우에만 적용됩니다.	embeddedCertData 또는 certThumbprint를 지정합니다.
password	인증서와 연결된 암호입니다. 이 필드를 SecureString 형식으로 표시하여 안전하게 저장합니다. Azure Key Vault에 저장된 비밀을 참조할 수도 있습니다.	아니요

인증에 certThumbprint를 사용하고 인증서가 로컬 컴퓨터의 개인 저장소에 설치된 경우 자체 호스팅 통합 런타임에 읽기 권한을 부여합니다.

MMC(Microsoft Management Console)를 엽니다. 로컬 컴퓨터를 대상으로 하는 인증서 스냅인을 추가합니다.
인증서>개인을 확장한 후 인증서를 선택합니다.
개별 저장소에서 인증서를 마우스 오른쪽 단추로 클릭한 다음, 모든 작업>프라이빗 키 관리를 선택합니다.
보안 탭에서 인증서에 대한 읽기 권한으로 통합 런타임 호스트 서비스(DIAHostService)를 실행 중인 사용자 계정을 추가합니다.
HTTP 커넥터는 신뢰할 수 있는 인증서만 로드합니다. 자체 서명된 인증서 또는 비통합 CA 발급 인증서를 사용하여 트러스트를 사용하도록 설정하는 경우 인증서도 다음 저장소 중 하나에 설치해야 합니다.
- 신뢰할 수 있는 사람
- 타사 루트 인증 기관
- 신뢰할 수 있는 루트 인증 기관

예제 1: certThumbprint 사용

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "certThumbprint": "<thumbprint of certificate>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예제 2: embeddedCertData 사용

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "embeddedCertData": "<Base64-encoded cert data>",
            "password": {
                "type": "SecureString",
                "value": "password of cert"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

인증 헤더 사용

또한, 기본 제공 인증 형식과 함께 인증을 위한 요청 헤더를 구성할 수 있습니다.

예제: API 키 인증 사용

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "url": "<HTTP endpoint>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

데이터 세트 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 데이터 세트 문서를 참조하세요.

Azure Data Factory는 다음과 같은 파일 형식을 지원합니다. 형식 기반 설정에 대한 각 문서를 참조하세요.

형식 기반 데이터 세트의 location 설정에서 HTTP에 다음 속성이 지원됩니다.

속성	설명	필수
type	데이터 세트에 있는 `location` 아래의 type 속성은 HttpServerLocation으로 설정해야 합니다.	예
relativeUrl	데이터를 포함하는 리소스에 대한 상대 URL입니다. HTTP 커넥터가 결합된 URL(`[URL specified in linked service][relative URL specified in dataset]`)에서 데이터를 복사합니다.	아니요

참고 항목

지원되는 HTTP 요청 페이로드 크기는 약 500KB입니다. 웹 엔드포인트에 전달하려는 페이로드 크기가 500KB보다 큰 경우 더 작은 청크로 페이로드를 일괄 처리하는 것이 좋습니다.

예제:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "HttpServerLocation",
                "relativeUrl": "<relative url>"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

복사 활동 속성

이 섹션에서는 HTTP 원본에서 지원하는 속성의 목록을 제공합니다.

작업 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 파이프라인을 참조하세요.

HTTP를 원본으로

Azure Data Factory는 다음과 같은 파일 형식을 지원합니다. 형식 기반 설정에 대한 각 문서를 참조하세요.

형식 기반 복사 원본의 storeSettings 설정에서 HTTP에 다음 속성이 지원됩니다.

속성	설명	필수
type	`storeSettings` 아래의 type 속성은 HttpReadSettings로 설정해야 합니다.	예
requestMethod	HTTP 메서드입니다. 허용되는 값은 Get(기본값) 또는 Post입니다.	아니요
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
requestBody	HTTP 요청의 본문입니다.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 읽는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요
maxConcurrentConnections	작업 실행 중 데이터 저장소에 설정된 동시 연결의 상한입니다. 동시 연결을 제한하려는 경우에만 값을 지정합니다.	아니요

예제:

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "HttpReadSettings",
                    "requestMethod": "Post",
                    "additionalHeaders": "<header key: header value>\n<header key: header value>\n",
                    "requestBody": "<body for POST HTTP request>"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

조회 작업 속성

속성에 대한 자세한 내용을 보려면 조회 작업을 확인하세요.

레거시 모델

참고 항목

다음 모델은 이전 버전과의 호환성을 위해 그대로 계속 지원됩니다. 앞의 섹션에서 설명한 새 모델을 사용하는 것이 좋습니다. 그러면 작성 UI가 새 모델을 생성하도록 전환됩니다.

레거시 데이터 세트 모델

속성	설명	필수
type	데이터 세트의 type 속성을 HttpFile로 설정해야 합니다.	예
relativeUrl	데이터를 포함하는 리소스에 대한 상대 URL입니다. 이 속성을 지정하지 않으면 연결된 서비스 정의에 지정된 URL만 사용됩니다.	아니요
requestMethod	HTTP 메서드입니다. 허용되는 값은 Get(기본값) 또는 Post입니다.	아니요
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
requestBody	HTTP 요청의 본문입니다.	아니요
format	데이터를 구문 분석하지 않고 HTTP 엔드포인트에서 데이터를 있는 그대로 검색하고 파일 기반 저장소에 복사하려면 입력 및 출력 데이터 세트 정의 모두에서 형식 섹션을 건너뜁니다. 복사 중에 HTTP 응답 콘텐츠를 구문 분석하려는 경우 TextFormat, JsonFormat, AvroFormat, OrcFormat 및 ParquetFormat과 같은 파일 형식 유형이 지원됩니다. 형식에서 type 속성을 이러한 값 중 하나로 설정합니다. 자세한 내용은 JSON 형식, 텍스트 형식, Avro 형식, Orc 형식 및 Parquet 형식을 참조하세요.	아니요
압축	데이터에 대한 압축 유형 및 수준을 지정합니다. 자세한 내용은 지원되는 파일 형식 및 압축 코덱을 참조하세요. 지원되는 형식: GZip, Deflate, BZip2 및 ZipDeflate. 지원되는 수준: Optimal 및 Fastest.	아니요

참고 항목

예제 1: Get 메서드(기본값) 사용

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "additionalHeaders": "Connection: keep-alive\nUser-Agent: Mozilla/5.0\n"
        }
    }
}

예제 2: POST 메서드 사용

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "requestMethod": "Post",
            "requestBody": "<body for POST HTTP request>"
        }
    }
}

레거시 복사 작업 원본 모델

속성	설명	필수
type	복사 작업 원본의 type 속성을 HttpSource로 설정해야 합니다.	예
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 읽는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요

예제

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<HTTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "HttpSource",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

복사 작업에서 원본 및 싱크로 지원되는 데이터 저장소의 목록은 지원되는 데이터 저장소 및 형식을 참조하세요.

Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 HTTP 엔드포인트에서 데이터 복사

지원되는 기능

필수 조건

시작하기

UI를 사용하여 HTTP 원본에 대한 연결된 서비스 만들기

커넥터 구성 세부 정보

연결된 서비스 속성

Basic, Digest 또는 Windows 인증 사용

ClientCertificate 인증 사용

인증 헤더 사용

데이터 세트 속성

복사 활동 속성

HTTP를 원본으로

조회 작업 속성

레거시 모델

레거시 데이터 세트 모델

레거시 복사 작업 원본 모델

관련 콘텐츠

추가 리소스