Google Workspace 서비스 계정: 회의실 리소스 캘린더 API 연동

구글 API를 사용할 때 사용자 계정으로 명시적으로 로그인 절차를 거친 뒤 받은 토큰을 기반으로 호출하여 사용하는 것이 기본이다. 그런데, 백그라운드 서비스나 일괄처리 작업 같은 경우에는 매번 사용자 로그인을 거쳐서 토큰을 받아올 방법이 없다. 응? 그럼 어떻게...???

 

그럴 때 사용하는 개념으로 Google Workspace에는 "서비스 계정"이라는 것이 있다.

 

>> 참조: https://cloud.google.com/iam/docs/service-accounts

서비스 계정  |  IAM 문서  |  Google Cloud

 

서비스 계정을 만드는 절차는 아래 사이트를 참조하면 된다.

 

>> 참조: https://support.google.com/a/answer/7378726?hl=ko 

서비스 계정 만들기 - Google Workspace 관리자 고객센터

 

이렇게 생성된 서비스 계정은 다음과 같은 형식을 가진다.

계정 이름: tablet-service@connect-place-123456.iam.gserviceaccount.com (예시) 클라이언트 ID: 110100001111222233330  (예시)

 

※ 주의: 이렇게 생성된 서비스 계정은 Google Workspace "조직 내부 계정"이 아니다. 따라서 필요한 경우 모든 권한을 일일이 명시적으로 부여해야 하며, 특히 캘린더 API를 이용해 개인 일정 생성 등을 하려면 도메인 수준의 조직 전체 권한 위임 절차, 즉 개인을 대신해 일정을 생성할 수 있는 권한 부여도 필요하다.

 

>> 참조: https://support.google.com/a/answer/162106?hl=ko#zippy=%2C%ED%81%B4%EB%9D%BC%EC%9D%B4%EC%96%B8%ED%8A%B8%EC%97%90-%EB%8F%84%EB%A9%94%EC%9D%B8-%EC%A0%84%EC%B2%B4-%EC%9C%84%EC%9E%84-%EC%84%A4%EC%A0%95%ED%95%98%EA%B8%B0%EF%BB%BF 

도메인 전체 위임으로 API 액세스 제어하기 - Google Workspace 관리자 고객센터

 

요약하면 아래와 같다.

1. https://admin.google.com/에 Google Workspace 관리자 계정으로 로그인
2. 메뉴 이동: 보안(Security) -> API 관리(API Controls) -> 도메인 전체 위임 관리(Domain-wide Delegation)
3. 추가 -> 클라이언트 ID: 110100001111222233330 (예시)
4. API 범위 설정 (회의실 리소스 대리 예약)
   • https://www.googleapis.com/auth/calendar (회의실 캘린더 접근 권한)
   • https://www.googleapis.com/auth/calendar.events (회의실 캘린더 개별 일정 접근 권한)
   • https://www.googleapis.com/auth/admin.directory.resource.calendar (개인 캘린더 접근 권한)
   • (옵션) https://www.googleapis.com/auth/directory.readonly (임직원 사번 검색 권한)

이 중에서 마지막 임직원 사번 검색 등 디렉터리에서 임직원 속성을 검색/조회하는 권한이 필요한 경우에는 다음의 한 가지 설정을 더 해 주어야 한다.

 

[Google People API 사용 설정]

1. 구글 클라우드 콘솔(https://console.cloud.google.com/)에 접속하여 해당 프로젝트를 선택한 다음,
2. 좌측 탐색(≡) 메뉴를 클릭하여 펼쳐지는 메뉴 중 “API 및 서비스”를 선택하고,
   

   

3. 다시 바뀐 왼쪽 메뉴에서 “라이브러리”를 선택하면 API 라이브러리 화면이 나타나는데,
   

   

4. 가운데 “API 및 서비스 검색” 입력창에 “People”을 입력하면 아래와 같은 화면이 나타난다.
   

   

5. 여기서 위 화면과 같이 “사용” 버튼이 보이는 경우 “사용” 버튼을 클릭하면 아래와 같이 “API 사용 설정됨”으로 바뀌게 된다.
   

   

6.  끝.

 

추가로,

이왕 회의실 리소스 대리 예약에 대한 언급을 한 김에, Google Workspace의 회의실 리소스를 서비스 계정으로 각 임직원을 대리하여 예약 및 예약 목록 조회 등을 할 수 있도록 하려면 각 회의실 리소스에 대한 "일정 변경" 이상의 권한을 명시적으로 부여해야 한다.

 

1. https://calendar.google.com/에 Google Workspace 관리자 계정으로 로그인
2. 메뉴 이동: 회의실 리소스 캘린더 선택 -> 컨텍스트 메뉴에서 옵션(︙) 선택 -> “설정 및 공유” -> “특정 사용자와 공유”
3. 사용자 추가 -> 이메일 주소: tablet-service@connect-place-123456.iam.gserviceaccount.com (예시)
4. 사용 권한: “일정 변경” 권한 부여

 

팁1. 여기서 회의실 리소스 컨텍스트 메뉴에 "설정 및 공유"가 나타나지 않으면 관리자 권한이 아니거나 관리자 권한이 부여되었지만 아직 권한 동기화가 덜 된 상태이므로 몇 시간 정도 기다린 후에 다시 시도해 보면 된다.

 

팁2. 사용 권한 목록에 "일정 변경"이 비활성화되어 선택할 수 없다면, 구글 관리자 콘솔에서 "보조 캘린더"의 외부 공유 옵션을 확인해 봐야 한다. 즉, 보조 캘린더 – 공유 설정 – 외부 공유 옵션에서 “모든 정보를 공유하며 외부 사용자도 캘린더 변경 가능” 이상의 옵션으로 선택되어 있는지 확인할 것. (>> 참조: https://support.google.com/a/answer/60765?hl=ko#zippy=%2C%EC%99%B8%EB%B6%80-%EA%B3%B5%EC%9C%A0-%ED%97%88%EC%9A%A9-%EB%98%90%EB%8A%94-%EC%A0%9C%ED%95%9C%ED%95%98%EA%B8%B0)

Calendar 공유 옵션 설정하기 - Google Workspace 관리자 고객센터

 

 

 

※ 참고: 구글 캘린더 API는 사용 제한이 있다.

• 분당 요청 횟수 제한: 1분간 평균 5 req/sec 초과 시(정확한 설정값은 모름... 구글도 안갈쳐줌 ㅆㅂ) 403 오류 발생
• 구글 캘린더 API 사용 제한 설명: https://developers.google.com/calendar/api/guides/quota
• API 사용이 많아지면 필연적으로 이 제한에 걸려서 장애가 발생하거나 내부적인 재시도 반복에 의해 처리 시간이 오래 걸리는 상황이 발생하게 됨(최대 2~3분간 재시도 후 실패 처리).

이를 극복하기 위해서는 별도로 구글에서 제공하는 watch API를 통해 구글 캘린더 일정 추가·변경 시 이벤트 콜백 방식으로 받아서 처리하도록 보완해야 한다.

• Watch - Push notification 기술 구조 설명: https://developers.google.com/calendar/api/guides/push
• Watch API: https://developers.google.com/calendar/api/v3/reference/events/watch
• 이벤트 수신을 위해 구글에서 직접 접근이 가능한 외부 노출 HTTPS URL을 제공해야 한다.

 

끝.