Gemini

Google 계정을 한 번 연결해 Gemini Code Assist 사용량과 Gemini Enterprise 라이선스 현황을 심플리에서 확인하는 방법을 안내합니다.

Gemini

Gemini를 연동하면 Gemini Code Assist 사용량과 Gemini Enterprise 라이선스 현황을 한 대시보드에서 확인할 수 있습니다. Google 계정을 한 번 연결하면 심플리가 그 계정으로 조회할 수 있는 결제 계정과 GCP 프로젝트를 자동으로 찾습니다. 서비스 계정을 추가하거나 프로젝트 ID를 직접 입력할 필요가 없습니다.

확인할 정보	대시보드 탭
활성 사용자, 코드 제안과 승인, 채팅, 토큰 사용량	Code Assist
청구 계정, 라이선스 배정 상태, 마지막 로그인	Enterprise

1. 연동할 Google 계정과 결제 계정 준비

연동할 결제 계정과 프로젝트를 모두 조회할 수 있는 Google 계정을 선택해야 합니다. 프로젝트 소유자 계정이더라도 결제 계정 권한이 없으면 프로젝트를 자동으로 찾지 못할 수 있습니다.

권한을 부여할 곳	필요한 IAM 권한	사용할 수 있는 역할 예시
각 Cloud Billing 결제 계정	`billing.accounts.get`, `billing.resourceAssociations.list`	Billing Account Viewer (`roles/billing.viewer`)
각 Code Assist 프로젝트	`monitoring.timeSeries.list`	Monitoring Viewer (`roles/monitoring.viewer`)
Enterprise 라이선스가 있는 결제 계정	`discoveryengine.billingAccountLicenseConfigs.list`	해당 권한을 포함한 조직 수준 사용자 지정 역할
각 Enterprise 프로젝트	`discoveryengine.userStores.listUserLicenses`	Gemini Enterprise Admin (`roles/discoveryengine.agentspaceAdmin`)
API 요청에 사용할 각 프로젝트	`serviceusage.services.use`	Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)

가장 좁은 권한만 부여하려면 표의 IAM 권한으로 사용자 지정 역할을 만드세요. discoveryengine.billingAccountLicenseConfigs.list는 결제 계정에 대해 평가되므로 프로젝트 역할만 부여해서는 부족합니다. 조직에서 이미 Gemini Enterprise 관리 역할을 운영하고 있다면 그 역할이 결제 계정과 프로젝트를 모두 포괄하는지 확인하세요.

MSP를 통해 Google Cloud를 이용해도 연동할 수 있습니다. 다만 MSP가 결제 계정을 관리해 고객 계정에 billing.resourceAssociations.list 또는 discoveryengine.billingAccountLicenseConfigs.list를 부여하지 않았다면, MSP 관리자에게 해당 조회 권한을 요청해야 합니다.

2. 필요한 API 활성화

심플리가 자동으로 찾을 각 GCP 프로젝트에서 다음 API를 활성화합니다.

API	서비스 이름	용도
Cloud Monitoring API	`monitoring.googleapis.com`	Gemini Code Assist 사용량 메트릭 조회
Discovery Engine API	`discoveryengine.googleapis.com`	연결된 결제 계정의 구매 라이선스와 프로젝트의 사용자 라이선스 조회

Enterprise 라이선스의 소유 단위는 결제 계정이지만, Discovery Engine API 호출에는 결제 계정에 연결된 GCP 프로젝트가 할당량·과금 프로젝트로 필요합니다. 따라서 그 프로젝트에 활성 결제 계정을 연결하고 Discovery Engine API를 활성화해야 합니다. API를 활성화하는 계정에는 프로젝트의 Service Usage Admin (roles/serviceusage.serviceUsageAdmin) 역할이 필요합니다.

Google Cloud Console에서 활성화

API 라이브러리로 이동합니다.
화면 상단에서 연동할 프로젝트를 선택합니다.
Cloud Monitoring API를 검색해 사용을 누릅니다.
Discovery Engine API를 검색해 사용을 누릅니다.
연동할 프로젝트가 여러 개이면 각 프로젝트에서 반복합니다.

Google Cloud CLI로 활성화

아래 명령의 PROJECT_ID를 실제 프로젝트 ID로 바꿉니다.

gcloud services enable \
  monitoring.googleapis.com \
  discoveryengine.googleapis.com \
  --project=PROJECT_ID

활성화 여부는 다음 명령으로 확인할 수 있습니다.

gcloud services list \
  --enabled \
  --project=PROJECT_ID \
  --filter='name:(monitoring.googleapis.com OR discoveryengine.googleapis.com)'

프로젝트에 결제 계정이 연결되어 있는지도 확인하세요.

gcloud billing projects describe PROJECT_ID

3. 계정에 IAM 권한 부여

프로젝트 권한

다음 명령은 연동할 Google 계정에 프로젝트 수준의 준비된 역할을 부여합니다. ACCOUNT_EMAIL과 PROJECT_ID를 실제 값으로 바꿔 각 프로젝트에서 실행합니다. Gemini Enterprise Admin은 필요한 조회 권한보다 넓은 역할이므로, 빠른 설정이 필요할 때 사용하고 최소 권한이 필요하면 아래 사용자 지정 역할을 사용하세요.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/monitoring.viewer'

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/discoveryengine.agentspaceAdmin'

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/serviceusage.serviceUsageConsumer'

결제 계정 권한

Billing Account Viewer는 다음 명령으로도 부여할 수 있습니다. BILLING_ACCOUNT_ID는 000000-000000-000000 형식의 결제 계정 ID입니다.

gcloud billing accounts add-iam-policy-binding BILLING_ACCOUNT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/billing.viewer'

Discovery Engine 최소 권한 역할

Google Cloud 조직 관리자는 다음처럼 조회에 필요한 두 권한만 담은 조직 수준 사용자 지정 역할을 만들 수 있습니다. ORG_ID를 실제 조직 ID로 바꿉니다.

gcloud iam roles create smplyGeminiLicenseViewer \
  --organization=ORG_ID \
  --title='Smply Gemini License Viewer' \
  --permissions='discoveryengine.billingAccountLicenseConfigs.list,discoveryengine.userStores.listUserLicenses' \
  --stage=GA

구매 라이선스 조회 권한은 결제 계정에, 사용자별 라이선스 조회 권한은 프로젝트에 적용합니다.

gcloud billing accounts add-iam-policy-binding BILLING_ACCOUNT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='organizations/ORG_ID/roles/smplyGeminiLicenseViewer'

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='organizations/ORG_ID/roles/smplyGeminiLicenseViewer'

결제 계정이 MSP 조직에 속해 있으면 고객 조직에서 만든 사용자 지정 역할을 그 결제 계정에 부여할 수 없습니다. 이 경우 MSP 관리자에게 billing.accounts.get, billing.resourceAssociations.list, discoveryengine.billingAccountLicenseConfigs.list 권한을 연결할 Google 계정에 부여해 달라고 요청하세요.

4. Google 계정 연결

심플리에서 설정 → 연동 관리 → Gemini로 이동합니다.
Gemini 연동 카드에서 **연동하기**를 누릅니다.
앞에서 권한을 준비한 Google 계정을 선택합니다.
Google 동의 화면에서 요청 내용을 확인하고 허용합니다.
심플리로 돌아오면 카드에 **Google 계정 연결됨**이 표시되는지 확인합니다. 이 표시는 계정 연결 상태이며, 데이터 동기화 성공 여부는 별도로 확인해야 합니다.

연동이 끝나면 자동으로 찾은 프로젝트에 프로젝트 ID와 상태가 표시됩니다. 심플리는 연결한 계정으로 조회할 수 있는 모든 결제 계정과 그에 연결된 프로젝트를 자동으로 가져오므로 프로젝트를 따로 추가하거나 삭제할 수 없습니다.

Google 계정 연결
      ↓
접근 가능한 결제 계정 탐색
      ↓
결제 계정에 연결된 프로젝트 탐색
      ↓
결제 계정의 구매 라이선스 + 프로젝트의 사용자 라이선스·Code Assist 사용량 동기화
      ↓
AI → Gemini에서 확인

5. 요청하는 OAuth 범위

심플리는 Gemini 관측에 필요한 다음 범위를 함께 요청합니다.

범위	사용 방식
`https://www.googleapis.com/auth/userinfo.email`	연결한 Google 계정의 이메일을 확인합니다.
`https://www.googleapis.com/auth/cloud-billing.readonly`	계정이 조회할 수 있는 결제 계정과 연결 프로젝트를 자동으로 찾습니다.
`https://www.googleapis.com/auth/monitoring.read`	프로젝트의 Gemini Code Assist 사용량 메트릭을 읽습니다.
`https://www.googleapis.com/auth/discoveryengine.serving.readwrite`	결제 계정의 Gemini Enterprise 구매 라이선스와 프로젝트의 사용자별 라이선스 현황을 읽습니다. 심플리는 라이선스 조회 API에만 사용합니다.

심플리는 장기 동기화를 위해 Google이 발급한 갱신 토큰을 암호화해 저장합니다. 연동을 해제하면 이후 API 호출과 데이터 동기화가 중단됩니다.

6. 프로젝트 상태 확인

자동으로 찾은 프로젝트에는 Enterprise 라이선스 조회 결과가 다음 상태로 표시됩니다.

상태	의미
정상	프로젝트와 결제 계정에 접근할 수 있고 라이선스 데이터를 조회할 수 있습니다.
Enterprise 권한 오류	연결한 계정에 결제 계정 또는 프로젝트의 필요한 라이선스 조회 IAM 권한이 없습니다.
데이터 없음	접근은 가능하지만 현재 조회할 Enterprise 라이선스 데이터가 없습니다.
프로젝트 없음	Google API에서 프로젝트를 찾을 수 없습니다.
청구 계정 없음	Google API에서 연결된 청구 계정을 찾을 수 없습니다.

프로젝트 상태는 Enterprise 라이선스 조회 결과입니다. Enterprise 동기화 실패가 함께 표시되면 최근 라이선스 수집도 실패한 것입니다. Enterprise 권한 오류가 표시되더라도, 해당 계정에 Cloud Monitoring 조회 권한이 있으면 Code Assist 사용량은 별도로 동기화될 수 있습니다.

7. 대시보드 확인

연동 후 AI → Gemini로 이동합니다. 한 화면에서 다음 탭을 전환할 수 있습니다.

탭	표시 내용
Code Assist	28일 활성 사용자, 제안 승인률, 승인된 코드 라인, 채팅 활동, 프로젝트별 사용량과 토큰
Enterprise	청구 계정 수, 마지막 동기화, 배정된 라이선스 수, 사용자별 배정 상태와 마지막 로그인

Code Assist는 최초 연동 시 최근 30일의 사용량을 가져옵니다. Google Cloud에 메트릭이나 라이선스 데이터가 아직 없으면 연동은 완료되어도 대시보드가 비어 있을 수 있습니다.

8. 연동 해제

설정 → 연동 관리 → Gemini로 이동합니다.
**연동 해제**를 누릅니다.
“Gemini 연동을 해제할까요?” 확인 창에서 **연동 해제**를 누릅니다.

연동을 해제하면 Code Assist와 Enterprise의 동기화가 함께 중단됩니다. 이미 수집된 데이터는 유지되지만 더 이상 갱신되지 않습니다.

9. 문제 해결

먼저 화면에 표시된 문구로 실패한 단계를 구분하세요. Google 계정이 연결된 상태와 데이터가 정상적으로 동기화되는 상태는 다릅니다.

화면에 표시된 상황	확인할 대상	다음 행동
결제 계정 조회 권한 없음 또는 프로젝트를 찾지 못함	연결할 Google 계정, 결제 계정, 프로젝트의 결제 연결	결제 계정 조회 권한과 프로젝트 연결을 확인한 뒤 다시 연동합니다.
Code Assist 사용량 동기화 실패	실패 프로젝트 ID가 표시되면 해당 프로젝트의 Cloud Monitoring API와 연결한 계정의 Monitoring Viewer 역할	프로젝트별 실패인지 먼저 구분하고 아래 안내를 따릅니다.
Enterprise 라이선스 동기화 실패 또는 Enterprise 권한 오류	결제 계정·프로젝트의 라이선스 조회 권한, Discovery Engine API	설정을 고친 뒤 다음 동기화 결과를 확인합니다.
Google 계정 인증 만료 또는 관리자 앱 승인 필요	OAuth 인증 또는 Google Workspace 앱 승인	아래 해당 항목에 따라 다시 연동하거나 관리자에게 승인을 요청합니다.
Google API에 일시적으로 연결하지 못함	Google API 응답과 호출 제한	잠시 뒤 다시 시도하고, 반복되면 채널톡으로 문의합니다.

Q: “연결한 계정에 결제 계정 조회 권한이 없습니다”가 표시됩니다

Cloud Billing의 결제 계정 조회 요청이 권한 오류를 반환했을 때 표시됩니다. 다음 순서로 확인하세요.

Google Cloud Console의 결제 → 계정 관리 → 권한에서 연결한 계정에 Billing Account Viewer (roles/billing.viewer) 역할이 있는지 확인합니다.
연동할 프로젝트가 해당 결제 계정에 연결되어 있는지 확인합니다.
권한을 새로 부여했다면 심플리의 Gemini 연동 화면에서 연동하기를 다시 누릅니다.

CLI를 사용한다면 다음 명령으로 역할을 부여하고 프로젝트의 결제 연결 상태를 확인할 수 있습니다.

gcloud billing accounts add-iam-policy-binding BILLING_ACCOUNT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/billing.viewer'

gcloud billing projects describe PROJECT_ID

MSP가 결제 계정을 관리한다면 MSP 관리자에게 연결할 계정의 roles/billing.viewer 부여를 요청하세요. 역할이 있는데도 같은 안내가 계속 표시되면 채널톡으로 문의해 주세요.

Q: 연동 직후 프로젝트를 찾지 못했다는 안내가 표시됩니다

연결한 계정으로 조회 가능한 결제 계정에 연결된 프로젝트가 없습니다. 결제 계정이 실제로 존재하는지, 연결한 계정이 해당 계정을 볼 수 있는지, 대상 프로젝트가 결제 계정에 연결되어 있는지 확인하세요. 권한이 없는 계정과 실제로 프로젝트가 없는 계정은 조회 결과만으로 구분할 수 없습니다.

Q: Google API 또는 결제 설정을 확인하라는 안내가 표시됩니다

오류를 반환한 Google API가 요청의 할당량 프로젝트에서 활성화되어 있는지, 프로젝트에 활성 결제 계정이 연결되어 있는지 확인하세요. Enterprise 라이선스 조회에는 Discovery Engine API가 필요합니다. 연동할 프로젝트의 API를 활성화하려면 프로젝트 관리자에게 요청하거나 다음 명령을 사용하세요.

gcloud services enable discoveryengine.googleapis.com --project=PROJECT_ID

사용량 수집에 필요한 Cloud Monitoring API도 사용량을 조회할 프로젝트에서 활성화되어 있어야 합니다. 결제 계정 검색에 쓰는 Cloud Billing API 오류가 계속되면 채널톡으로 문의해 주세요. 이 API의 오류가 심플리 OAuth 앱의 프로젝트에서 발생했는지, 고객 프로젝트에서 발생했는지는 Google 오류의 consumer 값을 확인해야 합니다.

gcloud services enable monitoring.googleapis.com --project=PROJECT_ID

Q: Google API에 일시적으로 연결하지 못했다는 안내가 표시됩니다

Google API의 일시적 장애나 호출 제한일 수 있습니다. 잠시 뒤 다시 연동해 보세요. 반복되면 채널톡으로 문의해 주세요. 이 오류가 표시됐을 때는 결제 계정 조회 권한이 부족하다고 단정하지 않습니다.

Q: Google 계정에서 필요한 권한을 모두 승인하지 못했다는 안내가 표시됩니다

OAuth 동의 화면에서 요청된 접근 범위를 확인하고 다시 연동하세요. 조직에서 앱 승인을 제한한다면 Google Workspace 관리자에게 심플리 앱의 접근 허용 여부를 확인해 달라고 요청하세요.

Q: “Discovery Engine API에는 결제 계정이 있는 프로젝트가 필요합니다”가 표시됩니다

Discovery Engine API를 활성화한 프로젝트에 활성 결제 계정을 연결해야 합니다. gcloud billing projects describe PROJECT_ID의 billingEnabled가 true인지 확인하세요.

Q: “Code Assist 사용량 동기화에 실패했습니다”가 표시됩니다

Google 계정 연결은 완료됐지만 Code Assist 사용량 동기화가 실패한 상태입니다. 먼저 화면에 사용량 수집에 실패한 프로젝트가 표시되는지 확인하세요. 같은 화면의 Enterprise 권한 오류는 라이선스 조회 결과이므로 이 오류와 별도로 확인해야 합니다.

실패한 프로젝트 ID가 표시되지 않는다면 프로젝트별 조회를 시작하기 전이나 전체 작업에서 오류가 발생했을 수 있습니다. 이때는 특정 프로젝트의 IAM 권한 부족으로 단정할 수 없습니다. 다음 동기화에서도 실패하면 채널톡으로 발생 시각을 알려주세요.

실패한 프로젝트 ID가 표시된다면 해당 프로젝트마다 다음을 확인하세요.

심플리 연동 시 선택한 Google 계정에, 실패한 각 프로젝트의 Monitoring Viewer (roles/monitoring.viewer) 역할이 있는지 확인합니다. 이 역할에는 사용량 조회에 필요한 monitoring.timeSeries.list 권한이 포함됩니다.
실패한 각 프로젝트에서 Cloud Monitoring API (monitoring.googleapis.com)가 활성화되어 있는지 확인합니다.
설정을 고친 뒤 다음 동기화 결과를 확인합니다. OAuth 연결이 유지되고 있다면 이 권한 문제 때문에 연동을 해제하거나 다시 승인할 필요는 없습니다.

프로젝트 관리자라면 다음 명령으로 설정할 수 있습니다. ACCOUNT_EMAIL은 심플리 연동 시 선택한 계정, PROJECT_ID는 화면에 표시된 실패 프로젝트의 ID로 바꾸고, 프로젝트마다 실행하세요. 명령을 실행하는 CLI 계정은 API를 활성화하고 IAM 역할을 부여할 수 있는 관리자 권한이 있어야 합니다. gcloud auth login으로 CLI에 로그인하는 것만으로 심플리에 연결된 계정의 권한이 바뀌지는 않습니다.

gcloud services enable monitoring.googleapis.com --project=PROJECT_ID

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='user:ACCOUNT_EMAIL' \
  --role='roles/monitoring.viewer'

두 설정이 맞는데도 실패한다면 Google API 호출 제한이나 다른 오류일 수 있습니다. 화면의 동기화 실패만으로 IAM 권한 부족이라고 단정할 수 없으므로, 채널톡으로 실패한 프로젝트 ID와 발생 시각을 알려주세요.

Q: 프로젝트 상태가 “Enterprise 권한 오류”입니다

Enterprise 라이선스 확인 요청이 권한 오류를 반환했습니다. Code Assist 사용량 수집과는 별개입니다. 연결한 계정의 discoveryengine.billingAccountLicenseConfigs.list, discoveryengine.userStores.listUserLicenses 권한과 호출 프로젝트에 대한 serviceusage.services.use 권한을 확인하세요. 권한을 고친 뒤에는 다음 동기화 결과를 확인하세요.

Q: 일부 프로젝트가 목록에 없습니다

심플리는 연결한 계정이 조회할 수 있는 결제 계정에 연결된 프로젝트만 가져옵니다. 빠진 프로젝트가 결제 계정에 연결되어 있는지, 연결한 계정에 그 결제 계정의 billing.resourceAssociations.list 권한이 있는지 확인하세요.

Q: 연동은 됐지만 데이터가 보이지 않습니다

최초 동기화가 끝나지 않았거나 Google Cloud에 아직 사용량·라이선스 데이터가 없을 수 있습니다. 잠시 뒤 다시 확인하세요. 마지막 동기화가 실패했다면 프로젝트의 권한, 필요한 API의 활성화 상태와 호출 제한을 확인하세요. 사용량만 비어 있다면 사용량을 조회할 프로젝트의 Cloud Monitoring API 및 연결한 계정의 Monitoring 조회 권한도 확인하세요.

Q: 연결된 계정의 인증이 만료됐다고 표시됩니다

Google에서 기존 OAuth 갱신 토큰을 사용할 수 없는 상태입니다. 심플리에서 Gemini 연동을 해제한 뒤 같은 계정으로 다시 연동하세요.

Q: Google Workspace 관리자의 앱 승인이 필요하다고 표시됩니다

조직의 Google Workspace 관리자가 타사 앱의 Google API 접근을 제한한 상태입니다. 관리자에게 심플리 앱을 허용해 달라고 요청하세요. 승인이 끝나면 Gemini 연동을 해제한 뒤 다시 연동하세요.

Q: 이 외의 문제

채널톡으로 문의해 주세요.

Gemini

Gemini

1. 연동할 Google 계정과 결제 계정 준비

2. 필요한 API 활성화

3. 계정에 IAM 권한 부여

프로젝트 권한

결제 계정 권한

Discovery Engine 최소 권한 역할

4. Google 계정 연결

5. 요청하는 OAuth 범위

6. 프로젝트 상태 확인

7. 대시보드 확인

8. 연동 해제

9. 문제 해결

Q: “연결한 계정에 결제 계정 조회 권한이 없습니다”가 표시됩니다

Q: 연동 직후 프로젝트를 찾지 못했다는 안내가 표시됩니다

Q: Google API 또는 결제 설정을 확인하라는 안내가 표시됩니다

Q: Google API에 일시적으로 연결하지 못했다는 안내가 표시됩니다

Q: Google 계정에서 필요한 권한을 모두 승인하지 못했다는 안내가 표시됩니다

Q: “Discovery Engine API에는 결제 계정이 있는 프로젝트가 필요합니다”가 표시됩니다

Q: “Code Assist 사용량 동기화에 실패했습니다”가 표시됩니다

Q: 프로젝트 상태가 “Enterprise 권한 오류”입니다

Q: 일부 프로젝트가 목록에 없습니다

Q: 연동은 됐지만 데이터가 보이지 않습니다

Q: 연결된 계정의 인증이 만료됐다고 표시됩니다

Q: Google Workspace 관리자의 앱 승인이 필요하다고 표시됩니다

Q: 이 외의 문제

출처