다음을 통해 공유

Azure Data Factory 또는 Azure Synapse Analytics를 사용하여 SharePoint Online 목록에서 데이터 복사

  • 아티클

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

이 문서에서는 Azure Data Factory 및 Azure Synapse 파이프라인의 복사 작업을 사용하여 SharePoint Online 목록에서 데이터를 복사하는 방법을 간략히 설명합니다. 이 문서는 복사 작업에 대한 일반적인 개요를 제공하는 복사 작업을 기준으로 합니다.

지원되는 기능

이 SharePoint Online 목록 커넥터는 다음 기능에 대해 지원됩니다.

지원되는 기능 IR
복사 작업(원본/-) 3,4
조회 작업 3,4

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

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

특히 이 SharePoint Online 목록 커넥터는 서비스 주체 인증을 사용하고 OData 프로토콜을 통해 데이터를 검색합니다.

팁

이 커넥터는 파일이 아닌 SharePoint Online 목록에서의 데이터 복사를 지원합니다. SharePoint Online에서 파일을 복사하는 방법에 대해 알아봅니다.

시작하기

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

UI를 사용하여 SharePoint Online 목록에 대한 연결된 서비스 만들기

다음 단계를 사용하여 Azure Portal UI에서 SharePoint Online 목록에 대한 연결된 서비스를 만듭니다.

  1. Azure Data Factory 또는 Synapse 작업 영역에서 관리 탭으로 이동하여 연결된 서비스를 선택하고 새로 만들기를 클릭합니다.

  2. SharePoint를 검색하고 SharePoint Online 목록 커넥터를 선택합니다.

    SharePoint Online 목록 커넥터의 스크린샷.

  3. 서비스 세부 정보를 구성하고, 연결을 테스트하고, 새로운 연결된 서비스를 만듭니다.

    SharePoint Online 목록의 연결된 서비스 구성 스크린샷.

커넥터 구성 세부 정보

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

연결된 서비스 속성

SharePoint Online 목록에 연결된 서비스에 다음 속성이 지원됩니다.

속성 설명 필수
type type 속성은 SharePointOnlineList로 설정해야 합니다. 예
siteUrl SharePoint Online 사이트 URL(예: https://contoso.sharepoint.com/sites/siteName) 예
servicePrincipalId Microsoft Entra ID에 등록된 애플리케이션의 애플리케이션(클라이언트) ID입니다. 예
servicePrincipalCredentialType 서비스 주체 인증에 사용할 자격 증명 유형을 지정합니다. 허용되는 값은 ServicePrincipalCert와 ServicePrincipalKey입니다. 아니요
ServicePrincipalCert의 경우
servicePrincipalEmbeddedCert Microsoft Entra ID에 등록된 애플리케이션의 base64 인코딩 인증서를 지정하고 인증서 콘텐츠 형식이 PKCS #12인지 확인합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다. 이 문서룰 참조하는 권한 설정을 구성해야 합니다. 아니요
servicePrincipalEmbeddedCertPassword 인증서가 암호로 보호되는 경우 인증서의 암호를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다. 아니요
ServicePrincipalKey의 경우
servicePrincipalKey 애플리케이션의 키입니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다. 권한 설정을 포함한 자세한 내용은 이 섹션을 참조하세요. 아니요
tenantId 애플리케이션이 있는 테넌트 ID입니다. 예
connectVia 데이터 저장소에 연결하는 데 사용할 통합 런타임입니다. 지정하지 않으면 기본 Azure Integration Runtime이 사용됩니다. 아니요

참고 항목

Azure ACS(Access Control Services)를 기준으로 하는 서비스 주체 키 인증을 사용하는 경우 ACS 사용 중지 계획으로 인해 서비스 주체 인증서 인증으로 전환하는 것이 좋습니다.

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

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType":  "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

서비스 주체 키 사용을 위한 권한 부여

SharePoint Online 목록 커넥터는 서비스 주체 인증을 사용하여 SharePoint에 연결합니다. 다음 단계에 따라 설정합니다.

  1. Microsoft ID 플랫폼에 애플리케이션 등록 자세한 방법은 빠른 시작: Microsoft ID 플랫폼에 애플리케이션 등록을 참조하세요. 연결된 서비스를 정의하는 데 사용되므로 다음 값을 적어둡니다.

    • 애플리케이션 ID
    • 애플리케이션 키
    • 테넌트 ID

  2. 아래 단계를 수행하여 등록된 애플리케이션에 SharePoint Online 사이트 권한을 부여합니다. 이를 수행하려면 사이트 관리자 역할이 필요합니다.

    1. SharePoint Online 사이트 링크를 엽니다. 자리 표시자 <your-site-url>이 사용자의 사이트인 https://<your-site-url>/_layouts/15/appinv.aspx 형식의 URL을 예로 들 수 있습니다.

    2. 등록한 애플리케이션 ID를 검색하고 빈 필드를 입력한 다음, “만들기”를 클릭합니다.

      • 앱 도메인: contoso.com

      • 리디렉션 URL: https://www.contoso.com

      • 권한 요청 XML:

        <AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>
</AppPermissionRequests>

        사이트 관리자 역할이 있는 경우 등록된 애플리케이션에 SharePoint Online 사이트 권한을 부여합니다.

      참고 항목

      SharePoint 커넥터 구성과 관련하여 "앱 도메인" 및 "리디렉션 URL"은 SharePoint 데이터에 대한 액세스를 허용하기 위해 Microsoft Entra ID에 등록한 SharePoint 앱을 나타냅니다. "앱 도메인"은 SharePoint 사이트가 호스트되는 도메인입니다. 예를 들어 SharePoint 사이트가 "https://contoso.sharepoint.com"에 있는 경우 "앱 도메인"은 "contoso.sharepoint.com"입니다. "리디렉션 URL"은 사용자가 앱에 대한 권한을 인증하고 부여한 후 SharePoint 앱이 리디렉션할 URL입니다. 이 URL은 앱에 액세스할 수 있는 권한이 있는 SharePoint 사이트의 페이지여야 합니다. 예를 들어 라이브러리의 파일 목록을 표시하는 페이지의 URL 또는 문서의 콘텐츠를 표시하는 페이지를 사용할 수 있습니다.

    3. 이 앱에 대해 "신뢰"를 클릭합니다.

데이터 세트 속성

데이터 세트 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 데이터 세트 및 연결된 서비스를 참조하세요. 이 섹션에서는 SAP 테이블 데이터 세트에서 지원되는 속성의 목록을 제공합니다.

속성 설명 필수
type 데이터 세트의 type 속성을 SharePointOnlineLResource로 설정해야 합니다. 예
listName SharePoint Online 목록의 이름입니다. 파일 이름에는 아포스트로피(')를 사용할 수 없습니다. 예

예제

{
    "name": "SharePointOnlineListDataset",
    "properties":
    {
        "type": "SharePointOnlineListResource",
        "linkedServiceName": {
            "referenceName": "<SharePoint Online List linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "listName": "<name of the list>"
        }
    }
}

복사 활동 속성

작업 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 파이프라인을 참조하세요. 다음 섹션에서는 SharePoint Online 목록 원본에서 지원되는 속성의 목록을 제공합니다.

SharePoint Online 목록을 원본으로

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

속성 설명 필수
type 복사 작업 원본의 type 속성은 SharePointOnlineListSource로 설정해야 합니다. 예
query 데이터 필터링을 위한 사용자 지정 OData 쿼리 옵션입니다. 예: "$top=10&$select=Title,Number" 아니요
httpRequestTimeout HTTP 요청이 응답을 받을 시간 제한(초)입니다. 기본값은 300(5분)입니다. 아니요

예제

"activities":[
    {
        "name": "CopyFromSharePointOnlineList",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<SharePoint Online List input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SharePointOnlineListSource",
                "query": "<OData query e.g. $top=10&$select=Title,Number>"
            }, 
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

참고 항목

SharePoint Online 목록 원본에 대해 두 개 이상의 선택 데이터 형식을 선택할 수 없습니다.

SharePoint Online 목록에 대한 데이터 형식 매핑

SharePoint Online 목록에서 데이터를 복사하는 경우 SharePoint Online 목록 데이터 형식과 서비스 내부에서 사용되는 중간 데이터 형식 사이에서 다음 매핑이 사용됩니다.

SharePoint Online 데이터 형식 OData 데이터 형식 중간 데이터 형식
한 줄 텍스트 Edm.String 문자열
여러 줄 텍스트 Edm.String 문자열
선택(선택할 메뉴) Edm.String 문자열
숫자(1, 1.0, 100) Edm.Double 두 배
통화($, ¥, €) Edm.Double 두 배
날짜 및 시간 Edm.DateTime DateTime
조회(사이트에 이미 있는 정보) Edm.Int32 Int32
예/아니요(확인란) Edm.Boolean 부울
개인 또는 그룹 Edm.Int32 Int32
하이퍼링크 또는 사진 Edm.String 문자열
계산됨(다른 열을 기반으로 계산) Edm.String/Edm.Double/Edm.DateTime/Edm.Boolean String/Double/DateTime/Boolean
첨부 파일 지원되지 않음
작업 결과 지원되지 않음
외부 데이터 지원되지 않음
관리되는 메타데이터 지원되지 않음

SharePoint Online에서 파일 복사

웹 작업을 사용하여 인증하고 SPO에서 액세스 토큰을 구한 다음, 이후의 복사 작업에 전달하여 HTTP 커넥터를 원본으로 데이터를 복사함으로써 SharePoint Online에서 파일을 복사할 수 있습니다.

Sharepoint 파일 복사 흐름

  1. 서비스 주체 키 사용을 위한 권한 부여 섹션에 따라 Microsoft Entra 애플리케이션을 만들고 SharePoint Online에 권한을 부여합니다.

  2. SharePoint Online에서 액세스 토큰을 가져오는 웹 작업을 만듭니다.

    • URL: https://accounts.accesscontrol.windows.net/[Tenant-ID]/tokens/OAuth/2. 테넌트 ID를 바꿉니다.
    • 메서드: POST
    • 헤더:
      • Content-Type: application/x-www-form-urlencoded
    • 본문: grant_type=client_credentials&client_id=[Client-ID]@[Tenant-ID]&client_secret=[Client-Secret]&resource=00000003-0000-0ff1-ce00-000000000000/[Tenant-Name].sharepoint.com@[Tenant-ID]. 클라이언트 ID(애플리케이션 ID), 클라이언트 암호(애플리케이션 키), 테넌트 ID 및 테넌트 이름(SharePoint 테넌트)을 대체합니다.

    주의

    웹 작업에서 보안 출력 옵션을 true로 설정하여 토큰 값이 일반 텍스트로 기록되지 않게 합니다. 이 값을 사용하는 추가 작업의 경우 보안 입력 옵션을 true로 설정해야 합니다.

  3. HTTP 커넥터를 원본으로 사용하여 SharePoint Online 파일 콘텐츠를 복사하는 복사 작업과의 체인

    • HTTP 연결 서비스:
      • 기준 URL: https://[site-url]/_api/web/GetFileByServerRelativeUrl('[relative-path-to-file]')/$value. 사이트 URL 및 상대 경로를 파일로 바꿉니다. 도메인 이름(예: https://[sharepoint-domain-name].sharepoint.com/sites/[sharepoint-site]/_api/web/GetFileByServerRelativeUrl('/sites/[sharepoint-site]/[relative-path-to-file]')/$value)과 함께 SharePoint 사이트 URL을 포함해야 합니다.
      • 인증 유형: 익명(나중에 복사 작업 원본에 구성된 전달자 토큰을 사용하기 위해)
    • 데이터 세트: 원하는 형식을 선택합니다. 파일을 있는 그대로 복사하려면 "이진" 형식을 선택합니다.
    • 복사 작업 원본:
      • 요청 메서드: GET
      • 추가 헤더: 업스트림 웹 작업에서 생성한 전달자 토큰을 인증 헤더로 사용하는 다음 식 @{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}을 사용합니다. 웹 작업 이름을 바꿉니다.
    • 지원되는 모든 싱크 대상에 대한 복사 작업 싱크를 구성합니다.

참고 항목

Microsoft Entra 애플리케이션에 SharePoint Online에 대한 FullControl 권한이 있더라도 IRM이 사용하도록 설정된 문서 라이브러리에서 파일을 복사할 수 없습니다.

조회 작업 속성

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

관련 콘텐츠

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