Azure Data Factory 및 Azure Synapse Analytics의 웹 작업

아티클
09/25/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

웹 활동은 Azure Data Factory 또는 Synapse 파이프라인에서 사용자 지정 REST 엔드포인트를 호출하는 데 사용할 수 있습니다. 작업에서 사용하고 액세스하도록 데이터 세트 및 연결된 서비스를 전달할 수 있습니다.

참고 항목

웹 작업은 자체 호스팅 통합 런타임을 활용하여 프라이빗 가상 네트워크에서 호스트되는 URL을 호출하는 경우에도 지원됩니다. 통합 런타임에서 URL 엔드포인트를 직접 확인할 수 있어야 합니다.

참고 항목

지원되는 최대 출력 응답 페이로드 크기는 4MB입니다.

UI를 사용하여 웹 작업 만들기

파이프라인에서 웹 작업을 사용하려면 다음 단계를 완료합니다.

파이프라인 작업 창에서 웹을 검색하고 웹 작업을 파이프라인 캔버스로 끕니다.
아직 선택하지 않은 경우 캔버스에서 새 웹 작업 및 해당 설정 탭을 선택하여 세부 정보를 편집합니다.
리터럴 URL 문자열이거나 동적 식, 함수, 시스템 변수 또는 다른 작업의 출력의 조합일 수 있는 URL을 지정합니다. 요청과 함께 제출할 다른 세부 정보를 제공합니다.
활동의 출력을 다른 활동에 대한 입력으로 사용하고 대상 활동에서 동적 콘텐츠가 지원되는 모든 위치에서 출력을 참조합니다.

구문

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

형식 속성

속성	설명	허용된 값	필수
name	웹 작업의 이름입니다.	문자열	예
type	WebActivity로 설정해야 합니다.	문자열	예
메서드(method)	대상 엔드포인트에 대한 REST API 메서드입니다.	문자열입니다. 지원되는 형식: "GET", "POST", "PUT", "PATCH", "DELETE"	예
URL	대상 엔드포인트 및 경로입니다.	문자열(또는 resultType 문자열이 있는 식). 활동이 엔드포인트에서 응답을 수신하지 않는 경우 오류가 발생하여 1분에 시간이 초과됩니다. httpRequestTimeout 속성을 업데이트하여 이 응답 시간 제한을 최대 10분까지 늘릴 수 있습니다.	예
httpRequestTimeout	응답 시간 제한 기간	최댓값이 00:10:00인 hh:mm:ss입니다. 명시적으로 지정하지 않은 경우 기본값은 00:01:00입니다.	아니요
헤더	요청에 전송되는 헤더입니다. 예를 들어 요청에 언어 및 형식을 설정하려면 다음과 같이 합니다. `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`	문자열(또는 resultType 문자열이 있는 식)	아니요
본문	엔드포인트에 전송된 페이로드를 나타냅니다.	문자열(또는 resultType 문자열이 있는 식). 요청 페이로드 스키마 섹션에서 요청 페이로드의 스키마를 참조하세요.	POST/PUT/PATCH 메서드에 필요합니다. DELETE 메서드의 경우 선택 사항입니다.
authentication	엔드포인트를 호출하는 데 사용되는 인증 방법입니다. 지원되는 형식은 "기본, 클라이언트 인증서, 시스템 할당 관리 ID, 사용자 할당 관리 ID, 서비스 주체"입니다. 자세한 내용은 인증 섹션을 참조하세요. 인증이 필요 없는 경우 이 속성을 제외합니다.	문자열(또는 resultType 문자열이 있는 식)	아니요
turnOffAsync	HTTP 202 응답의 응답 헤더에 있는 위치 필드에서 HTTP GET 호출을 사용하지 않도록 설정하는 옵션입니다. true로 설정하면 응답 헤더에 지정된 http 위치에서 HTTP GET 호출을 중지합니다. false로 설정하면 http 응답 헤더에 지정된 위치에서 HTTP GET 호출을 계속 호출합니다.	허용되는 값은 false(기본값) 및 true입니다.	아니요
disableCertValidation	서버 쪽 인증서 유효성 검사를 제거합니다(표준 CA 인증서를 사용하지 않는 신뢰할 수 있는 서버에 연결하지 않는 한 권장하지 않음).	허용되는 값은 false(기본값) 및 true입니다.	아니요
datasets	엔드포인트에 전달되는 데이터 세트의 목록입니다.	데이터 세트 참조의 배열입니다. 빈 배열일 수 있습니다.	예
linkedServices	엔드포인트에 전달되는 연결된 서비스 목록입니다.	연결된 서비스 참조의 배열입니다. 빈 배열일 수 있습니다.	예
connectVia	데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. Azure 통합 런타임 또는 자체 호스팅 통합 런타임(데이터 저장소가 프라이빗 네트워크에 있는 경우)을 사용할 수 있습니다. 해당 속성을 지정하지 않으면 서비스는 기본 Azure 통합 런타임을 사용합니다.	통합 런타임 참조입니다.	아니요

참고 항목

웹 작업이 호출하는 REST 엔드포인트는 JSON 형식의 응답을 반환해야 합니다. 활동이 엔드포인트에서 응답을 수신하지 않는 경우 오류가 발생하여 1분에 시간이 초과됩니다. 비동기 요청-회신 패턴을 지원하는 엔드포인트의 경우 웹 작업은 시간 초과 없이(최대 7일) 또는 엔드포인트에서 작업 완료 신호를 보낼 때까지 계속 대기합니다.

다음 표에서는 JSON 콘텐츠에 대한 요구 사항을 보여 줍니다.

값 유형	요청 본문	응답 본문
JSON 개체	지원됨	지원됨
JSON 배열	지원됨 (현재 JSON 배열은 버그의 결과로 작동하지 않습니다. 수정이 진행 중입니다.)	지원되지 않음
JSON 값	지원됨	지원되지 않음
비-JSON 형식	지원되지 않음	지원되지 않음

인증

다음은 웹 작업에서 지원되는 인증 유형입니다.

없음

인증이 필요 없는 경우 "authentication" 속성을 포함하지 않습니다.

Basic

기본 인증에 사용할 사용자 이름 및 암호를 지정합니다.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

클라이언트 인증서

PFX 파일의 base64로 인코딩된 콘텐츠 및 암호를 지정합니다.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

인증서는 x509 인증서여야 합니다. PFX 파일로 변환하려면 원하는 유틸리티를 사용할 수 있습니다. base-64 인코딩의 경우 다음 PowerShell 코드 조각을 사용할 수 있습니다.

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

관리 ID

데이터 팩터리 또는 Synapse 작업 영역 인스턴스용 관리 ID를 사용하여 요청되는 액세스 토큰에 대한 리소스 URI를 지정합니다. Azure Resource 관리 API를 호출하려면 https://management.azure.com/을 사용합니다. 관리 ID의 작동 방식에 대한 자세한 내용은 Azure 리소스의 관리 ID 개요 페이지를 참조하세요.

"authentication": {
	"type": "MSI",
	"resource": "https://management.azure.com/"
}

참고 항목

데이터 팩터리 또는 Synapse 작업 영역이 Git 리포지토리로 구성된 경우, 기본 또는 클라이언트 인증서 인증을 사용하려면 Azure Key Vault에 자격 증명을 저장해야 합니다. 서비스는 Git에 암호를 저장하지 않습니다.

서비스 사용자

클라이언트 암호에 대한 보안 문자열을 사용하여 테넌트 ID, 서비스 주체 ID 및 서비스 주체 키를 지정합니다.

"authentication": {
            "type": "ServicePrincipal",
            "tenant": "your_tenant_id",
            "servicePrincipalId": "your_client_id",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "your_client_secret"
            },
            "resource": "https://management.azure.com/"
}

요청 페이로드 스키마

POST/PUT 메서드를 사용하는 경우 body 속성은 엔드포인트에 전송되는 페이로드를 나타냅니다. 연결된 서비스 및 데이터 세트를 페이로드의 일부로 전달할 수 있습니다. 페이로드 스키마는 다음과 같습니다.

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

예시

이 예제에서 파이프라인의 웹 작업은 REST 끝점을 호출하고 Azure SQL 연결된 서비스 및 Azure SQL 데이터 세트를 엔드포인트에 전달합니다. REST 엔드포인트는 Azure SQL 연결 문자열을 사용하여 논리 SQL Server에 연결하고 SQL Server의 인스턴스 이름을 반환합니다.

파이프라인 정의

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

파이프라인 매개 변수 값

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

웹 서비스 엔드포인트 코드


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

지원되는 다른 제어 흐름 작업을 참조하세요.

다음을 통해 공유

Azure Data Factory 및 Azure Synapse Analytics의 웹 작업

UI를 사용하여 웹 작업 만들기

구문

형식 속성

인증

없음

Basic

클라이언트 인증서

관리 ID

서비스 사용자

요청 페이로드 스키마

예시

파이프라인 정의

파이프라인 매개 변수 값

웹 서비스 엔드포인트 코드

피드백

추가 리소스

다음을 통해 공유

Azure Data Factory 및 Azure Synapse Analytics의 웹 작업

UI를 사용하여 웹 작업 만들기

구문

형식 속성

인증

없음

Basic

클라이언트 인증서

관리 ID

서비스 사용자

요청 페이로드 스키마

예시

파이프라인 정의

파이프라인 매개 변수 값

웹 서비스 엔드포인트 코드

관련 콘텐츠

피드백

추가 리소스