Google Cloud

구독
다운로드 0
업데이트 2026. 10. 20.

gcp-projects

Cloud Resource Manager API로 Google Cloud 프로젝트를 검색합니다.

문법

gcp-projects [profile=STRING] [scope=STRING] [query=STRING] [limit=INT]

옵션

profile=STRING
선택 옵션. Google Cloud 접속 프로파일 식별자. 쉼표로 여러 개를 지정하면 프로파일마다 차례로 조회하고 profile 필드로 구분합니다. 생략하면 사용 권한이 있는 모든 Google Cloud 접속 프로파일로 조회합니다. 조회 중 한 프로파일에서 오류가 나면 그때까지 출력한 결과는 남고, 나머지 프로파일은 조회하지 않은 채 쿼리가 오류로 끝납니다.
scope=STRING
선택 옵션. folders/폴더번호 또는 organizations/조직번호. 바로 아래 프로젝트만 조회하며 하위 폴더의 프로젝트는 제외합니다. 생략하면 서비스 계정이 접근할 수 있는 모든 프로젝트를 조회하며, 다른 조직의 프로젝트도 포함될 수 있습니다.
query=STRING
선택 옵션. Resource Manager 검색식. 예: state:ACTIVE, id:my-project*, labels.env:prod. 필드 없이 단어만 쓰는 검색은 지원하지 않습니다. 검색식 문법은 projects.search 문서의 query 항목을 참고합니다.
limit=INT
선택 옵션. 프로파일별 최대 출력 건수. 1 이상의 정수. 생략하면 전체를 조회합니다.

출력 필드

필드타입이름설명
profile문자열프로파일접속 프로파일 이름
project_id문자열프로젝트 ID사용자가 지정한 프로젝트 ID. 예: my-project-123456
display_name문자열표시 이름프로젝트 표시 이름
state문자열상태ACTIVE 또는 DELETE_REQUESTED
parent문자열상위 자원folders/{번호} 또는 organizations/{번호}
project_number문자열프로젝트 번호시스템이 발급한 프로젝트 번호. 예: 345678901234
labels맵라벨사용자 정의 라벨
create_time날짜생성 시각프로젝트 생성 시각
update_time날짜수정 시각프로젝트 최종 수정 시각
delete_time날짜삭제 요청 시각프로젝트 삭제가 요청된 시각

오류 코드

파싱 오류

오류 메시지원인해결
사용 가능한 Google Cloud 프로파일이 없습니다.프로파일 식별자가 틀렸거나 사용 권한이 없음profile 옵션에 접속 프로파일 식별자 입력, 프로파일 사용 권한 확인
scope 형식이 올바르지 않습니다: {scope}scope 형식 오류, 또는 projects/를 지정함folders/폴더번호 또는 organizations/조직번호 입력
limit은 양의 정수여야 합니다: {limit}limit이 0 이하이거나 숫자가 아님1 이상의 정수 입력

런타임 오류

오류 메시지원인해결
HTTP 403: PERMISSION_DENIED - The caller does not have permissionscope로 지정한 폴더·조직에 권한이 없음해당 범위에 탐색자 역할 부여
HTTP 403: PERMISSION_DENIED - Cloud Resource Manager API has not been used in project ...서비스 계정 프로젝트에서 Cloud Resource Manager API 미사용 설정서비스 계정이 속한 프로젝트에서 Cloud Resource Manager API 사용 설정
HTTP 400: INVALID_ARGUMENT - field [query] has issue [...]검색식 문법 오류, 지원하지 않는 필드, 필드 없는 단어 검색필드:값 형식으로 수정. 예: name:my-project*
token exchange failed, HTTP 400: Invalid grantJSON 키 오류, 서비스 계정·키 삭제새 키를 발급해 접속 프로파일 수정

설명

Cloud Resource Manager API v3의 projects:search로 서비스 계정이 resourcemanager.projects.get 권한을 가진 프로젝트를 검색합니다. 권한이 없는 프로젝트는 오류 없이 결과에서 빠집니다. 결과가 0건이면 서비스 계정에 탐색자 역할이 있는지 gcp-check-permissions로 확인합니다.

scope를 지정하면 그 폴더·조직의 바로 아래 프로젝트만 나옵니다. Resource Manager의 검색이 직속 상위(parent) 일치만 지원하기 때문입니다. 하위 폴더 안까지 포함한 조직 전체 프로젝트는 gcp-assets에 types=cloudresourcemanager.googleapis.com/Project를 지정해 조회합니다.

query와 scope를 함께 지정하면 query는 Google Cloud로 전달하고 scope는 결과에서 거릅니다. Resource Manager 검색식은 조건을 여러 개 쓰면 하나라도 맞는 것을 돌려주기 때문입니다.

프로젝트 정보는 gcp-assets에 types=cloudresourcemanager.googleapis.com/Project를 지정해도 조회할 수 있습니다. 상황에 따라 다음과 같이 선택합니다.

상황권장 명령어
조직 하나의 전체 프로젝트를 소속 폴더·태그와 함께 조회gcp-assets (조직 수준 Cloud 애셋 뷰어 역할 필요)
조직이 없거나 여러 조직에 걸친 프로젝트를 한 번에 조회gcp-projects (scope 생략)
서비스 계정이 접근할 수 있는 프로젝트 확인, 삭제 요청 시각 확인gcp-projects
Note
새로 만든 프로젝트나 방금 부여한 역할은 몇 분 뒤에 검색 결과에 나올 수 있습니다. 프로젝트 태그는 이 명령어로 조회되지 않으므로 gcp-assets의 tags, effective_tags를 사용합니다.

사용 예

예시: 접근 가능한 프로젝트 목록

상황: 서비스 계정이 조회할 수 있는 프로젝트와 소속을 확인합니다.

gcp-projects profile=gcp
| fields project_id, project_number, display_name, parent, state, create_time

예상 결과:

project_idproject_numberdisplay_nameparentstatecreate_time
my-project-123456345678901234My Projectorganizations/123456789012ACTIVE2026-10-06 14:42:46+0900
test-project-234567456789012345Test Projectfolders/234567890123ACTIVE2026-10-15 11:22:13+0900

결과 해석: parent로 프로젝트가 조직 직속인지 폴더 아래인지 알 수 있습니다.

예시: 폴더 바로 아래의 활성 프로젝트

상황: 특정 폴더 바로 아래에서 활성 상태인 프로젝트만 봅니다.

gcp-projects profile=gcp scope=folders/234567890123 query="state:ACTIVE"
| fields project_id, display_name, state

결과 해석: 삭제 요청된(DELETE_REQUESTED) 프로젝트는 빠집니다. 하위 폴더의 프로젝트는 나오지 않습니다.