Azure Data Factory를 사용하여 REST 엔드포인트에서 데이터 복사 및 변환

아티클
08/29/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

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

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

REST 커넥터는 특히 RESTful API에서 데이터를 복사하는 것을 지원합니다.
HTTP 커넥터는 파일을 다운로드하는 등의 HTTP 엔드포인트에서 데이터를 검색하는 일반적인 커넥터입니다. 이 REST 커넥터 전에는 HTTP 커넥터를 사용하여 지원은 되지만 REST 커넥터와 비교할 때 기능이 적은 RESTful API에서 데이터를 복사할 수도 있습니다.
웹 테이블 커넥터는 HTML 웹 페이지에서 테이블 콘텐츠를 추출합니다.

지원되는 기능

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

지원되는 기능	IR
복사 작업(원본/싱크)	(1) (2)
매핑 데이터 흐름(원본/싱크)	(1)

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

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

특히 이 일반 REST 커넥터는 다음을 지원합니다.

GET 또는 POST 메서드를 사용하여 데이터를 REST 엔드포인트로 복사하고 Post, PUT 또는 PATCH 메서드를 사용하여 데이터를 복사합니다.
다음 인증 중 하나를 사용하여 데이터 복사합니다. 익명, 기본, 서비스 주체, OAuth2 클라이언트 자격 증명, 시스템 할당됨 관리 ID 및 사용자 할당 관리 ID.
REST API의 페이지 매김
원본인 REST에 REST JSON 응답을 있는 그대로 복사하거나 스키마 매핑을 사용하여 구문 분석합니다. JSON의 응답 페이로드만 지원됩니다.

팁

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

필수 조건

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

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

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

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

시작하기

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

UI를 사용하여 REST 연결된 서비스 만들기

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

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

커넥터 구성 세부 정보

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

연결된 서비스 속성

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

속성	설명	필수
type	형식 속성은 RestService로 설정되어야 합니다.	예
URL	REST 서비스의 기본 URL입니다.	예
enableServerCertificateValidation	엔드포인트에 연결할 때 서버 쪽 TLS/SSL 인증서의 유효성을 검사할지를 나타냅니다.	아니요 (기본값: true)
authenticationType	REST 서비스에 연결하는 데 사용되는 인증 형식입니다. 허용되는 값은 Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential 및 ManagedServiceIdentity입니다. `authHeaders` 속성에서 인증 헤더를 추가로 구성할 수 있습니다. 추가 속성 및 예제를 보려면 아래 해당 섹션을 참조하세요.	예
authHeaders	인증을 위한 추가 HTTP 요청 헤더입니다. 예를 들어 API 키 인증을 사용하려면 인증 유형을 “익명”으로 선택하고 헤더에 API 키를 지정할 수 있습니다.	아니요
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 필수 구성 요소 섹션에서 자세히 알아보세요. 지정하지 않으면 이 속성은 기본 Azure Integration Runtime을 사용합니다.	아니요

다양한 인증 유형에 대한 자세한 내용은 해당 섹션을 참조하세요.

인증 유형
서비스 주체 인증
OAuth2 클라이언트 자격 증명 인증
시스템이 할당한 관리 ID 인증
사용자가 할당한 관리 ID 인증
익명 인증

기본 인증 사용

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

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

예제

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

서비스 주체 인증 사용

authenticationType 속성을 AadServicePrincipal로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
servicePrincipalId	Microsoft Entra 애플리케이션의 클라이언트 ID를 지정합니다.	예
servicePrincipalCredentialType	서비스 주체 인증에 사용할 자격 증명 유형을 지정합니다. 허용되는 값은 `ServicePrincipalKey`와 `ServicePrincipalCert`입니다.	아니요
ServicePrincipalKey의 경우
servicePrincipalKey	Microsoft Entra 애플리케이션의 키를 지정합니다. 이 필드를 SecureString으로 표시하여 Data Factory에 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요
ServicePrincipalCert의 경우
servicePrincipalEmbeddedCert	Microsoft Entra ID에 등록된 애플리케이션의 base64 인코딩 인증서를 지정하고 인증서 콘텐츠 형식이 PKCS #12인지 확인합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다. 이 섹션으로 이동하여 Azure Key Vault에 인증서를 저장하는 방법을 알아봅니다.	아니요
servicePrincipalEmbeddedCertPassword	인증서가 암호로 보호되는 경우 인증서의 암호를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	아니요

테넌트	애플리케이션이 있는 테넌트 정보(도메인 이름 또는 테넌트 ID)를 지정합니다. Azure Portal의 오른쪽 위 모서리를 마우스로 가리켜 검색합니다.	예
aadResourceId	권한 부여를 요청하는 Microsoft Entra 리소스를 지정합니다(예: `https://management.core.windows.net`).	예
azureCloudType	서비스 주체 인증의 경우 Microsoft Entra 애플리케이션이 등록된 Azure 클라우드 환경의 형식을 지정합니다. 허용되는 값은 AzurePublic, AzureChina, AzureUsGovernment, AzureGermany입니다. 기본적으로 데이터 팩터리의 클라우드 환경이 사용됩니다.	아니요

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

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Azure Key Vault에 서비스 주체 인증서 저장

Azure Key Vault에 서비스 주체 인증서를 저장하는 두 가지 옵션이 있습니다.

옵션 1
1. 서비스 주체 인증서를 base64 문자열로 변환합니다. 이 문서에서 자세히 알아보세요.
2. Azure Key Vault에서 base64 문자열을 비밀로 저장합니다.
옵션 2

Azure Key Vault에서 인증서를 다운로드할 수 없는 경우 이 템플릿을 사용하여 변환된 서비스 주체 인증서를 Azure Key Vault에 비밀로 저장할 수 있습니다.

OAuth2 클라이언트 자격 증명 인증 사용

authenticationType 속성을 OAuth2ClientCredential로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
tokenEndpoint	액세스 토큰을 획득할 권한 부여 서버의 토큰 엔드포인트입니다.	예
clientId	애플리케이션과 연결된 클라이언트 ID입니다.	예
clientSecret	애플리케이션과 연결된 클라이언트 암호입니다. 이 필드를 SecureString 형식으로 표시하여 Data Factory에서 안전하게 저장합니다. Azure Key Vault에 저장된 비밀을 참조할 수도 있습니다.	예
scope	필요한 액세스 범위입니다. 어떤 종류의 액세스가 요청될지 설명합니다.	아니요
resource	액세스가 요청될 대상 서비스 또는 리소스입니다.	아니요

예제

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

시스템 할당 관리 ID 인증 사용

authenticationType 속성을 ManagedServiceIdentity로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
aadResourceId	권한 부여를 요청하는 Microsoft Entra 리소스를 지정합니다(예: `https://management.core.windows.net`).	예

예제

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

사용자 할당 관리 ID 인증 사용

authenticationType 속성을 ManagedServiceIdentity로 설정합니다. 앞 섹션에서 설명한 일반 속성 외에 다음 속성을 지정합니다.

속성	설명	필수
aadResourceId	권한 부여를 요청하는 Microsoft Entra 리소스를 지정합니다(예: `https://management.core.windows.net`).	예
credentials	사용자가 할당한 관리 ID를 자격 증명 개체로 지정합니다.	예

예제

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

인증 헤더 사용

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

예제: API 키 인증 사용

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

데이터 세트 속성

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

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

REST의 데이터를 복사하려는 경우 다음과 같은 속성이 지원됩니다.

속성	설명	필수
type	데이터 세트의 type 속성을 RestResource로 설정해야 합니다.	예
relativeUrl	데이터를 포함하는 리소스에 대한 상대 URL입니다. 이 속성을 지정하지 않으면 연결된 서비스 정의에 지정된 URL만 사용됩니다. HTTP 커넥터가 결합된 URL(`[URL specified in linked service]/[relative URL specified in dataset]`)에서 데이터를 복사합니다.	아니요

데이터 세트에서 requestMethod, additionalHeaders, requestBody 및 paginationRules를 설정한 경우 여전히 있는 그대로 지원되지만, 앞으로는 작업에 새 모델을 사용하는 것이 좋습니다.

예제:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

복사 활동 속성

이 섹션에서는 REST 원본 및 싱크에서 지원하는 속성 목록을 제공합니다.

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

REST를 원본으로

복사 작업 source 섹션에서 다음 속성이 지원됩니다.

속성	설명	필수
type	복사 작업 원본의 type 속성은 RestSource로 설정해야 합니다.	예
requestMethod	HTTP 메서드입니다. 허용되는 값은 GET(기본값) 또는 POST입니다.	아니요
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
requestBody	HTTP 요청의 본문입니다.	아니요
paginationRules	다음 페이지 요청을 작성하기 위한 페이지 매김 규칙입니다. 자세한 내용은 페이지 매김 지원을 참조하세요.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 읽는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요
requestInterval	다음 페이지에 대한 요청을 보내기 전에 대기할 시간입니다. 기본값은 00:00:01입니다.	아니요

참고 항목

REST 커넥터는 additionalHeaders에 지정된 "Accept" 헤더를 무시합니다. REST 커넥터는 JSON의 응답만 지원하므로 Accept: application/json의 헤더를 자동으로 생성합니다.
응답 본문인 개체의 배열은 페이지 매김에서 지원되지 않습니다.

예제 1: Get 메서드에서 페이지 매김 사용

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

예제 2: POST 메서드 사용

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

싱크인 REST

복사 작업 sink 섹션에서 다음 속성이 지원됩니다.

속성	설명	필수
type	복사 작업 싱크의 type 속성은 RestSink로 설정해야 합니다.	예
requestMethod	HTTP 메서드입니다. 허용되는 값은 POST(기본값), PUT, PATCH입니다.	아니요
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 쓰는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요
requestInterval	여러 요청 간의 간격 시간(밀리초)입니다. 요청 간격 값은 [10, 60000] 사이의 숫자여야 합니다.	아니요
httpCompressionType	최적의 압축 수준으로 데이터를 전송하는 동안 사용할 HTTP 압축 형식. 허용되는 값은 none 및 gzip입니다.	아니요
writeBatchSize	일괄 처리당 REST 싱크에 쓸 레코드 수입니다. 기본값은 10000입니다.	아니요

싱크인 REST 커넥터는 JSON을 허용하는 REST API와 함께 작동합니다. 데이터는 다음 패턴을 사용하여 JSON으로 전송됩니다. 필요에 따라 복사 작업인 스키마 매핑을 사용하여 REST API에서 필요한 페이로드를 따르도록 원본 데이터의 모양을 변경할 수 있습니다.

[
    { <data object> },
    { <data object> },
    ...
]

예제:

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

매핑 데이터 흐름 속성

REST는 통합 데이터 세트와 인라인 데이터 세트 모두에 대한 데이터 흐름에서 지원됩니다.

원본 변환

속성	설명	필수
requestMethod	HTTP 메서드입니다. 허용되는 값은 GET 및 POST입니다.	예
relativeUrl	데이터를 포함하는 리소스에 대한 상대 URL입니다. 이 속성을 지정하지 않으면 연결된 서비스 정의에 지정된 URL만 사용됩니다. HTTP 커넥터가 결합된 URL(`[URL specified in linked service]/[relative URL specified in dataset]`)에서 데이터를 복사합니다.	아니요
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 쓰는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요
requestInterval	여러 요청 간의 간격 시간(밀리초)입니다. 요청 간격 값은 [10, 60000] 사이의 숫자여야 합니다.	아니요
QueryParameters.request_query_parameter OR QueryParameters['request_query_parameter']	"request_query_parameter"는 다음 HTTP 요청 URL에 있는 하나의 쿼리 매개 변수 이름을 참조하는 사용자 정의 항목입니다.	아니요

싱크 변환

속성	설명	필수
additionalHeaders	추가 HTTP 요청 헤더입니다.	아니요
httpRequestTimeout	HTTP 요청이 응답을 받을 시간 제한(TimeSpan 값)입니다. 이 값은 응답 데이터를 쓰는 시간 제한이 아니라, 응답을 받을 시간 제한입니다. 기본값은 00:01:40입니다.	아니요
requestInterval	여러 요청 간의 간격 시간(밀리초)입니다. 요청 간격 값은 [10, 60000] 사이의 숫자여야 합니다.	아니요
httpCompressionType	최적의 압축 수준으로 데이터를 전송하는 동안 사용할 HTTP 압축 형식. 허용되는 값은 none 및 gzip입니다.	아니요
writeBatchSize	일괄 처리당 REST 싱크에 쓸 레코드 수입니다. 기본값은 10000입니다.	아니요

CRUD 작업을 위해 REST 싱크로 보낼 상대 행 데이터와 함께 delete, insert, update 및 upsert 메서드를 설정할 수 있습니다.

데이터 흐름 REST 싱크

샘플 데이터 흐름 스크립트

싱크 이전에 행 변경 변환을 사용하여 ADF에 REST 싱크로 수행할 작업 유형을 알려 줍니다. 즉. insert, update, upsert, delete.

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

페이지 매김 지원

REST API에서 데이터를 복사할 때 일반적으로 REST API는 단일 요청의 응답 페이로드 크기를 적절한 수치로 제한합니다. 대량의 데이터를 반환하려는 경우 결과를 여러 페이지로 분할하고 호출자에게 연속 요청을 전송하여 결과의 다음 페이지를 가져오도록 요구합니다. 보통 한 페이지에 대한 요청은 동적이고 이전 페이지의 응답에서 반환된 정보로 구성됩니다.

이 일반 REST 커넥터는 다음 페이지 매김 패턴을 지원합니다.

다음 요청의 절대 URL 또는 상대 URL = 현재 응답 본문의 속성 값
다음 요청의 절대 URL 또는 상대 URL = 현재 응답 헤더의 헤더 값
다음 요청의 쿼리 매개 변수 = 현재 응답 본문의 속성 값
다음 요청의 쿼리 매개 변수 = 현재 응답 헤더의 헤더 값
다음 요청의 헤더 = 현재 응답 본문의 속성 값
다음 요청의 헤더 = 현재 응답 헤더의 헤더 값

페이지 매김 규칙은 하나 이상의 대/소문자 구분 키-값 쌍을 포함하는 데이터 세트의 사전으로 정의됩니다. 이 구성은 두 번째 페이지에서 시작하는 요청을 생성하는 데 사용됩니다. 커넥터는 HTTP 상태 코드 204(콘텐츠 없음)를 가져오거나 "paginationRules"의 JSONPath 식 중 하나가 null을 반환하면 반복을 중지합니다.

페이지 매김 규칙의 지원되는 키는 다음과 같습니다.

키	설명
AbsoluteUrl	다음 요청을 실행할 URL을 나타냅니다. 절대 URL 또는 상대 URL일 수 있습니다.
QueryParameters.request_query_parameter OR QueryParameters['request_query_parameter']	"request_query_parameter"는 다음 HTTP 요청 URL에 있는 하나의 쿼리 매개 변수 이름을 참조하는 사용자 정의 항목입니다.
Headers.request_header OR Headers['request_header']	"request_header"는 다음 HTTP 요청에 있는 하나의 헤더 이름을 참조하는 사용자 정의 항목입니다.
EndCondition:end_condition	"end_condition"은 사용자 정의되며 다음 HTTP 요청에서 페이지 매김 루프를 종료할 조건을 나타냅니다.
MaxRequestNumber	최대 페이지 매김 요청 수를 나타냅니다. 비워 두면 제한이 없음을 의미합니다.
SupportRFC5988	기본적으로 페이지 매김 규칙이 정의되지 않은 경우 true로 설정됩니다. `supportRFC5988`을 false로 설정하여 이 규칙을 사용하지 않도록 설정하거나 스크립트에서 이 속성을 제거할 수 있습니다.

페이지 매김 규칙의 지원되는 값은 다음과 같습니다.

값	설명
Headers.response_header OR Headers['response_header']	"response_header"는 현재 HTTP 요청에 있는 하나의 헤더 이름을 참조하는 사용자 정의 항목으로, 다음에 요청할 때 해당 값이 사용됩니다.
"$"(응답 본문의 루트를 나타냄)로 시작하는 JSONPath 식	응답 본문에는 하나의 JSON 개체만 포함되어야 하며 응답 본문으로서의 object 배열은 지원되지 않습니다. JSONPath 식은 다음 요청을 실행하는 데 사용되는 단일 기본 값을 반환해야 합니다.

참고 항목

데이터 흐름 매핑의 페이지 매김 규칙은 다음 측면에서 복사 작업의 페이지 매김 규칙과 다릅니다.

데이터 흐름 매핑에서는 범위가 지원되지 않습니다.
['']는 데이터 흐름 매핑에서 지원되지 않습니다. 대신 {}를 사용하여 특수 문자를 이스케이프합니다. 예를 들어, JSON 노드 @odata.nextLink에 특수 문자 .이 포함된 body.{@odata.nextLink}입니다.
종료 조건은 매핑 데이터 흐름에서 지원되지만 조건 구문은 복사 작업에서 다릅니다. body는 $ 대신 응답 본문을 나타내는 데 사용됩니다. header는 headers 대신 응답 헤더를 나타내는 데 사용됩니다. 다음은 이 차이를 보여 주는 두 가지 예입니다.
- 예제 1:
  복사 작업: "EndCondition:$.data": "Empty"
  데이터 흐름 매핑: "EndCondition:body.data": "Empty"
- 예 2:
  복사 작업: "EndCondition:headers.complete": "Exist"
  데이터 흐름 매핑: "EndCondition:header.complete": "Exist"

페이지 매김 규칙 예

이 섹션에서는 페이지 매김 규칙 설정에 대한 예제 목록을 제공합니다.

예제 1: QueryParameters의 변수

이 예에서는 QueryParameters에 변수가 있는 여러 요청을 보내는 구성 단계를 제공합니다.

여러 요청:

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

1단계: 다음 스크린샷과 같이 기준 URL 또는 상대 URL에 sysparm_offset={offset}을 입력합니다:

쿼리 매개 변수에 변수가 있는 여러 요청을 보내기 위한 한 가지 구성을 보여 주는 스크린샷.

또는

쿼리 매개 변수에 변수가 있는 여러 요청을 보내기 위한 다른 구성을 보여 주는 스크린샷.

2단계: 페이지 매김 규칙을 옵션 1 또는 옵션 2로 설정합니다:

옵션1: "QueryParameters.{offset}" : "RANGE:0:10000:1000"
옵션2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

예제 2: AbsoluteUrl의 변수

이 예제에서는 변수가 AbsoluteUrl에 있는 여러 요청을 보내는 구성 단계를 제공합니다.

여러 요청:

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

1단계: 연결된 서비스 구성 페이지의 기준 URL 또는 데이터 세트 연결 창의 상대 URL에 {id}를 입력합니다.

절대 URL에 변수가 있는 여러 요청을 보내기 위한 한 가지 구성을 보여 주는 스크린샷l.

또는

절대 URL에 변수가 있는 여러 요청을 보내기 위한 다른 구성을 보여 주는 스크린샷.

2단계: 페이지 매김 규칙을 "AbsoluteUrl.{id}":"RANGE:1:100:1"로 설정합니다.

예제 3: 헤더의 변수

이 예제에서는 변수가 헤더에 있는 여러 요청을 보내는 구성 단계를 제공합니다.

여러 요청:
RequestUrl: https://example/table
요청 1: Header(id->0)
요청 2: Header(id->10)
......
요청 100: Header(id->100)

1단계: 추가 헤더에 {id}를 입력합니다.

2단계: 페이지 매김 규칙을 "Headers.{id}": "RANGE:0:100:10"으로 설정합니다.

헤더에 변수가 있는 여러 요청을 보내기 위한 페이지 매김 규칙을 보여 주는 스크린샷.

예제 4: 변수가 AbsoluteUrl/QueryParameters/Headers에 있고 종료 변수는 미리 정의되지 않고 종료 조건은 응답을 기반으로 합니다.

이 예제에서는 변수가 AbsoluteUrl/QueryParameters/Headers에 있지만 끝 변수가 정의되지 않은 여러 요청을 보내는 구성 단계를 제공합니다. 다른 응답에 대해 다른 종료 조건 규칙 설정이 예제 4.1-4.6에 나와 있습니다.

여러 요청:

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
......

이 예에서 두 가지 응답이 발생했습니다.

응답 1:

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

응답 2:

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

1단계: 페이지 매김 규칙 범위를 예 1로 설정하고 범위 끝을 "AbsoluteUrl.{offset}": "RANGE:0::1000"으로 비워 둡니다.

2단계: 다른 마지막 응답에 따라 다른 종료 조건 규칙을 설정합니다. 아래 예제를 참조하세요.

예제 4.1: 응답의 특정 노드 값이 비어 있으면 페이지 매김이 종료됩니다.

REST API는 다음 구조로 마지막 응답을 반환합니다.
```
{
    Data: []
}
```
응답의 특정 노드 값이 비어 있을 때 페이지 매김을 끝내려면 종료 조건 규칙을 "EndCondition:$.data": "Empty"로 설정합니다.
예제 4.2: 응답의 특정 노드 값이 존재하지 않을 때 페이지 매김이 종료됨

REST API는 다음 구조로 마지막 응답을 반환합니다.
```
{}
```
응답의 특정 노드 값이 존재하지 않을 때 페이지 매김을 끝내려면 종료 조건 규칙을 "EndCondition:$.data": "NonExist"로 설정합니다.
예제 4.3: 응답의 특정 노드 값이 존재하면 페이지 매김이 종료됩니다.

REST API는 다음 구조로 마지막 응답을 반환합니다.
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
응답의 특정 노드 값이 존재할 때 페이지 매김을 끝내려면 종료 조건 규칙을 "EndCondition:$.Complete": "Exist"로 설정합니다.
예제 4.4: 응답의 특정 노드 값이 사용자 정의 const 값이면 페이지 매김이 종료됩니다.

REST API는 다음 구조로 응답을 반환합니다.
```
{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}
```
......

그리고 마지막 응답은 다음 구조로 되어 있습니다.
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
응답의 특정 노드 값이 사용자 정의 const 값일 때 페이지 매김을 끝내려면 종료 조건 규칙을 "EndCondition:$.Complete": "Const:true"로 설정합니다.
예제 4.5: 응답의 헤더 키 값이 사용자 정의 const 값과 같을 때 페이지 매김이 종료됩니다.

REST API 응답의 헤더 키는 아래 구조로 표시됩니다.

응답 헤더 1: header(Complete->0)
......
마지막 응답 헤더: header(Complete->1)

응답의 헤더 키 값이 사용자 정의 const 값과 같을 때 페이지 매김을 종료하려면 종료 조건 규칙을 "EndCondition:headers.Complete": "Const:1"로 설정합니다.
예제 4.6: 응답 헤더에 키가 있으면 페이지 매김이 종료됩니다.

REST API 응답의 헤더 키는 아래 구조로 표시됩니다.

응답 헤더 1: header()
......
마지막 응답 헤더: header(CompleteTime->20220920)

응답 헤더에 키가 있을 때 페이지 매김을 종료하려면 종료 조건 규칙을 "EndCondition:headers.CompleteTime": "Exist"로 설정합니다.

예제 5: 범위 규칙이 정의되지 않은 경우 끝없는 요청을 피하기 위해 종료 조건 설정

이 예제에서는 범위 규칙을 사용하지 않을 때 여러 요청을 보내는 구성 단계를 제공합니다. 끝 조건은 끝없는 요청을 피하기 위해 예제 4.1-4.6을 참조하여 설정할 수 있습니다. REST API는 다음 구조로 응답을 반환하며, 이 경우 다음 페이지의 URL은 paging.next에 표시됩니다.

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

마지막 응답은 다음과 같습니다.

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

1단계: 페이지 매김 규칙을 "AbsoluteUrl": "$.paging.next"로 설정합니다.

2단계: 마지막 응답의 next가 항상 마지막 요청 URL과 동일하고 비어 있지 않으면 끝없는 요청이 전송됩니다. 끝 조건은 끝없는 요청을 방지하는 데 사용할 수 있습니다. 따라서 예제 4.1-4.6을 참조하여 종료 조건 규칙을 설정합니다.

예제 6：무한 요청을 피하기 위해 최대 요청 수 설정

다음 스크린샷과 같이 끝없는 요청을 방지하려면 MaxRequestNumber를 설정합니다.

예제 6의 최대 요청 수 설정을 보여 주는 스크린샷.

예제 7: 기본적으로 RFC 5988 페이지 매김 규칙이 지원됩니다.

백 엔드는 헤더의 RFC 5988 스타일 링크를 기반으로 다음 URL을 자동으로 가져옵니다.

R F C 5988와 호환되는 http 헤더의 샘플을 보여 주는 스크린샷.

팁

이 기본 페이지 매김 규칙을 사용하지 않으려면 supportRFC5988을 false로 설정하거나 스크립트에서 삭제하면 됩니다.

예제 7의 R F C 5988 설정을 사용할 수 없도록 하는 방법을 보여 주는 스크린샷.

예제 8a: 매핑 데이터 흐름에서 페이지 매김을 사용하는 경우 다음 요청 URL은 응답 본문에 있습니다.

이 예에서는 다음 요청 URL이 응답 본문에서 오는 경우 매핑 데이터 흐름에서 페이지 매김 규칙 및 종료 조건 규칙을 설정하는 방법을 설명합니다.

응답 스키마는 다음과 같습니다.

예제 8의 응답 스미카를 보여 주는 스크린샷.

페이지 매김 규칙은 다음 스크린샷과 같이 설정해야 합니다.

예제 8의 페이지 매김 규칙 설정 방법을 보여 주는 스크린샷.

기본적으로 body.{@odata.nextLink}**가 null이거나 비어 있으면 페이지 매김이 중지됩니다.

그러나 마지막 응답 본문의 @odata.nextLink 값이 마지막 요청 URL과 같으면 무한 루프가 발생합니다. 이 조건을 방지하려면 종료 조건 규칙을 정의합니다.

마지막 응답의 값이 비어 있음이면 종료 조건 규칙을 아래와 같이 설정할 수 있습니다.
응답 헤더의 전체 키 값이 true와 같으면 페이지 매김의 끝을 나타내는 경우 종료 조건 규칙은 다음과 같이 설정할 수 있습니다.

예제 8b: 복사 작업에서 페이지 매김을 사용하는 경우 다음 요청 URL이 응답 본문에 있습니다.

이 예제에서는 다음 요청 URL이 응답 본문 내에 포함될 때 복사 작업에서 페이지 매김 규칙을 설정하는 방법을 보여 줍니다.

응답 스키마는 다음과 같습니다.

예제 8b의 응답 스키마를 보여 주는 스크린샷

페이지 매김 규칙은 다음 스크린샷과 같이 설정해야 합니다.

예제 8b에 대한 페이지 매김 규칙을 설정하는 방법을 보여 주는 스크린샷

예제 9: 응답 형식은 XML이고 다음 요청 URL은 매핑 데이터 흐름에서 페이지 매김을 사용할 때 응답 본문에서 가져옵니다.

이 예제에서는 응답 형식이 XML이고 다음 요청 URL이 응답 본문에서 온 경우 매핑 데이터 흐름에서 페이지 매김 규칙을 설정하는 방법을 설명합니다. 다음 스크린샷과 같이 첫 번째 URL은 https://<user>.dfs.core.windows.NET/bugfix/test/movie_1.xml입니다.

응답 형식이 X M L이고 다음 요청 U R L이 응답 본문에서 가져온 것임을 보여 주는 스크린샷.

응답 스키마는 다음과 같습니다.

예제 9의 응답 스키마를 보여 주는 스크린샷.

페이지 매김 규칙 구문은 예제 8과 동일하며 이 예제에서 아래와 같이 설정해야 합니다.

예제 9의 페이지 매김 규칙의 설정을 보여 주는 스크린샷.

JSON 응답을 있는 그대로 내보내기

이 REST 커넥터를 사용하여 REST API JSON 응답을 다양한 파일 기반 저장소에 있는 그대로 내보낼 수 있습니다. 이러한 스키마 독립적 복사를 완수하려면 데이터 세트 및 복사 작업의 스키마 매핑에서 "구조"(스키마라고도 함) 섹션을 건너뛰세요.

스키마 매핑

데이터를 REST 엔드포인트에서 테이블 형식 싱크로 복사하려면 스키마 매핑을 참조하세요.

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

다음을 통해 공유

Azure Data Factory를 사용하여 REST 엔드포인트에서 데이터 복사 및 변환

지원되는 기능

필수 조건

시작하기

UI를 사용하여 REST 연결된 서비스 만들기

커넥터 구성 세부 정보

연결된 서비스 속성

기본 인증 사용

서비스 주체 인증 사용

Azure Key Vault에 서비스 주체 인증서 저장

OAuth2 클라이언트 자격 증명 인증 사용

시스템 할당 관리 ID 인증 사용

사용자 할당 관리 ID 인증 사용

인증 헤더 사용

데이터 세트 속성

복사 활동 속성

REST를 원본으로

싱크인 REST

매핑 데이터 흐름 속성

원본 변환

싱크 변환

샘플 데이터 흐름 스크립트

예제 1: QueryParameters의 변수

예제 2: AbsoluteUrl의 변수

예제 3: 헤더의 변수

예제 4: 변수가 AbsoluteUrl/QueryParameters/Headers에 있고 종료 변수는 미리 정의되지 않고 종료 조건은 응답을 기반으로 합니다.

예제 5: 범위 규칙이 정의되지 않은 경우 끝없는 요청을 피하기 위해 종료 조건 설정

예제 6：무한 요청을 피하기 위해 최대 요청 수 설정

JSON 응답을 있는 그대로 내보내기

스키마 매핑

피드백

추가 리소스

다음을 통해 공유

Azure Data Factory를 사용하여 REST 엔드포인트에서 데이터 복사 및 변환

지원되는 기능

필수 조건

시작하기

UI를 사용하여 REST 연결된 서비스 만들기

커넥터 구성 세부 정보

연결된 서비스 속성

기본 인증 사용

서비스 주체 인증 사용

Azure Key Vault에 서비스 주체 인증서 저장

OAuth2 클라이언트 자격 증명 인증 사용

시스템 할당 관리 ID 인증 사용

사용자 할당 관리 ID 인증 사용

인증 헤더 사용

데이터 세트 속성

복사 활동 속성

REST를 원본으로

싱크인 REST

매핑 데이터 흐름 속성

원본 변환

싱크 변환

샘플 데이터 흐름 스크립트

페이지 매김 지원

페이지 매김 규칙 예

예제 1: QueryParameters의 변수

예제 2: AbsoluteUrl의 변수

예제 3: 헤더의 변수

예제 4: 변수가 AbsoluteUrl/QueryParameters/Headers에 있고 종료 변수는 미리 정의되지 않고 종료 조건은 응답을 기반으로 합니다.

예제 5: 범위 규칙이 정의되지 않은 경우 끝없는 요청을 피하기 위해 종료 조건 설정

예제 6：무한 요청을 피하기 위해 최대 요청 수 설정

예제 7: 기본적으로 RFC 5988 페이지 매김 규칙이 지원됩니다.

예제 8a: 매핑 데이터 흐름에서 페이지 매김을 사용하는 경우 다음 요청 URL은 응답 본문에 있습니다.

예제 8b: 복사 작업에서 페이지 매김을 사용하는 경우 다음 요청 URL이 응답 본문에 있습니다.

예제 9: 응답 형식은 XML이고 다음 요청 URL은 매핑 데이터 흐름에서 페이지 매김을 사용할 때 응답 본문에서 가져옵니다.

JSON 응답을 있는 그대로 내보내기

스키마 매핑

관련 콘텐츠

피드백

추가 리소스