ETL: 중급 Part9：Xplenty의 Rest API로 기존 업무와의 연계(1)

들어가며 운영체제(OS)에 그래픽 사용자 인터페이스(GUI)가 등장하면서 컴퓨터와 관련된 환경이 크게 바뀌었다. GUI를 통해 컴퓨터는 더 이상 전문가의 도구가 아닌 누구나 사용할 수 있는 도구로 우리 생활 속에 자리 잡게 되었고, 그 변화 중 하나로 조작의 편의성을 꼽을 수 있다. 하지만 모든 일에는 앞과 뒤가 있듯이 반드시 좋은 영향만 있었던 것은 아니다. 기존의 명령줄 인터페이스(CLI)에 비해 일반 사용자의 편의성을 크게 향상시킨 GUI는 편리함 대신 시각적 처리 때문에 컴퓨터의 성능이 저하되거나 세밀한 제어가 어렵고, 숙달되면 오히려 조작이 느려지는 등의 문제가 발생하기도 했다. 이른바 익숙해진 전문가 입장에서 보면 비효율적인 요소가 크다. 그래서 현존하는 OS는 종류를 불문하고 GUI와 CLI를 함께 제공하고 있습니다. 전문 ETL 툴인 저희 Xplenty는 노코드/로우코드 툴로서 데이터 파이프라인 구축에 GUI 환경을 제공하고 있습니다. 하지만 위의 OS의 예처럼 데이터 파이프라인 구축과 운영에 익숙해지면 GUI를 통한 조작이 번거로울 수 있습니다. 이를 위해 Xplenty에서는 CLI 기반으로 이용할 수 있는 Rest API를 제공하고 있습니다. 이번 글에서는 Xplenty가 제공하는 Rest API 중 리소스 열람용에 대해 자세히 알아보겠습니다. 사전 준비

​

제한 사항

이 글은 아래와 같은 전제를 가지고 설명합니다. 양해 부탁드립니다.

• 데이터 파이프라인(Xplent에서는 패키지)은 이미 생성되어 있다.
• Crul, Postman, Insomnia 등의 HTTP/HTTPS 클라이언트 사용 경험이 있다.
• Rest API 조작에 익숙하다.
• API에 대한 자세한 내용은 github(영어)를 참고하시기 바랍니다.

​

Xplenty Rest API 기본 정보

Xplenty의 Rest API는 Xplenty가 제공하는 HTTPS 기반의 RESTful API 모음으로, 사용 방법도 일반적인 RESTful API 사용과 차이가 없습니다. 이 글에서는 github의 내용을 기준으로 Rest API의 실습을 진행하고자 합니다.

​

Rest API URL

**https://api.xplenty.com/**``**<account_id>/api/<reosource_name**

**<account_id>**는 Xplenty의 Settings - Accounting Settings - Profile에서 확인할 수 있다.[ ](https://cdn.filestackcontent.com/auto_image//compress/cache=expiry:max/D30XOukBSyudiHkKOUtt)

• <reosurce_name>에 대해서는 Xplenty의 주요 리소스 소개 부분을 참고하시기 바랍니다.

​

인증 방식

• HTTP Basic을 사용하고 있으며, 모든 Xplenty Rest API는 인증이 반드시 필요합니다.
• 사용자 이름은 Xplenty의 API KEY를 지정하며, 비밀번호는 지정할 필요가 없다.
• curl로 지정 - -d <API_KEY>:

**<API KEY>**는 Xplenty의 Settings - Developer Settings - Access token에서 조회할 수 있다.[ ](https://cdn.filestackcontent.com/auto_image//compress/cache=expiry:max/dWUZbBFZSayeC4T6r2oP)

• 단, 현재 API KEY 요청은 Live Chat을 통해 문의해 주시기 바랍니다!

​

호출 횟수 제한

• 사용자당 1시간에 5000회의 호출 횟수 제한(credit)이 있습니다.
• 지정된 호출 횟수 초과 시 429 Too Many Requests를 반환한다.

​

Rest API 호출 예시

이제 Xplenty의 Rest API 호출 샘플을 각각의 HTTP/HTTPS 클라이언트를 통해 소개하겠습니다. 예시 설명은 List Jobs를 사용하여 HTTP/HTTPS 클라이언트 상에서 API 호출을 수행합니다. Xplenty가 제공하는 모든 API의 목록은 이 링크를 참고하시기 바랍니다.

​

GUI 앱을 통한 호출

잘 알려진 HTTP/HTTPS 클라이언트인 Postman과 Insomnia를 사용하여 Xplenty의 Rest API를 호출 해 보겠습니다.

• Rest API의 URL을 주소창에 설정
• 위의 URL에 대해 적절한 메서드(여기서는 GET)를 선택합니다.
• 인증(Authentication)에서 방법을 Basic으로 선택한 후, username에는 API_KEY를 입력하고 password는 비워둔다. [

](https://cdn.filestackcontent.com/auto_image//compress/cache=expiry:max/2uA6xmYhREWh8ZOAVUyf)

• Header에 호출 시 필요한 Header를 해당 API의 문서를 참고하여 적절히 설정한다. [

](https://cdn.filestackcontent.com/auto_image//compress/cache=expiry:max/EQCUsRXQTReQcY4nKqhr)

• Send 버튼을 눌러 응답을 확인한다. [

](https://cdn.filestackcontent.com/auto_image//compress/cache=expiry:max/yviLCZxpQk6XLgMOmU03)

​

Curl 명령어로 호출하기

커맨드 라인에 의한 조작에 익숙한 분이라면 curl 명령어를 잘 사용하고 있을것으로 생각합니다. curl의 조작 방법이 궁금하다면 아래 두 가지 자료를 참고하면 좋을 것 같다.

• curl tutorial(영어)
• 간이 가이드(한국어)

앞의 Postman과 동일한 조작을 curl 명령어로 실행합니다. 호출 시 필요한 정보는 아래의 옵션을 사용하여 설정해 주시면 됩니다.

• -X : 메서드 지정(GET 지정)
• -u : Baisc 인증 설정(<API_KYE>:)
• URL : 작업 목록 조회를 위한 REST API의 URL
• -H : Rest API 호출 시 필요한 헤더 정보
• 요청 (Curl Call)

curl -X GET -u <API_KEY>: “https://api.xplenty.com/<account_id>/api/jobs”
-H “Accept: application/vnd.xplenty+json; version=2”

• 응답

[ { “id”: 304, “status”: “failed”, “variables”: { “InputPath”: ”‘/today’” }, “owner_id”: 1, “progress”: 0, “outputs_count”: 0, “outputs”: [], “started_at”: “2013-03-04T08:02:20Z”, “created_at”: “2013-03-04T08:02:17Z”, “updated_at”: “2013-03-04T08:03:01Z”, “failed_at”: null, “cluster_id”: 176, “package_id”: 103, “errors”: “Package failed to execute.”, “runtime_in_seconds”: 40, “completed_at”: “2013-03-04T08:03:01Z”, “url”: “https://api.xplenty.com/xplenation/api/jobs/304”, “html_url”: “https://xplenty.com/xplenation/jobs/304”, “log_url”: “https://api.xplenty.com/xplenation/api/jobs/304/log”, “creator”: { “type”:“Schedule”, “id”:1, “display_name”: “Schedule 1”, “url”: “https://api.xplenty.com/xplenation/api/schedules/1”, “html_url”: “https://xplenty.com/xplenation/schedules/1” }, “package”: { “id”: 2373, “name”: “AWS CloudFront Log Analysis”, “description”: “This package processes AWS CloudFront logs and extracts traffic information by time, geography and URIs”, “variables”: {}, “owner_id”: 8, “created_at”: “2014-03-12T07:09:18Z”, “updated_at”: “2014-04-13T19:38:04Z”, “url”: “https://api.xplenty.com/xplenation/api/packages/2373”, “status”:“active” }, “cluster”: { “id”: 99, “name”: “Daily Outliers Test #100”, “description”: “Daily Outliers Test”, : : “bootstrap_actions”: [{ “script_path”: “http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz”, “args”: [“arg1”, “arg2”] }, { “script_path”: “http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz”, “args”: [“arg1”] }], “creator”: { “type”:“Schedule”, “id”:1, “display_name”: “Schedule 1”, “url”: “https://api.xplenty.com/xplenation/api/schedules/1”, “html_url”: “https://xplenty.com/xplenation/schedules/1” } } }, { : : }, { : : } ]

​

Xplenty 리소스 보기

Xplenty에는 데이터 전송 작업과 관련된 몇 가지 개념을 리소스라고 부릅니다. 작업에 해당하는 적절한 리소스를 선택하여 조작을 수행합니다. 열람용의 Rest API는 이러한 리소스의 존재 여부 및 리소스의 상세 정보를 얻기 위해 필수적인 API이며, Rest API에서 열람용은 각 리소스에 대해 GET 메소드를 통해 호출 됩니다.

​

Xplenty의 주요 리소스 소개

Xplenty에서 사용되는 주요 리소스는 아래와 같습니다. 리소스 설명 클러스터(Cluster) 계정 사용자에게 독점적으로 할당되는 머신(노드)의 그룹으로, 하나 이상의 클러스터를 생성하고 각 클러스터에서 하나 이상의 작업을 실행할 수 있다. 생성한 클러스터는 종료될 때까지 계정에 할당된 상태로 유지된다. 패키지(Package) Xplenty 웹 애플리케이션에서 생성할 데이터 흐름의 정의이다. 처리할 원본 데이터(위치, 스키마, 필드), 수행할 데이터 작업 및 출력 대상(위치, 스키마)을 기술합니다. 패키지의 워크플로는 작업(Job)에 의해 구현된다. 작업(Job) 클러스터의 특정 패키지에 따라 데이터 흐름을 실행하는 프로세스이다. 작업은 대상 범위의 데이터를 처리하는 배치 프로세스이다. 여러 개의 작업이 동시에 동일한 패키지를 실행할 수 있으며, Xplenty API를 호출하여 새로운 작업을 실행할 때 작업이 실행할 워크플로우의 패키지 이름과 작업을 실행할 클러스터를 지정한다. 스케줄(Schedule) 지정된 일시에 패키지를 주기적으로 실행한다. 패키지는 스케줄된 클러스터 크기에 맞는 기존 클러스터를 사용하여 스케줄에 따라 실행된다. 클러스터가 존재하지 않는 경우, 지정된 노드 수만큼의 클러스터가 자동으로 프로비저닝된다. 기본적으로 패키지 실행이 완료되는 즉시 클러스터는 정지된다. 기타 리소스 위의 리소스 외에도 다양한 리소스가 있으니 링크를 참고하시기 바랍니다.

​

주요 리소스 열람 API

주요 리소스를 조회하기 위해 아래의 API를 사용합니다. 각각의 Rest API에는 지정 가능한 파라미터가 존재하며, 해당 파라미터의 지정에 따라 조회 범위의 제한 또는 가능 여부가 결정됩니다. 자세한 내용은 해당 링크를 참고하시기 바랍니다. 또한, 아래의 Rest API는 인증된 사용자에게만 허용됩니다. 열람 API 설명 List Clusters 클러스터 목록을 조회합니다. 기본적으로 모든 status(상태)의 클러스터를 조회할 수 있지만, 특정 상태의 클러스터만 조회할 수도 있습니다. List Jobs 작업 목록을 조회합니다. 패키지 ID나 상태를 지정하여 조회 범위를 좁힐 수 있습니다. List Packages 패키지 목록을 조회합니다. 패키지는 2가지 종류(workflow, dataflow)가 있지만, 기본적으로 모든 종류의 패키지를 열람할 수 있습니다. List Schedules 스케줄 목록을 조회합니다. List Account Connections 사용자가 생성한 커넥션 목록을 가져옵니다. type 파라미터를 통해 유형별로 세분화할 수 있으며, type에 대해서는 링크의 커넥터별 설명서를 참고하시기 바랍니다. 그 외 List로 시작하는 API는 링크된 페이지에서 해당 API의 문서를 참고하시기 바랍니다.

​

조회 API의 주요 쿼리 파라미터

GET 메서드로 리소스를 가져오는 브라우징 API는 리소스의 범위를 지정하는 몇 가지 쿼리 파라미터가 있습니다. 자세한 내용은 바로 위의 열람 API를 참고하기 바라며, 주로 사용하는 파라미터는 다음과 같다. 쿼리 파라미터 값 예시 설명 sort created / updated / 기타 sort=created 정렬 기준 속성을 지정한다. direction asc / desc direction=desc sort 파라미터에서 지정한 속성을 기준으로 오름차순 또는 내림차순으로 정렬한다.

​

since

since=2023-08-31T15:00:00:00Z 자원의 취득 시작 일자를 지정하며, 일자의 포맷은 ISO-8601(YYYY-MM-DDTHH:MM:SSZ)의 UTC이다.

​

status

status=all or status=active 리소스에 따라 지정할 수 있는 값이 다르므로 API 문서를 참고한다.

​

열람 시 제한 사항(offset과 limit)

Xplenty의 열람 API는 시스템의 영향을 고려하여 반환 목록의 임계값을 설정하고 있다. 임계값과 관련된 파라미터로 offset과 limit이 있습니다. 두 파라미터를 지정하지 않고 열람 API를 호출하면, 기본적으로 offset = 0과 limit = 20이 열람용 API에 부여됩니다. 또한 limit의 최대값은 100까지 지정할 수 있으므로, 열람용 Rest API를 사용할 때 offset과 limit의 적절한 값 조정을 권장합니다. 마치며 이상으로 Xplenty가 제공하는 Rest API 중 열람계에 대해 알아보았다. 다음에는 Rest API를 사용하여 Xplenty로 데이터를 전송하는 방법을 살펴보겠습니다. Xplenty는 IT 백그라운드가 없는 사람뿐만 아니라 IT에 익숙한 사람들도 편리하게 사용할 수 있는 유연한 환경을 제공하고 있습니다. 2주간 무료 트라이얼을 통해 Xplenty의 편리함을 직접 경험해 보시기 바랍니다. 진심으로 기다리고 있습니다.

​

<!— Google Tag Manager hidden fields —> <!— End Google Tag Manager hidden fields —> <!— Text input—> Get Started Free 7-day trial. Easy setup. Cancel any time