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

아티클
11/05/2024

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

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

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

참고 항목

Xero 커넥터는 OAuth 인증이 필요하며 서버 대 서버 사용을 위한 것이 아닙니다.

지원되는 기능

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

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

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

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

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

OAuth 2.0 인증.
"보고서"를 제외한 모든 Xero 테이블(API 엔드포인트)
이 문서의 Windows 버전입니다.

참고 항목

Xero에서 OAuth 1.0 인증이 종료되므로 현재 OAuth 1.0 인증 유형을 사용하는 경우 OAuth 2.0 인증 유형으로 업그레이드하세요.

시작

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

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

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

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

커넥터 구성 세부 정보

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

연결된 서비스 속성

다음은 Xero 연결된 서비스에 대해 지원되는 속성입니다.

속성	설명	필수
type	type 속성은 Xero로 설정해야 합니다.	예
connectionProperties	Xero에 연결하는 방법을 정의하는 속성 그룹입니다.	예
`connectionProperties`에서:
host	Xero 서버(`api.xero.com`)의 엔드포인트입니다.	예
authenticationType	허용되는 값은 `OAuth_2.0`와 `OAuth_1.0`입니다.	예
consumerKey	OAuth 2.0에 대해 Xero 애플리케이션의 클라이언트 ID를 지정합니다. OAuth 1.0에 대해 Xero 애플리케이션에 연결된 소비자 키를 지정합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예
privateKey	OAuth 2.0에 대해 Xero 애플리케이션에 대한 클라이언트 비밀을 지정합니다. OAuth 1.0의 경우 Xero 프라이빗 애플리케이션에 대해 생성된 .pem 파일의 프라이빗 키를 지정합니다. 512의 numbits로 privatekey.pem을 생성하기 위해 `openssl genrsa -out privatekey.pem 512`을 사용합니다. 1024는 지원되지 않습니다. Unix 줄 끝(\n)을 포함하여 .pem 파일의 모든 텍스트를 포함합니다. 아래 샘플을 참조하세요. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예
tenantId	Xero 애플리케이션과 연결된 테넌트 ID입니다. OAuth 2.0 인증에 적용됩니다. 액세스 권한이 부여된 테넌트 확인 섹션에서 테넌트 ID를 가져오는 방법에 대해 알아보기.	예(OAuth 2.0 인증의 경우)
refreshToken	OAuth 2.0 인증에 적용됩니다. OAuth 2.0 새로 고침 토큰은 Xero 애플리케이션과 연결되며, 액세스 토큰을 새로 고치는 데 사용됩니다. 액세스 토큰은 30분 후에 만료됩니다. 이 문서에서는 Xero 권한 부여 흐름이 작동하는 방법 및 새로 고침 토큰을 가져오는 방법에 대해 알아봅니다. 새로 고침 토큰을 가져오려면, offline_access 범위를 요청해야 합니다. 인식 제한: Xero는 액세스 토큰 새로 고침에 사용된 후 새로 고침 토큰을 다시 설정한다는 점을 참고합니다. 조작 가능한 워크로드의 경우, 각 복사 작업을 실행하기 전에 서비스에서 사용할 유효한 새로 고침 토큰을 설정해야 합니다. 이 필드를 SecureString으로 표시하여 안전하게 저장하거나, Azure Key Vault에 저장된 비밀을 참조합니다.	예(OAuth 2.0 인증의 경우)
useEncryptedEndpoints	데이터 원본 엔드포인트가 HTTPS를 사용하여 암호화되는지 여부를 지정합니다. 기본값은 true입니다.	아니요
useHostVerification	TLS를 통한 연결 시, 서버 인증서의 호스트 이름을 서버의 호스트 이름과 일치하도록 할지 여부를 지정합니다. 기본값은 true입니다.	아니요
usePeerVerification	TLS를 통해 연결할 때 서버의 ID를 확인할지 여부를 지정합니다. 기본값은 true입니다.	아니요

예: OAuth 2.0 인증

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": { 
                "host": "api.xero.com",
                "authenticationType":"OAuth_2.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<client ID>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<client secret>"
                },
                "tenantId": "<tenant ID>", 
                "refreshToken": {
                    "type": "SecureString",
                    "value": "<refresh token>"
                }, 
                "useEncryptedEndpoints": true, 
                "useHostVerification": true, 
                "usePeerVerification": true
            }            
        }
    }
}

예: OAuth 1.0 인증

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": {
                "host": "api.xero.com", 
                "authenticationType":"OAuth_1.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<consumer key>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<private key>"
                }, 
                "useEncryptedEndpoints": true,
                "useHostVerification": true,
                "usePeerVerification": true
            }
        }
    }
}

샘플 프라이빗 키 값:

Unix 줄 끝(\n)을 포함하여 .pem 파일의 모든 텍스트를 포함합니다.

"-----BEGIN RSA PRIVATE KEY-----\nMII***************************************************P\nbu****************************************************s\nU/****************************************************B\nA*****************************************************W\njH****************************************************e\nsx*****************************************************l\nq******************************************************X\nh*****************************************************i\nd*****************************************************s\nA*****************************************************dsfb\nN*****************************************************M\np*****************************************************Ly\nK*****************************************************Y=\n-----END RSA PRIVATE KEY-----"

데이터 세트 속성

데이터 세트 정의에 사용할 수 있는 섹션 및 속성의 전체 목록은 데이터 세트 문서를 참조하세요. 이 섹션에서는 Xero 데이터 세트에서 지원하는 속성의 목록을 제공합니다.

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

속성	설명	필수
type	데이터 세트의 형식 속성을 XeroObject로 설정해야 합니다.	예
tableName	테이블 이름입니다.	아니요(작업 원본에서 "query"가 지정된 경우)

예제

{
    "name": "XeroDataset",
    "properties": {
        "type": "XeroObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Xero linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

복사 작업 속성

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

Xero 원본

Xero에서 데이터를 복사하려면 복사 작업의 원본 형식을 XeroSource로 설정합니다. 복사 작업 source 섹션에서 다음 속성이 지원됩니다.

속성	설명	필수
type	복사 작업 원본의 type 속성은 XeroSource로 설정해야 합니다.	예
query	사용자 지정 SQL 쿼리를 사용하여 데이터를 읽습니다. 예: `"SELECT * FROM Contacts"`	아니요(데이터 세트의 "tableName"이 지정된 경우)

예제:

"activities":[
    {
        "name": "CopyFromXero",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Xero input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "XeroSource",
                "query": "SELECT * FROM Contacts"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Xero 쿼리를 지정할 때 다음 사항에 유의합니다.

복잡한 항목이 있는 테이블은 여러 테이블로 분할됩니다. 예를 들어 은행 거래에는 "LineItems"라는 복합 데이터 구조가 있기 때문에, 은행 거래의 데이터는 Bank_Transaction 및 Bank_Transaction_Line_Items 테이블로 매핑되고 Bank_Transaction_ID가 이들을 연결하는 외래 키로 사용됩니다.
Xero 데이터는 Minimal(기본값) 및 Complete라는 두 가지 스키마를 통해 사용할 수 있습니다. Complete 스키마는 원하는 쿼리를 만들기 전에 추가 데이터(예: ID 열)가 필요한 필수 구성 요소 호출 테이블을 포함합니다.

다음 테이블에는 Minimal 및 Complete 스키마와 동일한 정보가 있습니다. API 호출 수를 줄이기 위해 Minimal 스키마(기본값)를 사용합니다.

Bank_Transactions
Contact_Groups
연락처
Contacts_Sales_Tracking_Categories
Contacts_Phones
Contacts_Addresses
Contacts_Purchases_Tracking_Categories
Credit_Notes
Credit_Notes_Allocations
Expense_Claims
Expense_Claim_Validation_Errors
송장
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
Overpayments
Overpayments_Allocations
Prepayments
Prepayments_Allocations
영수증
Receipt_Validation_Errors
Tracking_Categories

다음 테이블은 complete 스키마로만 쿼리할 수 있습니다.

Complete.Bank_Transaction_Line_Items
Complete.Bank_Transaction_Line_Item_Tracking
Complete.Contact_Group_Contacts
Complete.Contacts_Contact_ Persons
Complete.Credit_Note_Line_Items
Complete.Credit_Notes_Line_Items_Tracking
Complete.Expense_Claim_ Payments
Complete.Expense_Claim_Receipts
Complete.Invoice_Line_Items
Complete.Invoices_Line_Items_Tracking
Complete.Manual_Journal_Lines
Complete.Manual_Journal_Line_Tracking
Complete.Overpayment_Line_Items
Complete.Overpayment_Line_Items_Tracking
Complete.Prepayment_Line_Items
Complete.Prepayment_Line_Item_Tracking
Complete.Receipt_Line_Items
Complete.Receipt_Line_Item_Tracking
Complete.Tracking_Category_Options

조회 작업 속성

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

복사 작업에서 지원되는 데이터 저장소 목록은 지원되는 데이터 저장소를 참조하세요.

다음을 통해 공유

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

지원되는 기능

시작

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

커넥터 구성 세부 정보

연결된 서비스 속성

데이터 세트 속성

복사 작업 속성

Xero 원본

조회 작업 속성

피드백

추가 리소스

다음을 통해 공유

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

지원되는 기능

시작

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

커넥터 구성 세부 정보

연결된 서비스 속성

데이터 세트 속성

복사 작업 속성

Xero 원본

조회 작업 속성

관련 콘텐츠

피드백

추가 리소스