이 페이지는 Cloud Translation API를 통해 번역되었습니다.

커뮤니티 커넥터 관련 오류 처리 및 메시지

우수한 사용자 환경을 제공하려면 코드에서 오류를 올바르게 처리해야 합니다. 문제 해결을 위한 수정 단계를 설명하는 실행 가능한 오류 메시지를 사용자에게 제공합니다.

이 문서에서는 커넥터에서 발생할 수 있는 오류, 오류 메시지의 작동 방식, 커넥터 오류를 올바르게 처리하는 방법을 설명합니다.

정보: 자바스크립트에서 예외를 처리하는 방법을 자세히 알아보려면 try...catch 문을 참고하세요.

오류 유형

커넥터를 사용할 때 사용자에게 발생할 수 있는 오류의 유형 및 원인은 일반적으로 다음 세 가지 카테고리 중 하나에 속합니다.

커넥터 내부 오류
커넥터 외부 오류
Looker Studio 오류

커넥터 내부 및 외부 오류는 커넥터 개발자가 처리해야 합니다. 이 오류는 개발자가 작성한 코드로 인해 발생합니다.

커넥터 내부 오류

커넥터 실행 중에 커넥터 내부 오류가 발생합니다. 예를 들어 getData()를 실행하는 동안 커넥터가 API 응답을 파싱할 수 없는 경우입니다. 해당하는 경우 사용자 친화적인 설명을 통해 이러한 오류를 예상하고 처리해야 합니다.

커넥터 내부 오류 처리에 대한 자세한 내용은 커넥터 오류 처리 권장사항을 참조하세요.

커넥터 외부 오류

커넥터 외부 오류는 커넥터 실행 후에 발생합니다. 예를 들어 3개의 필드에 대한 getData() 요청이 2개의 필드 데이터만 반환하는 경우입니다. 커넥터가 실행을 완료했지만 Looker Studio의 요청을 충족하지 않았습니다. 철저한 테스트를 통해 이러한 오류를 방지할 수 있습니다.

커넥터 외부 오류는 일반적으로 오류 세부정보 (가능한 경우)를 검토하고 코드를 디버깅하여 문제를 식별하면 해결할 수 있습니다. 커넥터 디버깅에 관한 자세한 내용은 코드 디버그를 참고하세요.

Looker Studio 오류

Looker Studio 오류는 커넥터 코드와 관련이 없는 오류입니다. 예를 들어 사용자가 날짜/시간 측정기준이 없는 데이터 소스가 있는 시계열 차트를 사용하려는 경우입니다.

오류가 커넥터와 직접적인 관련이 없는 경우 커넥터 개발자가 취해야 할 조치는 없습니다. 사용자는 Looker Studio 고객센터를 방문하여 추가 도움말을 확인할 수 있습니다.

오류 메시지 표시

관리자 상태를 기준으로 오류 세부정보 표시

커넥터에서 오류가 발생하면 Looker Studio에서 사용자의 관리자 상태에 따라 오류 메시지를 표시합니다.

관리자인 경우 모든 세부정보가 표시됩니다. 여기에는 오류 메시지, 오류 유형, 스택 트레이스가 포함됩니다.
사용자가 관리자가 아닌 경우 오류에 사용자 친화적인 메시지가 포함된 경우에만 세부정보가 표시됩니다. 관리자가 아닌 사용자에게 오류 메시지를 표시하는 방법을 자세히 알아보려면 사용자에게 발생하는 오류 발생을 참조하세요.

사용자에게 발생하는 오류 발생

기본적으로 커넥터 관리자만 오류 세부정보를 볼 수 있습니다. 이렇게 하면 스택 트레이스의 API 키와 같은 민감한 정보가 실수로 노출되는 것을 방지할 수 있습니다. 관리자가 아닌 사용자에게 오류 메시지를 표시하려면 Looker Studio Apps Script 서비스의 newUserError()를 사용합니다.

예:

try {
  // API request that can be malformed.
  getDataFromAPI();
} catch (e) {
  DataStudioApp.createCommunityConnector()
      .newUserError()
      .setDebugText('Error fetching data from API. Exception details: ' + e)
      .setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
      .throwException();

}

이 예에서 setText()는 모든 사용자에게 표시될 텍스트를 설정하고 setDebugText()는 관리자에게만 표시할 텍스트를 설정합니다.

커넥터 오류 처리를 위한 권장사항

커넥터 코드를 실행하는 동안 최대한 많은 오류를 포착하고 처리해야 합니다. 예를 들어 오류 또는 바람직하지 않은 상태를 유발할 수 있는 일반적인 작업은 다음과 같습니다.

실패한 URL 가져오기 시도 (일시적 오류, 시간 초과)
요청한 기간에 대한 데이터가 없습니다.
API의 데이터를 파싱하거나 형식을 지정할 수 없음
승인 토큰이 취소되었습니다.

복구 가능한 오류 처리

실패할 수 있지만 복구할 수 있는 커넥터 실행 지점을 처리해야 합니다. 예를 들어 심각하지 않은 이유 (예: 서버 부하 차단)로 API 요청이 실패하면 오류가 발생하기 전에 재시도해야 합니다.

오류 포착 및 발생

복구할 수 없는 오류는 포착하여 다시 발생시켜야 합니다. 다시 발생한 오류는 사용자가 오류가 발생한 이유를 이해하는 데 도움이 됩니다. 문제를 해결할 수 있는 경우 시정 조치에 대한 세부정보를 제공해야 합니다.

사용자에게 표시되는 오류 발생을 참조하세요.

Stackdriver에 오류 로깅

Stackdriver를 사용해 오류 및 기타 메시지 로깅 이렇게 하면 오류를 이해하고, 문제를 디버깅하고, 처리되지 않은 예외를 발견하는 데 도움이 됩니다.

Stackdriver Error Reporting, 스크립트에 예외 로깅을 사용 설정하는 방법, 디버깅할 목적으로 사용자를 안전하게 식별하는 방법에 대한 자세한 내용은 Stackdriver Logging 사용을 참조하세요.

지원 중단됨: 안전한 오류 메시지에 `DS_USER:` 접두사 사용

관리자가 아닌 사용자에게 사용자 친화적인 오류 메시지를 제공하려면 오류 메시지와 함께 DS_USER: 프리픽스를 포함하세요. 이 프리픽스는 관리자가 아닌 사용자에게 안전한 메시지를 식별하는 데 사용되며 실제 오류 메시지에 포함되지 않습니다.

다음 예에는 관리자가 아닌 사용자에게 오류 메시지가 표시되고 오류 메시지가 관리자에게만 표시되는 경우가 포함됩니다.

data-studio/errors.gs

GitHub에서 보기

// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}