들어가며

전문 ETL 툴인 당사의 Xplenty는 노코드/로우코드 툴로서 데이터 파이프라인 구축에 대한 IT 지식이 얕은 분들을 위해 GUI 환경을 제공합니다. 또한, Xplenty의 조작에 익숙한 분들이나 기존의 운영 워크플로우에 Xplenty를 도입하고 싶은 분들을 위해 CLI 기반으로 이용할 수 있는 Rest API를 제공하고 있습니다. 이번 글에서는 Xplenty의 비조회형 Rest API를 어떻게 활용할 수 있는지 자세히 살펴보겠습니다.

REST(ful) API에 대한 간단한 설명

앞뒤가 뒤바뀐 감은 있지만, 먼저 REST API란 무엇일까요?
다른 자료를 참고하면 아래와 같이 정의할 수 있습니다.

REST 원칙에 따라 구축된 웹 시스템의 HTTP 호출 인터페이스를 말합니다.
REpresentational State Transfer의 약자로, 분산 시스템에서 여러 소프트웨어를 연동하는 데 적합한 설계 원칙의 집합 혹은 사고방식을 지칭.
REST를 이야기할 때 빼놓을 수 없는 '리소스(Resource Oriented Architecture(ROA))'라는 개념이 있다.

그렇다면 리소스란 무엇일까?

웹상에 존재하는 정보, 데이터를 말한다.
컴퓨터 상에 저장할 수 있고, 일련의 비트로 표현할 수 있다. 또한, 그 자체로 참조할 가치가 있을 만큼 중요한 의미를 가진다.
예를 들어, 문서, 데이터베이스의 행 등. 리소스는 명사로 정의된다.

즉, 웹에 구성된 시스템 상에 축적된 데이터를 리소스라고 하며, 이를 HTTP의 메소드로 조작하여 다양한 작업을 수행하는 것을 말합니다. 조작에는 리소스 생성, 리소스 변경(전체, 일부), 리소스 삭제, 리소스 열람이 있습니다. 어떤 일을 시키기 위해서는 REST API에서는 자원의 변경(상태의 변이)을 통해 그 목적을 달성합니다.

REST API의 비조회용 메서드

REST API에는 리소스 조작을 위한 메서드들이 준비되어 있으며, 이전 글 전체에서 보여드린 것은 리소스 조회에 사용되는 GET 메서드였습니다.

아래에 다른 메서드들을 소개합니다.

메서드 이름	설명	Xplenty에서의 동작
`POST`	리소스 생성	`CREATE`로 시작하는 API에서 사용되는 메서드
`PUT`	리소스 전체 갱신(교체)	이미 생성된 리소스 변경 시 사용되며, `UPDATE`로 시작하는 API에서 사용되는 메서드이다.
`DELETE`	리소스 삭제	생성된 리소스를 터미네이션(종료)할 때 사용하며, `DELETE`로 시작하는 API에서 사용되는 메서드이다.
GET	리소스 조회	`LIST`로 시작하는 API에서 사용하는 메서드
~~PATCH~~	리소스의 부분 업데이트(일부 업데이트)	※ Xpelnty에서는 사용되지 않는다.

Xplenty에서는 위의 메소드와 리소스를 조합하여 데이터 전송을 명령어 라인 또는 통합 운영 관리 소프트웨어에서 기존 운영 환경에 쉽게 통합할 수 있다.

Rest API를 통한 운영 예시

여기서는 Xplenty의 Rest API를 활용한 작업 실행 작업을 설명한다. 보통은 Xplenty의 UI에서 수행하는 작업이지만, Rest API를 통해서도 동일한 작업이 가능합니다.
전제 조건으로 작업에 사용되는 패키지가 UI에서 이미 생성되어 있다고 가정한다.

작업	참조 문서
1. 클러스터 생성	Create Cluster
2. 클러스터 초기화 확인	List Clusters
3. 작업 실행	Run Job
4. 작업 초기화 및 완료 확인	List Jobs
6. 클러스터 종료	Terminate Cluster
7. 클러스터 종료 확인	List Clusters

1. 클러스터 생성

패키지를 실행하기 위해서는 그 실행 환경인 클러스터가 필요하다. 첫 단계에서는 클러스터가 없다고 가정하고 클러스터를 생성한다.

호출 예(curl call)

curl -X POST -u <API_KEY>: "https://api.xplenty.com/<Account_ID>/api/clusters" \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes":4,
    "type":"production",
    "name":"New Cluster",
    "description":"New Cluster Description"
  }'

응답 예시

HTTP/1.1 201 Created

{
  "id": 167,
  "name": "New Cluster",
  "description": "New Cluster Description",
  "status": "pending",
  "owner_id": 27,
  "plan_id": null,
  "nodes": 4,
  "type": "production",
  "created_at": "2013-03-03T13:06:51Z",
  "updated_at": "2013-03-03T13:06:51Z",
  "available_since": null,
  "terminated_at": null,
  "running_jobs_count": 0,
  "terminate_on_idle": false,
  "time_to_idol": 3600,
  "terminated_on_idle": false,
  "region": "amazon-web-services::us-east-1",
  "zone": "us-east-1b",
    :
  "idle_since": "2013-03-03T13:06:51Z",
  "url": "https://api.xplenty.com/xplenation/api/clusters/167",
  "html_url": "https://xplenty.com/xplenation/clusters/167",
  "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",
    "display_name": "Schedule 1",
    "id":1,
    "url": "https://api.xplenty.com/xplenation/api/schedules/1",
    "html_url": "https://xplenty.com/xplenation/schedules/1"
  }
}

2. 클러스터 초기화 확인

클러스터 생성 및 초기화를 확인한다. 클러스터의 상태(status)가 available이 될 때까지 기다려야 하므로 이 API를 반복적으로 실행한다.

호출 예(curl call)

curl -X GET -u <API_KEY>: "https://api.xplenty.com/<Account_ID>/api/clusters/<cluster_id>" \
  -H "Accept: application/vnd.xplenty+json; version=2"

응답 예시

HTTP/1.1 200 OK

[
  {
    "id": 99,
    "name": "Daily Outliers Test #100",
    "description": "Daily Outliers Test",
    "status": "terminated",
    "owner_id": 27,
    "plan_id": 1,
    "nodes": 2,
    "type": "production",
    "created_at": "2013-01-25T08:18:39Z",
    "updated_at": "2013-01-28T16:45:24Z",
    "available_since": "2013-01-28T16:46:22Z",
    "terminated_at": "2013-01-28T17:45:33Z",
    "running_jobs_count": 0,
    "terminate_on_idle": false,
    "time_to_idle": 3600,
    "terminated_on_idle": false,
         :
         :
    }
]

3. 작업 실행

실행하고자 하는 패키지의 package_id와 클러스터 생성 시 획득한 cluster_id를 이용하여 작업을 실행한다.

호출 예(curl call)

curl -X POST -u <API_KEY>: "https://api.xplenty.com/<Account_ID>/api/jobs" \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_id":167,
    "package_id":103,
    "dynamic_variables":{
      "current_time":"CurrentTime()",
      "MY_CURRENT_TIME":"$CURRENT_TIME_VAR",
      "MY_STRING_VAR":"'some string'"
    },
    "variables": {
      "MY_STATIC_VAR":"some static variable"
    }
  }'

응답 예시

HTTP/1.1 201 Created

{
  "id": 157,
  "status": "completed",
  "variables": {},
  "owner_id": 1,
  "progress": 1,
  "outputs_count": 2,
  "outputs": [
    {
      "component": {
        "name": "destination7",
        "type": "cloud_storage_destination_component",
            :
            :
      "url": "https://api.xplenty.com/xplenation/api/jobs/299/outputs/521"    },
    {
      "component": {
        "name": "destination7",
        "type": "cloud_storage_destination_component",
        "fields": [
          "id",
          "account_name"
        ]
      },
      "created_at": "2013-03-04T07:14:44Z",
      "id": 522,
          :
          :
    }
  ],
  "started_at": "2012-12-30T14:21:29Z",
  "created_at": "2012-12-30T14:21:18Z",
  "failed_at": null,
  "updated_at": "2012-12-30T14:29:29Z",
  "cluster_id": 52,
  "package_id": 434,
      :
      :
  "html_url": "https://xplenty.com/xplenation/jobs/157",
  "log_url": "https://api.xplenty.com/xplenation/api/jobs/157/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"
    }
}

4. 작업 초기화 및 완료 확인

실행한 작업의 id를 이용하여 해당 작업의 상태(status) 전환을 모니터링하여 completed 또는 failed가 될 때까지 이 API를 반복적으로 실행한다.
작업의 상태에 대해서는 잡 문서의 status 속성을 참고한다.

호출 예(curl call)

curl -X GET -u <API_KEY>: "https://api.xplenty.com/<Account_ID>/api/jobs/<job_id>" \
  -H "Accept: application/vnd.xplenty+json; version=2"

응답 예시

HTTP/1.1 200 OK

[
  {
    "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":
    {
        :
        :
    },
    "package": {
      "id": 2373,
          :
          :
    },
    "cluster": {
       "id": 99,
        :
    }
  }
]

5. 다음 작업들을 반복적으로 실행

cluster_id와 package_id를 적절히 바꾸면서 3-4단계를 반복한다.

6. 클러스터 종료

실행할 작업이 없어지면 지정된 클러스터를 종료한다.

호출 예(curl call)

curl -X DELETE -u <API_KEY>: "https://api.xplenty.com/<Account_ID>/api/clusters/<cluster_id>" \
  -H "Accept: application/vnd.xplenty+json; version=2"

응답 예시

HTTP/1.1 200 OK

{
  "id": 167,
  "name": "New Cluster",
  "description": "New Cluster Description",
  "status": "pending_terminate",
  "owner_id": 27,
  "plan_id": null,
  "nodes": 1,
  "type": "sandbox",
  "created_at": "2013-03-03T13:06:51Z",
  "updated_at": "2013-03-03T14:16:18Z",
  "available_since": "2013-03-03T13:09:22Z",
  "terminated_at": null,
  "running_jobs_count": 0,
  "terminate_on_idle": false,
    :
    :
  "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",
    "display_name": "Schedule 1",
    "id":1,
    "url": "https://api.xplenty.com/xplenation/api/schedules/1",
    "html_url": "https://xplenty.com/xplenation/schedules/1"
  }
}

7. 클러스터 종료 확인

해당 클러스터의 상태(status)가 terminated가 될 때까지 반복적으로 실행한다.

호출 예(curl call)

curl -X GET -u <API_KEY>: "https://api.xplenty.com/:account_id/api/clusters/:cluster_id" \
  -H "Accept: application/vnd.xplenty+json; version=2"

응답 예시

HTTP/1.1 200 OK

[
  {
    "id": 99,
    "name": "Daily Outliers Test #100",
    "description": "Daily Outliers Test",
    "status": "terminated",
    "owner_id": 27,
    "plan_id": 1,
    "nodes": 2,
    "type": "production",
    "created_at": "2013-01-25T08:18:39Z",
    "updated_at": "2013-01-28T16:45:24Z",
    "available_since": "2013-01-28T16:46:22Z",
    "terminated_at": "2013-01-28T17:45:33Z",
    "running_jobs_count": 0,
    "terminate_on_idle": false,
    "time_to_idle": 3600,
    "terminated_on_idle": false,
         :
         :
    }
]

마치며

이상으로 2회에 걸쳐 Xplenty가 제공하는 Rest API의 기능과 사용법에 대해 알아보았습니다.

Rest API를 사용하여 기존 시스템에 통합한 Xplenty를 사용해 보시는 건 어떨까요?
2주간 무료 트라이얼을 통해 Rest API를 마음껏 사용해 보실 수 있습니다.

ETL & Reverse ETL
Korean Knowledge Base

ETL & Reverse ETL Knowledge base

Xplenty 입문편

10 Articles

Xplenty 중급편

10 Articles

Xplenty 기타

11 Articles

Rest API의 활용

8 Articles

온프레미스(On-premise) 접속

1 Articles

스토리지

4 Articles

Salesforce

5 Articles

커넥터

3 Articles

사전정의 템플릿

4 Articles

중급 Part10：Xplenty의 Rest API로 기존 업무와의 연계(2)

들어가며

REST(ful) API에 대한 간단한 설명

REST API의 비조회용 메서드

Rest API를 통한 운영 예시

1. 클러스터 생성

2. 클러스터 초기화 확인

3. 작업 실행

4. 작업 초기화 및 완료 확인

5. 다음 작업들을 반복적으로 실행

6. 클러스터 종료

7. 클러스터 종료 확인

마치며

솔루션

서포트

회사안내

언어

ETL & Reverse ETL Korean Knowledge Base

ETL & Reverse ETL Knowledge base

Xplenty 입문편

10 Articles

Xplenty 중급편

10 Articles

Xplenty 기타

11 Articles

Rest API의 활용

8 Articles

온프레미스(On-premise) 접속

1 Articles

스토리지

4 Articles

Salesforce

5 Articles

커넥터

3 Articles

사전정의 템플릿

4 Articles

중급 Part10：Xplenty의 Rest API로 기존 업무와의 연계(2)

들어가며

REST(ful) API에 대한 간단한 설명

REST API의 비조회용 메서드

Rest API를 통한 운영 예시

1. 클러스터 생성

2. 클러스터 초기화 확인

3. 작업 실행

4. 작업 초기화 및 완료 확인

5. 다음 작업들을 반복적으로 실행

6. 클러스터 종료

7. 클러스터 종료 확인

마치며

See Also

솔루션

서포트

회사안내

언어

ETL & Reverse ETL
Korean Knowledge Base