Azure Data Factory 또는 Synapse Analytics를 사용하여 OData 원본에서 데이터 복사

아티클
02/25/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

이 문서에서는 Azure Data Factory 또는 Synapse Analytics 파이프라인에서 복사 작업을 사용하여 OData 원본에서 데이터를 복사하는 방법을 간략하게 설명합니다. 이 문서는 복사 작업에 대한 일반적인 개요를 제공하는 복사 작업을 기준으로 합니다.

지원되는 기능

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

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

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

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

특히 이 OData 커넥터는 다음을 지원합니다.

OData 버전 2.0, 3.0 및 4.0
익명, 기본, Windows 및 Microsoft Entra 서비스 주체 인증 중 하나를 사용하여 데이터를 복사합니다.

필수 조건

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

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

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

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

시작하기

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

UI를 사용하여 OData 저장소에 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 OData 저장소에 연결된 서비스를 만듭니다.

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

커넥터 구성 세부 정보

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

연결된 서비스 속성

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

속성	설명	필수
type	형식 속성은 OData로 설정해야 합니다.	예
URL	OData 서비스의 루트 URL입니다.	예
authenticationType	OData 원본에 연결하는 데 사용되는 인증 형식입니다. 허용되는 값은 익명, 기본, Windows, AadServicePrincipal입니다. 사용자 기반 OAuth는 지원되지 않습니다. `authHeader` 속성에서 인증 헤더를 추가로 구성할 수 있습니다.	예
authHeaders	인증을 위한 추가 HTTP 요청 헤더입니다. 예를 들어 API 키 인증을 사용하려면 인증 유형을 “익명”으로 선택하고 헤더에 API 키를 지정할 수 있습니다.	아니요
userName	Basic 또는 Windows 인증을 사용할 경우 userName을 지정합니다.	아니요
password	userName에 지정한 사용자 계정의 password를 지정합니다. 이 필드를 SecureString 형식으로 표시하여 안전하게 저장합니다. 또한 Azure Key Vault에 저장된 비밀을 참조할 수도 있습니다.	아니요
servicePrincipalId	Microsoft Entra 애플리케이션의 클라이언트 ID를 지정합니다.	아니요
aadServicePrincipalCredentialType	서비스 주체 인증에 사용할 자격 증명 유형을 지정합니다. 허용되는 값은 `ServicePrincipalKey` 또는 `ServicePrincipalCert`입니다.	아니요
servicePrincipalKey	Microsoft Entra 애플리케이션의 키를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요
servicePrincipalEmbeddedCert	Microsoft Entra ID에 등록된 애플리케이션의 base64 인코딩 인증서를 지정하고 인증서 콘텐츠 형식이 PKCS #12인지 확인합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요
servicePrincipalEmbeddedCertPassword	인증서가 암호로 보호되는 경우 인증서의 암호를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요
테넌트	애플리케이션이 있는 테넌트 정보(도메인 이름 또는 테넌트 ID)를 지정합니다. Azure Portal의 오른쪽 위 모서리를 마우스로 가리켜 검색합니다.	아니요
aadResourceId	권한 부여를 요청하는 Microsoft Entra 리소스를 지정합니다.	아니요
azureCloudType	서비스 주체 인증의 경우 Microsoft Entra 애플리케이션이 등록된 Azure 클라우드 환경의 형식을 지정합니다. 허용되는 값은 AzurePublic, AzureChina, AzureUsGovernment, AzureGermany입니다. 기본적으로 이 서비스의 클라우드 환경이 사용됩니다.	아니요
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 필수 구성 요소 섹션에서 자세히 알아보세요. 지정하지 않으면 기본 Azure Integration Runtime이 사용됩니다.	아니요

예제 1: 익명 인증 사용

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "https://services.odata.org/OData/OData.svc",
            "authenticationType": "Anonymous"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예제 2: 기본 인증 사용

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

예제 3: Windows 인증 사용

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Windows",
            "userName": "<domain>\\<user>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

예제 4: 서비스 주체 키 인증 사용

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource URL>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

예제 5: 서비스 주체 인증서 인증 사용

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource e.g. https://tenant.sharepoint.com>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

예제 6: API 키 인증 사용

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "APIKey": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

이 섹션에서는 OData 데이터 세트에서 지원하는 속성의 목록을 제공합니다.

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

OData에서 데이터를 복사하려면 데이터 세트의 type 속성을 ODataResource로 설정합니다. 다음과 같은 속성이 지원됩니다.

속성	설명	필수
type	데이터 세트의 type 속성을 ODataResource로 설정해야 합니다.	예
경로	OData 리소스에 대한 경로입니다.	예

예제

{
    "name": "ODataDataset",
    "properties":
    {
        "type": "ODataResource",
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<OData linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "path": "Products"
        }
    }
}

복사 활동 속성

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

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

OData를 원본으로

OData에서 데이터를 복사하기 위해 복사 작업의 source 섹션에서 지원되는 속성은 다음과 같습니다.

속성	설명	필수
type	복사 작업 source 섹션의 type 속성은 ODataSource로 설정해야 합니다.	예
query	데이터 필터링에 대한 OData 쿼리 옵션입니다. 예: `"$select=Name,Description&$top=5"` 참고: OData 커넥터가 결합된 URL(`[URL specified in linked service]/[path specified in dataset]?[query specified in copy activity source]`)에서 데이터를 복사합니다. 자세한 내용은 OData URL 구성 요소를 참조하세요.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 읽는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 지정하지 않으면 기본값은 00:30:00(30분)입니다.	아니요

예제

"activities":[
    {
        "name": "CopyFromOData",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<OData input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ODataSource",
                "query": "$select=Name,Description&$top=5"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

RelationalSource 형식의 원본을 사용하고 있는 경우 현재까지 지원되지만 앞으로는 새 형식을 사용하는 것이 좋습니다.

OData에 대한 데이터 형식 매핑

OData에서 데이터를 복사할 때 서비스 내부에서 사용되는 OData 데이터 형식과 중간 데이터 형식 사이에서 다음 매핑이 사용됩니다. 복사 작업에서 원본 스키마 및 데이터 형식을 싱크에 매핑하는 방법을 알아보려면 스키마 및 데이터 형식 매핑을 참조하세요.

OData 데이터 형식	중간 서비스 데이터 형식
Edm.Binary	Byte[]
Edm.Boolean	Bool
Edm.Byte	Byte[]
Edm.DateTime	DateTime
Edm.Decimal	소수
Edm.Double	두 배
Edm.Single	단일
Edm.Guid	GUID
Edm.Int16	Int16
Edm.Int32	Int32
Edm.Int64	Int64
Edm.SByte	Int16
Edm.String	문자열
Edm.Time	TimeSpan
Edm.DateTimeOffset	DateTimeOffset

참고 항목

OData 복합 데이터 형식(예: Object)은 지원되지 않습니다.

Project Online에서 데이터 복사

Project Online에는 Azure Data Factory에서 지원되지 않는 사용자 기반 OAuth가 필요합니다. Project Online에서 데이터를 복사하려면 OData 커넥터와 Postman과 같은 도구에서 얻은 액세스 토큰을 사용하면 됩니다.

주의

액세스 토큰은 기본적으로 1시간 후에 만료되며, 만료되면 새 액세스 토큰을 받아야 합니다.

Postman을 사용하여 액세스 토큰을 가져옵니다.
1. Postman 웹 사이트의 권한 부여 탭으로 이동합니다.
2. 형식 상자에서 OAuth 2.0을 선택하고 Add authorization data to(권한 부여 데이터 추가 대상) 상자에서 요청 헤더를 선택합니다.
3. 새 액세스 토큰을 가져오려면 Configure New Token(새 토큰 구성) 페이지에 다음 정보를 입력합니다.
  - 권한 부여 유형: 인증 코드를 선택합니다.
  - 콜백 URL: https://www.localhost.com/을 입력합니다.
  - Auth URL(인증 URL): https://login.microsoftonline.com/common/oauth2/authorize?resource=https://<your tenant name>.sharepoint.com을 입력합니다. <your tenant name>을 사용자 고유의 테넌트 이름으로 바꿉니다.
  - Access Token URL(액세스 토큰 URL): https://login.microsoftonline.com/common/oauth2/token을 입력합니다.
  - 클라이언트 ID: Microsoft Entra 서비스 주체 ID를 입력합니다.
  - 클라이언트 암호: 서비스 주체 비밀을 입력합니다.
  - 클라이언트 인증: Send as Basic Auth header(기본 인증 헤더로 보내기)를 선택합니다.
4. 사용자 이름 및 암호를 사용하여 로그인하라는 메시지가 표시됩니다.
5. 액세스 토큰을 가져오면 다음 단계를 위해 토큰을 복사하여 저장하세요.
OData 연결된 서비스 만들기:
- 서비스 URL: https://<your tenant name>.sharepoint.com/sites/pwa/_api/Projectdata를 입력합니다. <your tenant name>을 사용자 고유의 테넌트 이름으로 바꿉니다.
- 인증 형식: Anonymous를 선택합니다.
- 인증 헤더:
  - 속성 이름: Authorization을 선택합니다.
  - 값: Bearer <access token from step 1>을 입력합니다.
- 연결된 서비스 테스트
OData 데이터 세트 만들기:
1. 2 단계에서 만든 OData 연결된 서비스를 사용하여 데이터 세트를 만듭니다.
2. 데이터 미리 보기

조회 작업 속성

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

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