Resource Explorer API

주요 정보

IAM 역할 관리

Resource Explorer 서비스의 역할 관리는 카카오클라우드의 IAM 역할 기반 액세스 제어(RBAC)을 따릅니다. 사용자 토큰으로 프로젝트 역할을 체크하고 각 역할에 따라 API 사용 권한이 부여됩니다.

프로젝트 역할

권한	프로젝트 관리자(Admin)	프로젝트 멤버(Member)	프로젝트 리더(Reader)
리소스 조회	✓	✓	✓
태그 조회	✓	✓	✓
태그 생성/삭제	✓	✓
태그 지정	✓	✓

KCRN

Kakaocloud Resource Name의 약자로 카카오클라우드 리소스에 부여한 고유값을 말합니다. KCRN이 부여된 리소스를 Resource Explorer에서 한 번에 조회하고 다양한 방식으로 리소스 탐색이 가능합니다.

형식	설명
kcrn:region:project-id:service:resource-type:resource-id	kcrn:으로 시작하며 리전, 프로젝트 ID, 서비스, 리소스 유형, 리소스 ID 값을 포함

안내

Resource Explorer에서 조회 가능한 리소스 유형은 지원 중인 리소스 유형을 참고하시기 바랍니다.

리소스

리소스 생성 또는 삭제 직후에는 Resource Explorer에 해당 변경 사항이 반영되기까지 일정 시간이 소요될 수 있습니다.
리소스 관련 API는 다음과 같습니다.

리소스 조회

리소스는 KCRN 포맷으로 조회 하거나 필터로 조회할 수 있습니다.

API 호출 방식

메서드	요청 URL
POST	https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/resources/search

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력
Content-Type	string	필수	항상 application/json으로 설정

Request Body(KCRN 포맷으로 조회)

KCRN 포맷으로 리소스를 조회할 수 있습니다.

KCRN 포맷으로 리소스 조회 Request Body

{
  "filter": {     
    "filter_kcrn": "kcrn:*:91e6b4bf1ac441eaa99ba7802e64970c:Virtual Machine:Instance:*"   
  } 
}

Request Elements

필드명	유형	필수 여부	설명
filter	object	선택	리소스 조회 시 사용할 필터 조건을 포함하는 객체입니다. 내부에 filter_kcrn을 지정하여 kcrn 포맷으로 리소스를 조회할 수 있습니다.
filter.filter_kcrn	string	선택	kcrn:region:project-id:service:resource-type:resource-id 형식의 KCRN 포맷을 기반으로 리소스를 필터링 합니다. 와일드카드(*)를 사용하여 특정 항목을 범위로 지정할 수 있습니다. - 위 Request Body 예시는 특정 프로젝트에서 Virtual Machine 서비스의 Instance 리소스 전체를 조회하는 조건

Request Body(필터로 조회)

다양한 필터 항목으로 리소스를 조회할 수 있습니다.

필터로 리소스 조회 Request Body

{     
  "filter": {         
    "filter_string": "string"     
  },     
  "offset": 0, # optional     
  "limit": 10, # optional (max, default 500)     
  "sort": "string" # optional
}

Request Elements

필드명	유형	필수 여부	설명
filter	object	선택	리소스 조회 시 사용할 필터 조건들을 포함하는 객체입니다. - 필터 없이 전체 리소스를 조회하는 것이 가능합니다.
filter.filter_string	string	선택	리소스를 조회할 때 사용할 검색 필터 조건을 문자열 형태로 지정하는 파라미터입니다. 특정 서비스나 태그가 지정된 리소스만 조회하고 싶을 때 사용할 수 있습니다. - 형식: “키=값” - 예시: service=Virtual Machine → Virtual Machine 서비스만 조회 - 지원하는 필터 항목은 filter_string 항목 참고
offset	integer	선택	검색 결과 목록에서 가져올 데이터의 인덱스를 지정하는 파라미터입니다. 예를 들어 offset을 0으로 설정하면 첫 번째 결과부터, 10으로 설정하면 11번째 결과부터 데이터를 반환합니다. - 기본값: 0
limit	integer	선택	한 번의 요청에서 최대 몇 개의 리소스를 반환할 지 설정하는 값입니다. 조회 결과가 많을 경우 offset과 함께 사용하여 페이지 단위로 리소스를 나누어 조회할 수 있습니다. - 기본값: 500 - 최대값: 500 - 예시: limit: 10 → 최대 10개의 리소스만 반환
sort	string	선택	결과 리스트를 정렬할 때 사용하는 파라미터입니다. - 형식: +정렬기준(오름차순) 또는 -정렬기준(내림차순) - 예시: +resource_id → 리소스 ID 기준으로 오름차순 정렬 - 지원하는 정렬 기준은 sort 항목 참고

filter_string 항목

리소스 조회 시 사용 가능한 필터 항목입니다. 여러 조건을 지정하면 논리곱(AND)으로 동작합니다.

키	유형	검색 지원	필수 여부	설명
resource_name	string	exact, not, contains, start with, end with, *	선택	리소스 이름으로 조회합니다. 예시: - exact: resource_name=myResource - not: -resource_name=myResource - contains: resource_name=*my* - start with: resource_name=my* - end with: resource_name=*my - *: resource_name=* → 모든 리소스 조회
resource_id	string	exact, not, contains, start with, end with, *	선택	리소스 ID로 조회합니다. 예시: - exact: resource_id=63cbe932-3a14-4d39-a24e-ed2fa28cc410 - not: -resource_id=63cbe932-3a14-4d39-a24e-ed2fa28cc410 - contains: resource_id=*3a14* - start with: resource_id=3a14* - end with: resource_id=*3a14 - *: resource_id=* → 모든 리소스 조회
region	string	exact, not, *	선택	리전으로 조회합니다. 예시: - exact: region=kr-central-2 - not: -region=kr-central-2 - *: region=* → 모든 리전의 리소스 조회
service	string	exact, not, *	선택	서비스로 조회합니다. 예시: - exact: service=Virtual Machine - not: -service=Virtual Machine - *: service=* → 모든 서비스의 리소스 조회
resource_type	string	exact, not, *	선택	리소스 유형으로 조회합니다. 예시: - exact: resource_type=Instance - not: -resource_type=Instance - *: resource_type=* → 모든 리소스 유형의 리소스 조회
tag.key	string	exact, not, *	선택	태그 키로 조회합니다. 예시: - exact: tag.key=myKey - not: -tag.key=myKey - *: tag.key=* → 태그가 있는 리소스 조회
tag.value	string	exact, not, *	선택	태그 값으로 조회합니다. 예시: - exact: tag.value=myValue - not: -tag.value=myValue - *: tag.value=* → 태그가 있는 리소스 조회
기타	-	-	선택	태그 유무로 조회합니다. 예시: - tag:all → 태그가 있는 리소스 조회 - tag:none → 태그가 없는 리소스 조회

sort 항목

항목	검색 지원 및 예시
resource_name	- 오름차순: +resource_name - 내림차순: -resource_name
resource_id	- 오름차순: +resource_id - 내림차순: -resource_id
resource_type	- 오름차순: +resource_type - 내림차순: -resource_type
service	- 오름차순: +service - 내림차순: -service

Response Body

리소스 조회 Response Body

{
  "success": boolean,
  "resources": [
    {
      "kcrn": "string",
      "project_id": "string",
      "region": "string",
      "resource_type": "string",
      "service": "string",
      "resource_id": "string",
      "resource_name": "string",
      "user_name": "string",
      "tags": [
        {
          "tag_id": "string",
          "key": "string",
          "value": "string",
          "type": "string"
        }
      ]
    }
  ],
  "count": integer,
  "total_count": integer
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false
resources	list	조회된 리소스 객체 목록입니다. 각 항목은 리소스 하나에 대한 정보를 포함합니다.
resources[].kcrn	string	리소스의 고유 식별자(KakaoCloud Resource Name)입니다.
resources[].project_id	string	리소스가 속한 프로젝트의 ID입니다.
resources[].region	string	리소스가 위치한 리전 정보입니다.
resources[].resource_type	string	리소스의 유형입니다. - 예: Instance, Volume 등
resources[].service	string	해당 리소스를 제공하는 서비스 이름입니다. - 예: Virtual Machine
resources[].resource_id	string	리소스의 고유 ID입니다.
resources[].resource_name	string	사용자가 설정한 리소스 이름 또는 서비스에서 지정한 리소스 이름입니다.
resources[].user_name	string	해당 리소스를 생성한 사용자 계정 또는 서비스 에이전트입니다.
resources[].tags	list	리소스에 연결된 태그 목록입니다.
resources[].tags[].tag_id	string	태그의 고유 ID입니다.
resources[].tags[].key	string	태그의 키입니다.
resources[].tags[].value	string	태그의 값입니다.
resources[].tags[].type	string	태그의 유형입니다. - 커스텀 태그: custom - 시스템 태그: system
count	integer	이번 요청에서 반환된 리소스 수 입니다.
total_count	integer	필터 조건에 해당하는 전체 리소스 수 입니다.

상태 코드

코드	응답 내용	설명
200	OK	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

태그 조회

새로 생성한 태그 또는 삭제한 태그가 Resource Explorer 태그 목록에 반영되는 데 까지는 일정 시간이 소요될 수 있습니다.
태그 조회 관련 API는 다음과 같습니다.

안내

커스텀 태그에만 tag_id가 부여되며, 시스템 태그에는 tag_id가 존재하지 않습니다.

태그 다건 조회

API 호출 방식

메서드	요청 URL
POST	https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/tags/search

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력
Content-Type	string	필수	항상 application/json으로 설정

Request Body

태그 다건 조회 Request Body

{
  "filter": { 
    "filter_string": "string" 
  }, 
  "offset": integer, # optional 
  "limit": integer, # optional 
  "sort": "string" # optional
}

Request Elements

필드명	유형	필수 여부	설명
filter	object	선택	태그 조회 시 사용할 필터 조건들을 포함하는 객체입니다. 내부에 filter_string을 포함하며 다양한 필터 조건을 지정할 수 있습니다. - 필터 없이 전체 태그를 조회하는 것이 가능합니다.
filter.filter_string	string	선택	태그를 조회할 때 사용할 필터 조건을 문자열 형태로 지정합니다. - 예: tag.type=system&tag.value=Kubernetes Engine처럼 특정 태그 정보 기준으로 조회가 가능하며 조건이 여러 개인 경우 논리곱(AND)으로 처리됩니다. - 지원하는 필터 항목은 filter_string 항목 참고
offset	integer	선택	검색 결과 목록에서 가져올 데이터의 인덱스를 지정하는 파라미터입니다. 예를 들어 offset을 0으로 설정하면 첫 번째 결과부터, 10으로 설정하면 11번째 결과부터 데이터를 반환합니다. - 기본값: 0
limit	integer	선택	한 번의 요청에서 최대 몇 개의 리소스를 반환할 지 설정하는 값입니다. 조회 결과가 많을 경우 offset과 함께 사용하여 페이지 단위로 리소스를 나누어 조회할 수 있습니다. - 기본값: 500 - 최대값: 500 - 예시: limit: 10 → 최대 10개의 리소스만 반환
sort	integer	선택	결과 리스트를 정렬할 때 사용하는 파라미터입니다. - 형식: +정렬기준(오름차순) 또는 -정렬기준(내림차순) - 예시: +key → 태그 키 기준으로 오름차순 정렬 - 지원하는 정렬 기준은 sort 항목 참고

filter_string 항목

태그 다건 조회 시 사용 가능한 필터 항목입니다. 여러 조건을 지정하면 논리곱(AND)으로 동작합니다.

키	유형	검색 지원	필수 여부	설명
tag.key	string	exact, not, *	선택	태그 키로 조회합니다. 예시: - exact: tag.key=myKey - not: -tag.key=myKey - *: tag.key=* → 모든 태그 조회
tag.value	string	exact, not, *	선택	태그 값으로 조회합니다. 예시: - exact: tag.value=myValue - not: -tag.value=myValue - *: tag.value=* → 모든 태그 조회
tag.type	string	exact, not, *	선택	태그 유형으로 조회합니다. 태그 유형에는 시스템 태그(system)와 커스텀 태그(custom)가 있습니다. 예시: - exact: tag.type=system - not: -tag.type=system - *: tag.type=* → 모든 태그 조회
기타	-	-	선택	태그 사용 유무로 조회합니다. 예시: - tag:in_use → 리소스에 연결된 태그 - tag:not_in_use → 리소스에 연결되지 않은 태그

sort 항목

항목	검색 지원 및 예시
tag.key	- 오름차순: +tag.key - 내림차순: -tag.key
tag.value	- 오름차순: +tag.value - 내림차순: -tag.value
tag.type	- 오름차순: +tag.type - 내림차순: -tag.type
tag.created_at	- 오름차순: +tag.created_at - 내림차순: -tag.created_at

Response Body

태그 다건 조회 Response Body

{ 
  "success": boolean,
  "total_count": integer,
  "count": integer,
  "tags": [ 
            { 
              "tag_id": "string",
              "key": "string",
              "value": "string",
              "type": "string",
              "created_at": "string",
              "resource_count": integer
            }
          ]
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false
total_count	integer	조건에 해당하는 전체 태그의 총 개수를 나타냅니다.
count	integer	현재 응답에 포함된 태그의 개수입니다. 페이지네이션(offset, limit)이 적용된 경우 일부만 반환됩니다.
tags	list	태그 객체 목록입니다.
tags[].tag_id	string	태그의 고유 ID입니다.
tags[].key	string	태그의 키입니다.
tags[].value	string	태그의 값입니다.
tags[].type	string	태그의 유형입니다. - 커스텀 태그: custom - 시스템 태그: system
tags[].created_at	string	태그가 생성된 시간입니다. - ISO 8601 형식의 UTC 타임스탬프 - 예시: 2025-03-17T05:46:52.537490588Z
tags[].resource_count	integer	해당 태그가 연결된 리소스의 개수입니다.

상태 코드

코드	응답 내용	설명
200	OK	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

태그 단건 조회

API 호출 방식

메서드	요청 URL
GET	https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/tags/search/{tag_id}

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력

Request

태그 단건 조회 Request 예시

curl --location --request GET 'https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/tags/search/{tag_id}' \
--header 'X-Auth-Token: {x-auth-token}'

Request Body

태그 단건 조회 Request Body

이 API는 요청 본문을 사용하지 않습니다.

Request Elements

필드명	위치	필수 여부	설명
tag_id	path	필수	조회하고자 하는 태그의 고유 ID입니다.
X-Auth-Token	header	필수	사용자 인증 토큰 입력 - 이 값을 사용하는 경우 Credential-ID 및 Credential-Secret은 생략합니다.

Response Body

태그 단건 조회 Response Body

{ 
  "success": boolean,
  "tag": {
    "tag_id": "string", 
    "key": "string", 
    "value": "string", 
    "type": "string", 
    "created_at": "string" 
  } 
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false
tag	object	반환된 태그 정보를 담는 객체입니다.
tag.tag_id	string	태그의 고유 ID입니다.
tag.key	string	태그의 키입니다.
tag.value	string	태그의 값입니다.
tag.type	string	태그의 유형입니다. - 커스텀 태그: custom - 시스템 태그: system
tag.created_at	string	태그가 생성된 시간입니다. - ISO 8601 형식의 UTC 타임스탬프 - 예시: 2025-03-17T05:46:52.537490588Z

상태 코드

코드	응답 내용	설명
200	OK	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
404	Not Found	존재하지 않는 태그 - tag_id 정보 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

태그 관리

태그 생성 및 삭제 관련 API는 다음과 같습니다.

태그 생성

태그는 한 번에 최대 100개까지 생성할 수 있습니다. 태그 생성이나 삭제 요청은 비동기 방식으로 처리되며 완료되기까지 일정 시간이 소요될 수 있습니다.
또한 태그 생성·삭제 또는 리소스에 태그를 지정하는 작업이 진행 중인 경우 해당 작업이 모두 완료된 이후에만 다음 요청을 처리할 수 있습니다.

API 호출 방식

메서드	요청 URL
POST	https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/tags

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력
Content-Type	string	필수	항상 application/json으로 설정

Request Body

태그 생성 Request Body

{ 
  "tags": [
    { 
      "key": "string", 
      "value": "string" 
    } 
  ] 
}

Request Elements

필드명	유형	필수 여부	설명
tags	list	필수	생성할 태그 객체들의 목록입니다. 한 번에 최대 100개 태그를 동시에 생성할 수 있습니다.
tags[].key	string	필수	태그의 키입니다.
tags[].value	string	필수	태그의 값입니다.

Response Body

태그 생성 Response Body

{ 
  "success": boolean,
  "tags": [
      {
          "tag_id": "string"
          "key": "string"
          "value": "string"
      }
  ]
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false
tags	list	생성된 태그 목록입니다.
tags[].tag_id	string	생성된 태그의 고유 ID 입니다.
tags[].key	string	생성된 태그의 키입니다.
tags[].value	string	생성된 태그의 값입니다.

상태 코드

코드	응답 내용	설명
202	Accepted	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

태그 삭제

더 이상 사용하지 않는 태그를 삭제할 수 있습니다. 태그는 한 번에 최대 100개까지 삭제할 수 있습니다. 태그 생성이나 삭제 요청은 비동기 방식으로 처리되며 완료되기까지 일정 시간이 소요될 수 있습니다.
또한 태그 생성·삭제 또는 리소스에 태그를 지정하는 작업이 진행 중인 경우 해당 작업이 모두 완료된 이후에만 다음 요청을 처리할 수 있습니다.

API 호출 방식

메서드	요청 URL
POST	https://resource-explorer.kr-central-2.kakaocloud.com/console/api/v1/tags/delete

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력
Content-Type	string	필수	항상 application/json으로 설정

Request Body

태그 삭제 Request Body

{ 
  "tag_ids": [
    "string"
  ] 
}

Request Elements

필드명	유형	필수 여부	설명
tag_ids	list	필수	삭제할 태그 ID들의 목록입니다. 한 번에 최대 100개 태그를 동시에 삭제할 수 있습니다.
tag_ids[]	string	필수	개별 태그의 고유 ID입니다. 존재하지 않는 ID는 에러로 처리됩니다.

Response Body

태그 생성 Response Body

{ 
  "success": boolean
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false

상태 코드

코드	응답 내용	설명
202	OK	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망

태그 지정

태그 지정 작업을 통해 특정 리소스에 원하는 태그를 연결할 수 있습니다. 이 작업은 비동기적으로 처리되며 완료까지 시간이 소요될 수 있습니다.
또한 태그 생성·삭제 또는 리소스에 태그를 지정하는 작업이 진행 중인 경우 해당 작업이 모두 완료된 이후에만 다음 요청을 처리할 수 있습니다.

안내

커스텀 태그에만 tag_id가 부여되며, 시스템 태그에는 tag_id가 존재하지 않습니다.

API 호출 방식

메서드	요청 URL
PATCH	https://resource-explorer.kr-central-2.kakaocloud.com/api/v1/tags

Request Header

Request Header	유형	필수 여부	설명
X-Auth-Token	string	필수	사용자 인증 토큰 입력
Content-Type	string	필수	항상 application/json으로 설정

Request Body

태그 지정 Request Body

{ 
  "kcrns": ["string"],
  "connect_tag_ids": ["string"],
  "disconnect_tag_ids": ["string"]
}

Request Elements

필드명	유형	필수 여부	설명
kcrns	list	필수	태그를 지정할 리소스의 KCRN(KakaoCloud Resource Name)의 배열입니다. - 여러 리소스에 동시에 태그 지정이 가능합니다.
connect_tag_ids	list	필수	연결할 태그의 ID 목록입니다. - 지정된 태그가 리소스에 연결됩니다.
disconnect_tag_ids	list	필수	해제할 태그의 ID 목록입니다. - 지정된 태그가 리소스에서 제거됩니다.

Response Body

태그 생성 Response Body

{ 
  "success": boolean
}

Response Elements

필드명	유형	설명
success	boolean	API 요청의 성공 여부를 나타냅니다. - true, false

상태 코드

코드	응답 내용	설명
202	OK	성공
400	Bad Request	유효하지 않은 요청 - 에러 메시지를 참고하여 요청 수정
403	Forbidden	인증은 성공했으나 요청한 리소스 또는 작업에 대한 권한 없음 - 올바른 권한이 부여된 계정 또는 프로젝트로 요청했는지 확인 요망
500	Internal Server Error	내부 서버 에러 - 잠시 후 재요청 요망