Looker 확장 프로그램 프레임워크 문제 해결

Looker 확장 프로그램 프레임워크를 사용하면 Looker 내에서 실행되는 커스텀 JavaScript 및 TypeScript 애플리케이션과 시각화를 빌드할 수 있습니다. 확장 프로그램은 샌드박스 처리된 iframe에서 실행되며 확장 프로그램 SDK를 통해 Looker 인스턴스와 상호작용합니다. iframe 내의 빈 페이지 또는 오류 메시지, 브라우저 콘솔 JavaScript 또는 교차 출처 리소스 공유 (CORS) 오류, 실패한 Looker API 요청 (4xx 또는 5xx 상태 코드), manifest.lkml 구성 오류와 같은 커스텀 확장 프로그램 문제가 발생하면 이 문서를 통해 문제를 해결할 수 있습니다.

기본 요건 및 일반 구성 요구사항

문제 해결을 시작하기 전에 환경, LookML 프로젝트, 사용자 계정이 Looker 확장 프로그램을 실행하기 위한 요구사항을 충족하는지 확인합니다.

  • 확장 프로그램 프레임워크 사용 설정됨: Looker 관리자가 관리 > 플랫폼 > 확장 프로그램 프레임워크에서 확장 프로그램 프레임워크 설정을 사용 설정해야 합니다.
  • LookML 프로젝트 및 모델 구성: 모든 확장 프로그램에는 다음 구성요소가 포함된 LookML 프로젝트가 필요합니다.
  • 매니페스트 사용 권한: manifest.lkml 파일의 application 선언은 확장 프로그램에 필요한 모든 entitlements를 명시적으로 정의해야 합니다(예: Looker API 호출의 경우 core_api_methods, 외부 도메인에 대한 요청의 경우 external_api_urls). 확장 프로그램은 entitlements 블록이 없으면 실행되지 않습니다.
  • 사용자 권한: 사용자는 확장 프로그램의 LookML 모델이 포함된 모델 세트에 대한 확장 프로그램 권한(예: access_data, explore, develop)이 있어야 합니다. 확장 프로그램을 빌드하려면 개발자에게 LookML develop 권한이 필요합니다.
  • 진단 도구 및 환경 세부정보: 문제 해결을 시작하기 전에 다음 세부정보와 도구를 준비하세요.
    • Looker 인스턴스 URL, LookML 프로젝트 이름, manifest.lkml에 선언된 application 이름
    • 클라이언트 머신에서 웹브라우저의 개발자 도구 (콘솔 및 네트워크 탭)에 액세스합니다.
    • 로컬 개발 중에 로컬 개발 서버를 실행하는 터미널에 액세스합니다.
    • Looker API 호출의 5xx 서버 오류의 경우 Looker 인스턴스 로그에 액세스합니다(고객 호스팅 인스턴스의 looker.log 또는 Looker (Google Cloud 핵심 서비스) 인스턴스의 Google Cloud 콘솔에 있는 Cloud Logging의 로그 탐색기).

디버깅 트리

다음 결정 트리를 사용하여 Looker 확장 프로그램 프레임워크 문제 해결을 시작합니다.

다음 섹션에서는 트리의 시나리오를 자세히 설명합니다.

브라우저 콘솔 및 네트워크 로그 검사

Looker 확장 프로그램은 브라우저에서 클라이언트 측으로 실행되므로 브라우저의 개발자 도구에서 JavaScript 오류, 보안 정책 위반, 실패한 HTTP 요청을 검사하여 문제 해결을 시작합니다.

브라우저 콘솔에서 오류 확인하기

확장 프로그램이 로드되거나 실행되지 않는 클라이언트 측 오류를 식별하려면 다음 단계를 따르세요.

  1. Looker에서 확장 프로그램이 로드되는 페이지를 엽니다.
  2. 페이지 아무 곳이나 마우스 오른쪽 버튼으로 클릭하고 검사를 선택합니다(또는 Windows 및 Linux에서 Control+Shift+I를 누르거나 macOS에서 Command+Option+I를 누름).
  3. 개발자 도구 패널에서 콘솔 탭을 선택합니다.
  4. 페이지를 새로고침하여 초기 로드 중에 발생하는 오류를 캡처합니다.
  5. 콘솔에서 빨간색 오류 메시지를 검사합니다.

네트워크 탭에서 실패한 요청 검사

JavaScript 번들, 애셋 또는 API 엔드포인트에 대해 확장 프로그램에서 수행하는 HTTP 요청을 분석하려면 다음 단계를 따르세요.

  1. 브라우저 개발자 도구 패널에서 네트워크 탭을 선택합니다.
  2. 브라우저가 오래된 캐시 리소스를 로드하지 않도록 캐시 사용 중지 체크박스를 선택합니다.
  3. 확장 프로그램이 로드되는 페이지를 새로고침합니다.
  4. 네트워크 요청 목록에서 4xx 또는 5xx 상태 코드를 확인하고 실패한 요청을 선택하여 헤더, 페이로드, 응답 탭을 검사합니다.
    • 확장 프로그램 번들의 404(예: bundle.js): 개발 서버가 실행 중이고 manifest.lkml의 url 또는 file 매개변수가 정확한지 확인합니다.
    • Looker API 요청에 대한 401 또는 403: 인증, 권한, 사용 권한을 조사합니다.
    • API 요청의 400 또는 422: 페이로드 및 응답 탭을 검사하여 잘못된 형식의 JSON 또는 잘못된 요청 매개변수를 식별합니다.
    • 5xx 서버 오류: Looker 인스턴스의 서버 측 오류를 나타냅니다. 고객 호스팅 인스턴스의 looker.log 또는 Looker (Google Cloud 핵심 서비스) 인스턴스의 콘솔에 있는 로그 탐색기를 확인하여 타임스탬프가 일치하는 항목을 찾습니다.

콘솔 또는 네트워크 탭에 오류가 표시되지 않거나 Looker가 확장 프로그램을 로드하는 방법을 확인해야 하는 경우 다음 섹션으로 진행합니다.

매니페스트 및 프로젝트 구성 확인

프로젝트의 manifest.lkml 파일에 있는 application 선언은 Looker가 확장 프로그램을 로드하는 방법과 확장 프로그램에서 사용할 수 있는 리소스를 제어합니다. manifest.lkml의 잘못된 구성은 로드 및 API 실패의 일반적인 원인입니다.

  • url 또는 file 매개변수 확인: Looker IDE에서 프로젝트의 manifest.lkml 파일을 열고 application 선언을 검사합니다.
    • application 선언에는 url 매개변수 또는 file 매개변수 중 하나만 포함되어야 합니다.
    • 로컬 개발 중: url 매개변수가 로컬 개발 서버에서 제공하는 정확한 프로토콜 (http 또는 https), 호스트 이름, 포트, 경로와 일치하는지 확인합니다 (예: https://localhost:8080/bundle.js).
    • 프로덕션: LookML 프로젝트 (예: file: "apps/bundle.js") 또는 프로덕션 번들 URL에서 application 선언을 로컬 개발 url에서 프로덕션 file 경로로 업데이트했는지 확인합니다.
  • manifest.lkml 사용 권한 확인: application 선언에서 entitlements 블록을 검토합니다. 확장 프로그램은 다음과 같이 사용 권한이 명시적으로 선언되지 않는 한 Looker 리소스 또는 외부 도메인을 사용할 수 없습니다.
    • core_api_methods: 확장 프로그램이 호출하는 모든 Looker API 메서드를 나열해야 합니다 (예: core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: 확장 프로그램이 직접 또는 프록시를 통해 요청하는 모든 외부 비Looker 도메인을 나열해야 합니다.
    • 추가 사용 권한: 확장 프로그램에 local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes 또는 scoped_user_attributes가 필요한지 확인합니다.
  • 검증, 커밋, 배포: manifest.lkml를 수정한 후 LookML 검증을 클릭하고 변경사항을 커밋한 다음 프로덕션에 배포를 클릭하여 업데이트된 구성이 적용되도록 합니다.

로컬 개발 서버 및 환경 문제 해결

manifest.lkml에서 url 매개변수를 사용하여 로컬에서 확장 프로그램을 개발하는 경우 로컬 개발 서버가 실행 중이고 브라우저에서 액세스할 수 있어야 합니다.

  • 개발 서버가 실행 중인지 확인: 개발 서버를 시작한 터미널 창을 확인합니다 (예: yarn develop 또는 npm start 사용).
    • 빌드가 오류 없이 컴파일되고 수신 메시지 (예: webpack compiled successfully 또는 listening on localhost:8080)가 표시되는지 확인합니다.
    • 서버가 실행되고 있지 않으면 yarn develop 또는 npm start로 서버를 시작합니다.
    • 서버가 문법 오류 또는 종속 항목 누락 오류로 종료된 경우 코드 오류를 해결하거나 yarn install (또는 npm install)를 실행하여 누락된 패키지를 설치합니다.
    • 서버가 포트 충돌 (EADDRINUSE)로 인해 실패하면 해당 포트를 사용하는 다른 프로세스를 중지하거나 개발 서버와 manifest.lkml url 매개변수를 다른 포트를 사용하도록 구성합니다.
  • 브라우저에서 직접 확장 프로그램 URL 열기: manifest.lkml에서 url 값(예: https://localhost:8080/bundle.js)을 복사하여 새 브라우저 탭에서 엽니다.
    • 신뢰할 수 없는 자체 서명 SSL 인증서: 로컬 개발 서버는 자체 서명 SSL 인증서를 자주 사용합니다. 브라우저에 인증서 보안 경고가 표시되면 고급을 선택하고 localhost로 이동하여 브라우저 세션의 인증서를 신뢰합니다. 인증서를 신뢰할 수 있을 때까지 브라우저는 Looker iframe 내에서 번들이 로드되지 않도록 차단합니다.
    • 연결이 거부되거나 차단됨: 브라우저가 URL에 연결할 수 없는 경우 로컬 방화벽이나 엔드포인트 보안 소프트웨어가 구성된 포트에서 localhost에 대한 연결을 차단하지 않는지 확인합니다.

네트워킹, CORS, 보안 정책 문제 해결

웹브라우저는 동일 출처 정책을 적용하므로 교차 출처 리소스 공유 (CORS) 헤더 및 보안 정책이 구성되지 않는 한 Looker가 확장 프로그램 리소스를 로드하거나 다른 출처의 외부 서버를 호출할 수 없습니다.

  • 브라우저 콘솔에서 CORS 오류 식별: 콘솔 탭에서 Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy 또는 누락된 Access-Control-Allow-Origin 헤더가 포함된 오류 메시지를 찾습니다.
  • 로컬 개발 서버 CORS 헤더 구성: webpack-dev-server (또는 유사한 번들러)를 사용하는 경우 webpack.config.js의 devServer 구성에 Access-Control-Allow-Origin 헤더가 포함되어 있는지 확인합니다. javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • 프로덕션 호스팅 및 외부 API CORS 헤더 구성: 확장 프로그램이 외부 서비스 (예: Cloud Storage, Amazon S3 또는 커스텀 백엔드 서버)에서 애셋을 로드하거나 데이터를 요청하는 경우 Looker 인스턴스 도메인을 허용하는 Access-Control-Allow-Origin 헤더를 반환하도록 호스팅 서비스를 구성합니다. 또한 네트워크 프록시 또는 방화벽이 응답에서 CORS 헤더를 제거하지 않는지 확인하고 외부 도메인이 manifest.lkml의 external_api_urls에 나열되어 있는지 확인합니다.
  • 콘텐츠 보안 정책 (CSP) 및 향상된 확장 프로그램 로드 확인: 확장 프로그램을 로드할 때 CSP 위반이 발생하면 관리 > 플랫폼 > 확장 프로그램 프레임워크에서 향상된 확장 프로그램 로드 설정을 확인합니다.

인증 및 API 액세스 문제 해결

확장 프로그램은 확장 프로그램 SDK를 통해 로그인한 사용자를 대신하여 Looker API와 상호작용합니다. 네트워크 탭에서 API 호출이 401 Unauthorized 또는 403 Forbidden 상태 코드로 실패하면 다음을 조사합니다.

  • 401 오류와 403 오류 구분:
    • 401 Unauthorized: 요청이 인증되지 않았습니다. 이 오류는 일반적으로 확장 프로그램 SDK가 제대로 초기화되지 않았거나 SDK가 인증 핸드셰이크를 완료하기 전에 확장 프로그램이 API 호출을 시도한 경우에 발생합니다.
    • 403 Forbidden: 요청이 인증되었지만 로그인한 사용자에게 필요한 Looker 권한이 없거나 확장 프로그램의 manifest.lkml에 core_api_methods의 호출된 메서드가 포함되어 있지 않습니다.
  • 사용자 역할 및 권한 확인: 관리 > 사용자 및 관리 > 역할에서 로그인한 사용자의 할당된 역할, 권한 세트, 모델 세트를 확인합니다.
    • 사용자에게 확장 프로그램의 LookML 모델과 확장 프로그램에서 쿼리하는 모든 모델이 포함된 모델 세트에 대한 access_data (필요한 경우 explore 또는 develop)를 포함하여 확장 프로그램을 사용할 권한이 있는지 확인합니다.
    • 사용자의 역할에 확장 프로그램이 호출하는 각 Looker API 엔드포인트에 필요한 특정 권한이 포함되어 있는지 확인합니다.
  • API를 호출하기 전에 SDK 컨텍스트가 준비되었는지 확인: 확장 프로그램 코드가 API 메서드를 호출하기 전에 확장 프로그램 SDK 컨텍스트가 초기화될 때까지 기다리는지 확인합니다.

확장 프로그램 SDK 및 종속 항목 문제 해결

npm 또는 Yarn 패키지 설치 문제 또는 SDK 제공업체 구성요소 누락으로 인해 확장 프로그램이 컴파일되거나 Looker에 연결되지 않을 수 있습니다.

  • Node.js 모듈 설치 확인: 터미널에서 확장 프로그램 프로젝트의 루트 디렉터리로 이동하여 node_modules 디렉터리를 확인합니다.
    1. node_modules가 누락되었거나 종속 항목이 손상된 것으로 보이면 node_modules 디렉터리와 잠금 파일 (yarn.lock 또는 package-lock.json)을 삭제합니다.
    2. 선택사항: 패키지 설치가 반복적으로 실패하면 패키지 관리자 캐시를 지웁니다 (예: npm cache clean --force 실행).
    3. 설치된 Node.js 버전이 프로젝트 요구사항과 호환되는지 확인한 후 yarn install 또는 npm install을 실행하여 새로 설치합니다.
  • ExtensionProvider 초기화 확인: 확장 프로그램의 기본 항목 파일 (예: App.js 또는 index.js)을 열고 <ExtensionProvider>(@looker/extension-sdk-react에서 가져옴)가 Looker SDK 컨텍스트가 필요한 애플리케이션 구성요소를 래핑하는지 확인합니다. javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); <ExtensionProvider>가 누락되었거나 SDK를 호출하는 구성요소 뒤에 배치한 경우 하위 구성요소는 SDK 컨텍스트에 액세스할 수 없습니다.

런타임 JavaScript 및 논리 오류 문제 해결

확장 프로그램의 구성, 개발 서버, 권한, SDK 설정이 유효한 경우 확장 프로그램의 커스텀 JavaScript 또는 TypeScript 코드의 런타임 오류가 문제일 수 있습니다.

  • 콘솔 스택 트레이스 분석: 브라우저의 콘솔 탭에서 빨간색 오류 메시지를 찾고 펼치기 화살표를 클릭하여 전체 스택 트레이스를 확인합니다. 스택 트레이스의 맨 위 줄은 오류가 발생한 소스 코드의 파일과 줄 번호를 식별합니다. 파일 링크 (예: MyComponent.js:42)를 클릭하여 소스 탭의 해당 줄로 바로 이동합니다.
  • 정의되지 않은 값 또는 null 값 확인: TypeError: Cannot read properties of undefined과 같은 오류의 경우 코드가 중첩된 속성을 읽기 전에 비동기 API 응답 또는 속성이 로드를 완료했는지 확인합니다. 방어 검사 (예: if (myObject && myObject.property) 또는 선택적 체이닝 myObject?.property)를 추가합니다.
  • API 응답 형식 확인: 코드가 Looker API 호출에서 반환하는 실제 데이터 구조를 처리하는지 확인합니다 (예: 배열 메서드를 호출하기 전에 응답 페이로드가 객체인지 배열인지 확인).
  • 중단점 및 로깅으로 디버그: 브라우저의 소스 탭에서 실패한 줄 앞에 중단점을 설정하여 실행을 일시중지하고 실시간으로 변수 값을 검사하거나 console.log() 문을 추가하여 실행 흐름을 추적합니다.

Looker 버전 호환성 확인

Looker의 주요 기능 업데이트 또는 변경사항에는 호환되는 버전의 Looker 확장 프로그램 SDK가 필요할 수 있습니다.

  1. 확장 프로그램 프로젝트의 package.json 파일에서 @looker/extension-sdk(및 @looker/extension-sdk-react(사용하는 경우))의 버전을 확인합니다.
  2. Looker 웹 인터페이스에서 도움말 > 정보 또는 관리자 > 일반 > 설정에서 인스턴스의 현재 출시 버전을 확인합니다.
  3. Looker 출시 버전을 @looker/extension-sdk 문서의 호환성 노트와 비교합니다.
  4. Looker 인스턴스가 최근에 업그레이드되었고 확장 프로그램이 오래된 SDK를 사용하거나 확장 프로그램이 이전 Looker 버전에서 지원되지 않는 최신 SDK 기능을 사용하는 경우 SDK 패키지를 호환되는 버전으로 업데이트합니다. bash npm install @looker/extension-sdk@latest 패키지를 업데이트한 후 종속 항목을 다시 설치하고 개발 서버를 다시 시작합니다.

진단 정보 수집

문제 해결 단계를 수행한 후에도 문제를 해결할 수 없는 경우 지원팀에 문의하기 전에 다음 정보를 수집하세요.

  1. Looker 인스턴스 및 프로젝트 정보:
    • Looker 인스턴스 URL (예: instance_name.looker.com)
    • Looker 출시 버전입니다.
    • manifest.lkml의 확장 프로그램과 application 이름이 포함된 LookML 프로젝트의 이름입니다.
  2. 확장 프로그램 구성 및 SDK 세부정보:
    • manifest.lkml 파일의 application 선언 사본 또는 스크린샷
    • package.json에 지정된 @looker/extension-sdk 버전입니다.
    • 확장 프로그램이 로컬 개발 서버 (url)에서 실행되는지 또는 프로덕션 (file)에 배포되는지 여부
  3. 오류 로그 및 스크린샷:
    • 브라우저의 콘솔 및 네트워크 탭에서 발생한 오류의 스크린샷 또는 전체 텍스트 (실패한 4xx 또는 5xx 요청의 요청 헤더 및 응답 페이로드 포함)
    • API 호출이 지속적으로 5xx 서버 오류를 반환하는 경우 looker.log (고객 호스팅 인스턴스) 또는 Logging의 로그 탐색기 (Looker (Google Cloud 핵심 서비스) 인스턴스)에서 일치하는 로그 발췌문
  4. 문제 해결 요약 및 재현 단계:
    • 이미 수행한 문제 해결 단계 및 결과 요약
    • Looker 확장 프로그램 프레임워크 또는 확장 프로그램 SDK에서 문제가 의심되는 경우 문제를 재현하는 정확한 단계 또는 최소한의 재현 가능한 예시

지원팀에 문의

이전 단계를 모두 확인했는데도 문제가 해결되지 않으면 다음 단계를 따르세요.