SpaceONE API

SpaceONE API 소개

SpaceONE은 모든 기능을 Open API로 제공하고 있어 이를 통해 외부 시스템과 연동하거나 프로세스를 자동화할 수 있습니다.

API 사용 방법

1. 앱 생성
SpaceONE에서 API를 사용하려면 먼저 SpaceONE 콘솔에서 앱을 생성해야 합니다.
앱 생성 시 client_secret이 발급되며 이는 API 인증에 활용됩니다.

2. API 요청
REST API 요청 시, [1. 앱 생성]에서 발급받은 client_secret을 Bearer Token에 설정한 후 엔드포인트를 호출합니다.
SpaceONE에서 지원하고 있는 API 정보는 Swagger 또는 API 문서 를 통해 확인할 수 있습니다.

API 권한

SpaceONE은 총 3가지의 권한 체계를 제공하고 있습니다.

Domain Admin: 모든 자원 접근 가능
Workspace Owner: 워크스페이스 내 모든 자원 접근 가능
Workspace Member: 워크스페이스 내 지정한 프로젝트 자원만 접근 가능

ℹ️

Domain Admin 권한과 Workspace 권한은 앱의 생성 위치가 다르니 아래 가이드를 참조하여 진행하시기 바랍니다.

1. 앱 생성

앱을 생성한 뒤 발급되는 client_secret 정보를 Bearer Token으로 설정하여 API를 요청합니다.

1-1. Domain Admin 권한으로 앱 생성하기

Admin 모드로 전환

앱 생성하기

왼쪽 메뉴 탭에서 [사용자 및 접근 관리 > 앱]으로 이동한 뒤 [생성] 버튼을 클릭합니다.

그리고 이름, 역할과 태그를 설정한 뒤, [확인] 버튼 클릭합니다.

생성된 앱 토큰 복사

[Client ID] 항목에서 [더 보기]를 클릭합니다.
[더 보기]에서 client_secret 데이터를 복사하거나 [JSON 다운로드]로 다운로드합니다.

1-2. Workspace Owner & Workspace Member 권한으로 앱 생성하기

Admin 모드 종료 혹은 Workspace 모드 접속

만약 Admin 모드로 전환한 상태라면 종료하여 접근 가능한 워크스페이스로 이동합니다.

ℹ️

만약 Domain Admin 권한을 가지고 있지 않다면 해당 토글은 보이지 않습니다.

앱 생성하기

이름, 역할과 태그를 설정하여 앱을 생성합니다.
Workspace Member 권한으로 앱을 생성하려면 [프로젝트 할당] 토글을 클릭한 뒤 프로젝트 그룹 혹은 프로젝트를 선택합니다.

ℹ️

프로젝트 그룹 할당 시 해당 앱을 통해 하위에 존재하는 프로젝트까지 접근 가능합니다.

생성된 앱 토큰 복사

[Client ID] 항목에서 [더 보기]를 클릭합니다.
[더 보기]에서 client_secret 데이터를 복사하거나 [JSON 다운로드]로 다운로드합니다.

2. API 요청

2-1. REST API 호출

API 구조 및 구성 요소

SpaceONE의 API는 독자적인 API 포맷을 가지고 있습니다.

RESTful하지 않으며 verb를 통해 행위를 나타냅니다.
일부(service check, reflection 등)를 제외한 모든 API의 Method는 POST입니다.

요청을 보내기 위한 구성은 다음과 같습니다.

항목	값
Base URL	https://console-v2.kr1.api.spaceone.megazone.io
URL 포맷	/{`service`}/{`resource`}/{`verb`}
Method	`POST`
Header	Authorization: Bearer {`client_secret`}

ℹ️

URL 포맷의 각 항목은 다음과 같습니다.

service: 각 마이크로서비스 (e.g., Identity, Inventory 등)
resource: 마이크로서비스 내의 특정 자원 (e.g., Identity > Workspace, Inventory > Collector 등)
verb: 자원에 대해 수행할 작업 (e.g., create, get, list, delete 등)

예를 들어, inventory > collector > list는 Inventory 서비스의 Collector 리소스에 대한 목록을 조회하는 동작을 의미합니다.

REST API 요청 예시

CURL

curl -X 'POST' \
  'https://{Base URL}/{Service}/{Resource}/{Verb}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{<아래 API 문서 참고하여 적절한 데이터 입력>}'

Python

import requests

token = input("Enter your client secret (token): ")
base_url = input("Enter the base URL (e.g., https://www.example.com): ")

def dispatch_request(service:str, resource:str, verb:str, data:dict):
    url = f"{base_url}/{service}/{resource}/{verb}"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    return requests.post(url, headers=headers, json=data)

if __name__ == "__main__":
    response = dispatch_request(service="inventory", resource="region", verb="list", data={})
    print(response.json())

지원 API 확인

2-2. CLI를 사용하여 호출

cfctl은 SpaceONE 서비스와 상호작용하기 위해 설계된 강력한 CLI입니다. cfctl을 통해 SpaceONE 리소스를 원활하게 관리하고 제어할 수 있습니다.

ℹ️

cfctl 설치는 해당 가이드 문서를 참고해주세요.

도메인 주소 설정

도메인 주소를 {your_domain_url} 에 입력합니다.

$ cfctl setting init proxy {your_domain_url} --app

토큰 정보 입력

앱 생성을 통해 발급 받은 토큰을 {client_secret}에 입력합니다.

$ cfctl setting token {client_secret}

cfctl 실행

cfctl을 통해 SpaceONE의 자원과 상호작용하기 위해서 다음과 같은 구조로 명령어를 입력해야 합니다.

$ cfctl {service} {verb} {resource}

$ cfctl inventory list Region

Use Cases

자산 (Inventory) 조회 시나리오

1. Provider가 aws인 클라우드 서비스 조회

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {
    "page": {
      "start": 1,
      "limit": 10
    },
    "filter": [
      {
        "key": "provider",
        "value": "aws",
        "operator": "eq"
      },
      {
        "key": "cloud_service_group",
        "value": "EC2",
        "operator": "eq"
      },
      {
        "key": "cloud_service_type",
        "value": "Instance",
        "operator": "eq"
      }
    ]
  }
}'

Response

{
  "results": [
      {
          "cloud_service_id": "cloud-svc-11111111111111",
          "name": "service-bastion",
          "state": "ACTIVE",
          "ip_addresses": [
              "10.0.138.84"
          ],
          "account": "11111111111",
          "instance_type": "t3.micro",
          "cloud_service_type": "Instance",
          "cloud_service_group": "EC2",
          "provider": "aws",
          "data": {
              "os": {
                  "os_distro": "linux",
                  "os_arch": "x86_64",
                  "os_type": "LINUX",
                  "details": "Linux/UNIX"
              },
              "aws": {
                  "ami_id": "ami-1111111111111111",
                  "ami_launch_index": 0.0,
                  "kernel_id": null,
                  "monitoring_state": "disabled",
                  "ebs_optimized": true,
                  "ena_support": true,
                  "hypervisor": "xen",
                  "placement": {
                      "GroupName": "",
                      "Tenancy": "default",
                      "AvailabilityZone": "ap-northeast-2a"
                  },
                  "iam_instance_profile": {
                      "Arn": "arn:aws:iam::11111111111:instance-profile/ems-ec2-eks-bastion-role",
                      "Id": "AAAAAAAAAAAAAAAAAAAAAAA"
                  },
                  "root_volume_type": "gp3"
              },
              "hardware": {
                  "core": 2.0,
                  "memory": 1.0
              },
              "compute": {
                  "keypair": "",
                  "az": "ap-northeast-2a",
                  "instance_state": "STOPPED",
                  "instance_type": "t3.micro",
                  "launched_at": "2023-11-09T05:58:59",
                  "instance_id": "i-0322e4fe54dfa9f0f",
                  "instance_name": "obsv-service-bastion",
                  "security_groups": [
                      {
                          "name": "bastion-sg-01",
                          "id": "sg-1111111111",
                          "display": "bastion-sg-01 (sg-1111111111)"
                      }
                  ],
                  "image": "ec2-20231107-final",
                  "account": "11111111111"
              }
          },
          "reference": {
              "resource_id": "i-111111111111",
              "external_link": "https://ap-northeast-2.console.aws.amazon.com/ec2/v2/home?region=ap-northeast-2#Instances:instanceId=i-111111111111"
          },
          "tags": {
              "aws": {
                  "Name": "service-bastion"
              }
          },
          "tag_keys": {
              "aws": [
                  "Name"
              ]
          },
          "collection_info": {
              "service_account_id": "sa-11111113c43",
              "secret_id": "secret-aaa88e9e1110",
              "collector_id": "collector-afc8806f1485",
              "last_collected_at": "2024-12-17T06:32:56.922Z"
          },
          "region_code": "ap-northeast-2",
          "domain_id": "domain-1111111111",
          "workspace_id": "workspace-1111111111",
          "project_id": "project-11111111111",
          "created_at": "2024-12-17T06:32:56.922Z",
          "updated_at": "2024-12-17T06:32:56.922Z"
      }
  ] ... ,
  "total_count": 23
}

2. 출력된 자원(클라우드 서비스) 리스트 중 하나의 자원에 대한 정보 확인

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
	  "cloud_service_id": "cloud-svc-11111111111111"
	}'

Response

{
    "cloud_service_id": "cloud-svc-11111111111111",
    "name": "service-bastion",
    "state": "ACTIVE",
    "ip_addresses": [
        "10.0.138.84"
    ],
    "account": "11111111111",
    "instance_type": "t3.micro",
    "cloud_service_type": "Instance",
    "cloud_service_group": "EC2",
    "provider": "aws",
    "data": {
        "os": {
            "os_distro": "linux",
            "os_arch": "x86_64",
            "os_type": "LINUX",
            "details": "Linux/UNIX"
        },
        "aws": {
            "ami_id": "ami-1111111111111111",
            "ami_launch_index": 0.0,
            "kernel_id": null,
            "monitoring_state": "disabled",
            "ebs_optimized": true,
            "ena_support": true,
            "hypervisor": "xen",
            "placement": {
                "GroupName": "",
                "Tenancy": "default",
                "AvailabilityZone": "ap-northeast-2a"
            },
            "iam_instance_profile": {
                "Arn": "arn:aws:iam::11111111111:instance-profile/ems-ec2-eks-bastion-role",
                "Id": "AAAAAAAAAAAAAAAAAAAAAAA"
            },
            "root_volume_type": "gp3"
        },
        "hardware": {
            "core": 2.0,
            "memory": 1.0
        },
        "compute": {
            "keypair": "",
            "az": "ap-northeast-2a",
            "instance_state": "STOPPED",
            "instance_type": "t3.micro",
            "launched_at": "2023-11-09T05:58:59",
            "instance_id": "i-0322e4fe54dfa9f0f",
            "instance_name": "obsv-service-bastion",
            "security_groups": [
                {
                    "name": "bastion-sg-01",
                    "id": "sg-1111111111",
                    "display": "bastion-sg-01 (sg-1111111111)"
                }
            ],
            "image": "ec2-20231107-final",
            "account": "11111111111"
        }
    },
    "reference": {
        "resource_id": "i-111111111111",
        "external_link": "https://ap-northeast-2.console.aws.amazon.com/ec2/v2/home?region=ap-northeast-2#Instances:instanceId=i-111111111111"
    },
    "tags": {
        "aws": {
            "Name": "service-bastion"
        }
    },
    "tag_keys": {
        "aws": [
            "Name"
        ]
    },
    "collection_info": {
        "service_account_id": "sa-11111113c43",
        "secret_id": "secret-aaa88e9e1110",
        "collector_id": "collector-afc8806f1485",
        "last_collected_at": "2024-12-17T06:32:56.922Z"
    },
    "region_code": "ap-northeast-2",
    "domain_id": "domain-1111111111",
    "workspace_id": "workspace-1111111111",
    "project_id": "project-11111111111",
    "created_at": "2024-12-17T06:32:56.922Z",
    "updated_at": "2024-12-17T06:32:56.922Z"
}

3. 특정 Managed Tag가 존재하는 EC2관련 리소스 목록 조회

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {client_secret}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query":
    {
        "page":
        {
            "start": 1,
            "limit": 20
        },
        "filter":
        [
            {
                "k": "provider",
                "v": "aws",
                "o": "eq"
            },
            {
                "k": "cloud_service_group",
                "v": "EC2",
                "o": "eq"
            },
            {
                "k": "tags.aws.Created_by",
                "v": "wonny",
                "o": "eq"
            }
        ]
    }
}'

Response

{
    "results":
    [
        {
            "cloud_service_id": "cloud-svc-22222222",
            "name": "spaceone-instance",
            "state": "ACTIVE",
            "account": "111111111111",
            "provider": "aws",
            "data":
            {
                "compute":
                {
                    "az": "ap-northeast-2b",
                    "instance_type": "t3.xlarge",
                    "instance_state": "RUNNING"
                },
                "os":
                {
                    "os_distro": "amazonlinux"
                },
                "hardware":
                {
                    "core": 4.0,
                    "memory": 16.0
                },
                "primary_ip_address": ""
            },
            "reference":
            {
                "resource_id": "i-0111111111",
                "external_link": ""
            },
            "tags":
            {
                "aws":
                {
                   
                    "Created_by": "wonny"
                }
            },
            "tag_keys":
            {},
            "collection_info":
            {},
            "region_code": "ap-northeast-2",
            "project_id": "project-111111111",
            "updated_at": "2025-01-01T09:56:56.256Z"
        }
    ],
    ...
    "total_count": 2
}

4. SecurityGroup(SG)중 EC2에서 사용중인 SG 목록 조회

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {client_secret}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query":
    {
        "page":
        {
            "start": 1,
            "limit": 20
        },
        "only":
        [
            "name",
            "state",
            "data.instances"
        ],
        "filter":
        [
            {
                "k": "provider",
                "v": "aws",
                "o": "eq"
            },
            {
                "k": "cloud_service_group",
                "v": "EC2",
                "o": "eq"
            },
            {
                "k": "cloud_service_type",
                "v": "SecurityGroup",
                "o": "eq"
            },
            {
            	"k": "data.instances",
            	"v": [null, []],
            	"o": "not_in"
            }
        ]
    }
}'

Response

{
  "results": [
    {
      "name": "ems-eks-bastion-sg-01",
      "state": "ACTIVE",
      "data": {
        "instances": [
          {
            "SubnetId": "subnet-111111111111",
            "PrivateIpAddress": "10.0.0.0",
            "PrivateDnsName": "ip-10-0-0-0.ap-northeast-1.compute.internal",
            "VpcId": "vpc-11111111111",
            "Tags": [
              {
                "Key": "Name"
              }
            ],
            "Architecture": "x86_64",
            "InstanceId": "i-11111111111",
            "PublicDnsName": "amazonaws.com",
            "State": {
              "Name": "running"
            },
            "PublicIpAddress": "",
            "instance_name": "spaceone-instance",
            "SecurityGroups": [
              {
                "GroupName": "sg-01",
                "GroupId": "sg-11111111111"
              }
            ]
          }
        ]
      },
      "tags": {},
      "tag_keys": {},
      "collection_info": {}
    }
  ],
  ...
  "total_count": 10
}

비용 (Cost Analysis) 조회 시나리오

1. Data Source 조회

Request

curl -X 'POST' \
  'https://{Base URL}/cost-analysis/data-source/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {}
}'

Response

{
  "results": [
    {
      "data_source_id": "string",
      "name": "string",
      "state": "string",
      "data_source_type": "string",
      "permissions": {},
      "provider": "string",
      "secret_type": "string",
      "secret_filter": {
        "state": "string",
        "secrets": [
          "string"
        ],
        "service_accounts": [
          "string"
        ],
        "schemas": [
          "string"
        ]
      },
      ...
      ...
      "data_source_account_count": 0,
      "connected_workspace_count": 0,
      "resource_group": "string",
      "domain_id": "string",
      "workspace_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "last_synchronized_at": "string"
    }
  ],
  "total_count": 4
}

2. 조회한 정보에서 특정 Data Source가 특정 날짜에 수집한 비용 정보들 조회

Request

curl -X 'POST' \
  'https://<Base URL>/cost-analysis/cost/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {
    "filter": [
      {
        "key": "data_source_id",
        "value": "ds-a8cac8e9c7c8",
        "operator": "eq"
      },
      {
	      "key": "billed_date",
	      "value": "2024-12-16",
	      "operator": "eq"
      }
    ]
  }
}'

Response

{
  "results": [
    {
      "cost_id": "string",
      "cost": "string",
      "usage_quantity": "string",
      "usage_unit": "string",
      "provider": "string",
      "region_code": "string",
      "region_key": "string",
      "product": "string",
      "usage_type": "string",
      "resource": "string",
      "tags": {},
      "additional_info": {},
      "data": {},
      "domain_id": "string",
      "workspace_id": "string",
      "project_id": "string",
      "service_account_id": "string",
      "data_source_id": "string",
      "account_id": "string",
      "billed_year": "string",
      "billed_month": "string",
      "billed_date": "string"
    },
    ...
    ...
  ],
  "total_count": 356
}

SpaceONE 설치