이 섹션에서는 Chat 앱을 빌드하고 테스트하는 동안 발생할 수 있는 일반적인 문제를 설명합니다.
카드 메시지, 대화상자 또는 링크 미리보기가 예상대로 렌더링되거나 작동하지 않음
카드 오류를 해결하는 데 도움이 필요하면 카드 문제 해결 및 수정을 참고하세요.
앱이 응답하지 않음
Chat 앱에 메시지를 보냈는데 '앱이 응답하지 않습니다'라는 메시지가 표시되면 Chat 앱의 구성을 확인하세요.
Google Cloud 콘솔에서 메뉴 > 제품 더보기 > Google Workspace > 제품 라이브러리 > Google Chat API > 관리 > 구성을 클릭합니다.
앱 상태에서 활성 - 사용자에게 제공됨을 선택했는지 확인합니다.
대화형 기능에서 설정이 앱의 기능에 적합한지 확인합니다. Chat 앱이 사용자와 상호작용하는 경우 대화형 기능 사용 설정을 사용 설정해야 합니다.
- 기본적으로 앱은 사용자의 채팅 메시지에 응답할 수 있습니다.
- 앱이 스페이스 및 그룹 채팅의 메시지에 응답하는 경우 스페이스 및 그룹 대화 참여를 선택합니다.
- 연결 설정에서 HTTP 엔드포인트 URL, Apps Script 프로젝트 배포 ID, Cloud Pub/Sub 주제 이름 또는 Dialogflow 에이전트가 올바르게 설정되어 있고 배포되었는지 확인합니다.
- 공개 상태에서 적절한 사용자가 Google Workspace 도메인의 이메일 주소 또는 그룹을 사용하여 앱에 액세스할 수 있는지 확인합니다. 앱이 Google Workspace Marketplace SDK로 배포된 경우 Google Workspace Marketplace 설정이 우선하므로 공개 상태 설정이 필요하지 않습니다.
Google Workspace Marketplace SDK를 사용하여 앱을 게시한 경우 Google Workspace Marketplace 설정을 검토합니다.
저장을 클릭합니다.
앱에 다시 메시지를 보내 보세요.
Google Chat API는 Google Workspace 사용자에게만 제공됩니다.
Chat 앱을 구성할 때 Google Chat API is only available to Google Workspace users 오류가 표시될 수 있습니다. 이 메시지는 Chat API를 구성하는 데 사용한 Google 계정이 Google Workspace 조직에 속하지 않음을 의미합니다. Chat 앱을 빌드하거나 Chat API를 사용하려면 Google Workspace 계정을 사용해야 합니다.
Google Chat 사용자는 Google Workspace 계정 없이도 Chat 앱을 사용할 수 있습니다. 사용자가 Chat 앱을 검색하고 설치하는 방법을 자세히 알아보려면 대화형 Google Chat 앱 빌드를 참고하세요.
스페이스에서 사용자를 제외할 수 있음
Google Workspace 관리자가 사용자가 채팅 기록을 사용 또는 사용 중지하도록 허용하지 않는 경우, 채팅 기록을 강제로 사용 또는 사용 중지하는 사용자 수준 설정과 조직 수준의 강제 설정을 상속하는 스페이스 간의 충돌로 인해 사용자가 스페이스에 참여할 수 없거나 스페이스에 머무르지 못할 수 있습니다.
예를 들어 사용자의 채팅 기록 설정이 강제로 '사용'으로 설정되어 있고 스페이스의 채팅 기록 설정이 강제로 '사용 중지'로 설정되어 있는 경우 해당 사용자는 스페이스에 참여할 수 없습니다. 또한 충돌 전에 참여한 사용자가 충돌 후 스페이스에 메시지를 게시하면 스페이스에서 삭제될 수 있습니다.
이 시나리오와 기록 설정 간에 충돌이 발생하는 기타 시나리오에서 Chat API는 멤버십을 만들 수 없거나 사용자 인증으로 메시지를 만들면 충돌하는 Chat 기록 설정이 있는 인증된 사용자가 스페이스에서 삭제될 수 있습니다.
자세한 내용은 Google Workspace 관리자 고객센터의 스페이스에서 사용자를 제외할 수 있음을 참고하세요.
Google Apps Script의 고급 Chat 서비스 문제 해결
고급 Chat 서비스에 관한 Apps Script 페이지를 참고하세요.
사용자가 스페이스에 Chat 앱을 추가할 수 없음
사용자가 스페이스에 Chat 앱을 추가하려고 할 때 This organization's administrator must allow users to install this Chat app 오류 메시지가 표시되면 다음 중 한 가지 이유 때문일 수 있습니다.
- 조직에서 Chat 앱을 사용 중지했습니다.
- 조직에서 이 특정 Chat 앱을 조직의 허용 목록에 추가하지 않았습니다.
사용자가 Chat 앱과 상호작용하려고 할 때 이 오류 메시지가 표시되면 조직에서 상위 조직 단위에 대해 사용 설정하지 않고 하위 조직 단위에 대한 액세스 권한을 부여했기 때문일 수 있습니다.
이 문제를 해결하는 방법은 사용자가 Chat 앱을 설치하도록 허용하기를 참고하세요.
관리자는 이 작업을 위해 앱에 필요한 OAuth 승인 범위를 부여해야 합니다.
Chat 앱으로 인증할 때 다음 오류가 표시될 수 있습니다.
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">
이 오류 메시지는 Google Workspace 관리자가 https://www.googleapis.com/auth/chat.app.* 이름으로 시작하는 승인 범위를 사용하도록 Chat 앱에 일회성 승인을 아직 부여하지 않았음을 의미합니다.
이 오류를 해결하려면 다음 단계를 따르세요.
- Google Workspace 관리자에게 Chat 앱 승인을 요청합니다. Chat 앱 로직에서 이 오류를 처리할 때 Chat 앱이 요청된 작업을 실행하려면 관리자 승인이 필요하다는 메시지를 전송하는 것이 좋습니다. 예를 들면 다음과 같습니다.
To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>. - Chat API 메서드가 관리자 승인이 필요하지 않은
https://www.googleapis.com/auth/chat.bot승인 범위를 지원하는 경우 이를 대신 사용하는 것이 좋습니다. 메서드에서 지원하는 승인 범위를 확인하려면 Google Chat 앱 및 Google Chat API 요청 인증 및 승인하기를 참고하세요.
Cloud 함수 오류 문제 해결
채팅 앱이 Cloud Functions로 구현되었는데 작동하지 않는 경우 다음 섹션에서 문제를 해결하는 데 도움이 됩니다.
Cloud 함수 로그 확인
먼저 Cloud Functions 로그에서 오류를 확인합니다.
Google Cloud 콘솔에서 Cloud Functions 페이지로 이동합니다.
로그를 열려면 Chat 앱의 Cloud 함수를 찾은 다음 작업 표시 > 로그 보기를 클릭합니다.
로그 탐색기가 열리고 오류를 비롯한 Cloud Functions 로그를 표시하는 쿼리가 실행됩니다.
로깅된 기본 정보가 앱을 디버깅하기에 충분하지 않은 경우 Cloud 함수 코드에서 추가 로깅을 추가할 수 있습니다. Cloud 함수 로그 보기 및 쓰기를 참고하세요.
Cloud 함수 오류 확인
로그 외에도 Cloud 함수는 실행 중에 발생한 오류를 보고할 수 있습니다.
Google Cloud 콘솔에서 Cloud Functions 페이지로 이동합니다.
Chat 앱의 Cloud 함수를 클릭합니다.
함수 세부정보 페이지의 오류에 오류가 나열됩니다.
오류를 클릭하여 추가로 문제를 해결할 수 있습니다.
일반적인 Cloud 함수 오류 수정
Cloud Functions로 Chat 앱을 빌드할 때 다음 오류가 발생하는 경우가 있습니다.
프로젝트 PROJECT_NAME의 REGION_NAME 리전에 함수 ChatApp이 이미 있습니다.
Cloud Function을 배포할 때 Function
ChatApp in region REGION_NAME in project PROJECT_NAME already
exists 오류가 표시될 수 있습니다. 이 메시지는 다른 Cloud 함수가 배포 중인 함수와 이름이 동일하다는 의미입니다. 이름을 변경하고 함수를 다시 배포합니다. Chat 앱이 기존 Cloud 함수의 트리거 URL이 아닌 Cloud 함수의 트리거 URL을 사용하는지 확인합니다.
정책에 지정된 사용자 중 하나 이상이 허용된 고객에 속하지 않습니다.
Cloud Functions를 배포할 때 The operation
cannot be completed on the function: "One or more users named in the policy do
not belong to a permitted customer." 오류가 표시될 수 있습니다. 이 오류가 표시된 후 Chat 앱에 메시지를 보내면 Google Chat에서 Cloud Functions를 호스팅하는 서버에 연결할 수 없기 때문에 앱이 응답하지 않는다는 오류가 표시됩니다. 이 메시지는 'allUsers'라는 사용자에게 Cloud 함수를 호출할 권한이 없음을 의미합니다.
'allUsers'에 'Cloud Functions 호출자' 역할을 부여하면 앱을 지원하는 Cloud Functions를 공개적으로 사용할 수 있으며 인증 없이 액세스할 수 있습니다. 역할 할당 방법을 알아보려면 단일 역할 부여를 참고하세요.
이 오류는 Google Cloud 프로젝트가 도메인으로 제한되어 있음을 의미할 수 있습니다. 도메인 제한 제약 조건에 대한 자세한 내용은 도메인별 ID 제한을 참고하세요.
이 문제를 해결하려면 Cloud 함수가 인증되지 않은 호출을 허용하는지 확인하세요. 기존 Cloud 함수의 인증되지 않은 호출을 허용하는 방법을 알아보려면 공개 (인증되지 않은) 액세스 허용을 참고하세요.