Looker API 문제 해결

이 페이지에는 Looker API에서 발생할 수 있는 다음 문제에 대한 문제 해결 절차가 나옵니다.

API 엔드포인트에 연결할 수 없음

API 엔드포인트에 연결할 수 없는 경우 다음을 수행합니다.

API 사용자 인증 정보 확인

Looker API 엔드포인트에 연결할 수 없는 경우 먼저 API 사용자 인증 정보가 올바른지 확인하세요. API 사용자 인증 정보를 보려면 다음 안내를 따르세요.

  1. Looker에서 왼쪽 탐색 패널의 관리 옵션을 선택하여 관리 패널에 액세스합니다.
  2. 관리 페이지의 왼쪽 패널에서 아래로 스크롤하여 사용자를 클릭합니다.
  3. 사용자 목록에서 사용자 이름을 검색하고 이를 클릭하여 사용자 페이지를 수정합니다.
  4. API 키 수정을 클릭합니다. 클라이언트 ID를 확인할 수 있으며 눈 모양 아이콘을 클릭하여 구성한 각 API 키의 클라이언트 보안 비밀번호를 확인할 수 있습니다. API 사용자 인증 정보가 스크립트에서 사용하는 사용자 인증 정보와 일치하는지 확인합니다.

API URL 확인

API 엔드포인트에 연결하는 또 다른 일반적인 문제는 잘못된 API 호스트 URL입니다. 대부분의 Looker 인스턴스는 API의 기본 URL을 사용합니다. 그러나 대체 API 경로를 사용하는 Looker 설치 또는 부하 분산기 뒤에 있는 Looker 설치(예: 클러스터 구성) 또는 다른 프록시가 기본 URL을 사용하지 않을 수 있습니다. 이 경우 API 호스트 URL은 사용자 대상 API 호스트 이름과 포트를 나타내야 합니다.

Looker 관리자는 API 관리자 설정에서 API 호스트 URL을 볼 수 있습니다(자세한 내용은 관리자 설정 - API 문서 페이지 참조). API 호스트 URL을 보려면 다음 안내를 따르세요.

  1. 왼쪽 탐색 패널에서 관리 옵션을 선택하여 관리 패널에 액세스합니다.
  2. 관리 패널에서 API를 클릭합니다.

  3. API 호스트 URL을 확인합니다.

    API 호스트 URL 필드가 비어 있는 경우 Looker 인스턴스는 기본 형식을 사용합니다.

    https://<instance_name>.cloud.looker.com:<port>

API 호스트 URL을 테스트하려면 다음 안내를 따르세요.

  1. 브라우저를 열고 브라우저 콘솔을 엽니다.

  2. API 호스트 URL 뒤에 /alive를 입력합니다. 예를 들어 API 호스트 URL이 https://company.cloud.looker.com인 경우 다음을 입력합니다.

    https://company.cloud.looker.com/alive

    API 호스트 URL 필드가 비어 있는 경우 기본 API URL을 사용합니다. 예를 들어 Google Cloud, Microsoft Azure에서 호스팅되는 인스턴스와 2020년 7월 7일 이후에 생성된 Amazon Web Service(AWS)에서 호스팅되는 인스턴스의 경우 기본 Looker API 경로는 포트 443을 사용합니다.

    https://<instance_name>.cloud.looker.com:443/alive

    2020년 7월 7일 이전에 생성된 AWS에서 호스팅되는 인스턴스의 경우 기본 Looker API 경로는 포트 19999를 사용합니다.

    https://<instance_name>.cloud.looker.com:19999/alive

API 호스트 URL이 올바른 경우 URL에 오류 페이지가 아닌 빈 웹페이지가 표시됩니다.

브라우저 콘솔에서 네트워크 응답을 확인하여 API에 도달했는지 확인할 수도 있습니다. 네트워크 응답은 200이어야 합니다.

이러한 검사에 실패할 경우 API를 잘못 호출했거나 코드에 다른 오류가 있는 것이 문제일 수 있습니다. API 호출과 스크립트의 코드를 확인합니다. 코드가 맞는 경우 포트 확인에 대한 다음 섹션을 참조하세요.

API 포트 확인

위의 검사가 실패하고 고객 호스팅 Looker 배포가 있는 경우 네트워크 인프라에서 API 포트를 열어야 할 수 있습니다.

API 포트가 Looker 서버로 전달되어야 합니다. 고객 호스팅 Looker 배포의 경우 네트워크 관리자에게 API 포트 설정을 확인하도록 요청하세요. API 포트는 가장 일반적으로 443 또는 19999입니다. API 포트의 구성 설정은 Looker 인스턴스 포트(기본적으로 9999)와 동일해야 합니다. 네트워크 관리자는 API 포트에 대한 다음 설정이 Looker 인스턴스 포트와 동일한지 확인해야 합니다.

  • 프록시
  • 부하 분산기
  • 방화벽

API 호출 URL 확인

API 호출에 올바른 URL을 사용하고 있는지 확인하세요. API 엔드포인트 URL의 형식은 다음과 같습니다.

<API Host URL>/api/<API version>/<API call>

기본 API 호스트 URL을 사용하는 경우 API 엔드포인트 URL의 형식은 다음과 같습니다.

https://<instance_name>:<port>/api/<API version>/<API call>

API 탐색기 또는 API 참조 문서에서 API 엔드포인트의 URL 형식을 가져올 수 있습니다.

예를 들어 API 4.0 참조는 실행 중인 모든 쿼리 가져오기 엔드포인트에 대해 다음과 같은 상대 경로를 제공합니다.

/api/4.0/running_queries

따라서 docsexamples.dev.looker.com Looker 인스턴스에서 실행 중인 모든 쿼리 가져오기 엔드포인트에 대한 전체 API 엔드포인트 URL은 다음과 같습니다.

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

API 결과가 무의미한 텍스트임

API가 잘못된 텍스트 응답을 반환하는 경우 PDF, PNG, JPG 파일의 바이너리 콘텐츠가 표시될 가능성이 높습니다. 일부 HTTP REST 라이브러리에서는 API 응답이 텍스트 파일일 것으로 가정하므로 다른 유형의 파일은 바이너리 텍스트로 표시됩니다.

이 경우 HTTP REST 라이브러리가 API 응답을 텍스트가 아닌 바이너리 데이터로 처리하는지 확인해야 합니다. 경우에 따라 API 호출에 플래그를 설정하여 HTTP REST 라이브러리에 바이너리 결과임을 알려주거나 결과를 문자열 변수에 할당하는 대신 바이트 스트림이나 바이트 배열과 같은 특수한 방식으로 처리하는 것을 의미할 수 있습니다.

API 호출이 응답하지 않음

API 탐색기를 열 수 있지만 API 호출이 응답하지 않으면 Looker 인스턴스의 API 호스트 URL 설정이 올바르게 설정되었는지 확인합니다. Looker 관리자는 Looker의 API 관리자 설정에서 API 호스트 URL을 확인할 수 있습니다(관리자 설정 - API 문서 페이지 참조).

잘못된 인코딩 오류

API 호출을 시도할 때 인코딩 오류가 발생하면 요청 중에 헤더에 적절한 Content-Type을 설정해야 할 수 있습니다. HTTP 프로토콜 표준에는 POST, PUT 또는 PATCH 요청에 Content-Type 헤더가 포함되어야 합니다. Looker API는 전반적으로 JSON을 사용하므로 Content-Type 헤더를 application/json으로 설정해야 합니다.

Looker SDK를 사용하면 이 문제가 자동으로 처리됩니다.

메서드를 찾을 수 없음 오류

method not found: all_looks()와 같은 메서드를 찾을 수 없음 오류가 발생할 경우 가장 먼저 API 버전을 확인해야 합니다. API 4.0에 새로 추가되거나 API 4.0에서 삭제된 API 호출이 여러 개 있습니다. 업데이트 목록은 Looker API 4.0 정식 버전 공지를 참조하세요.

잘못된 요청(400) 오류

400 Bad Request 오류는 API 호출에 제공된 데이터를 인식할 수 없음을 나타냅니다. 이로 인해 JSON이 손상되거나 잘못된 경우가 많으며 파싱 오류가 있을 수 있습니다. 대부분의 경우 400 오류가 이미 인증을 통과했으므로 오류 응답 메시지에서 오류에 대한 세부정보를 제공합니다.

승인되지 않음(401) 오류

API 호출에 401 Unauthorized 오류가 발생하면 API 호출이 올바르게 인증되지 않았음을 의미합니다. 자세한 문제 해결 방법은 401 오류 문제를 어떻게 해결하나요?를 참고하세요. 커뮤니티 자료

금지됨(403) 오류

Looker API는 사용자가 권한이 없는 LookML 객체 또는 기타 콘텐츠에 액세스하려고 할 때마다 403 오류를 반환하지 않습니다. 404 오류 대신 403 오류가 반환되면 소유자가 알리지 않으려 하는 특정 Explore, 대시보드 또는 LookML 객체의 존재를 확인할 수도 있습니다. 이를 방지하기 위해 Looker는 이러한 경우 404를 반환하고 Looker UI에 '요청하신 페이지를 찾을 수 없습니다' 오류가 표시됩니다. 존재하지 않거나 볼 권한이 없습니다.

Looker 인스턴스가 호스팅되는 환경 및 Looker 인스턴스의 구성에 따라 API에 액세스할 수 있는 포트 번호 및 관련 URL이 다를 수 있습니다. 잘못된 포트 번호를 사용할 경우 403 오류가 표시될 수 있습니다. 예를 들어 Looker 인스턴스가 기본 API 포트 443으로 구성된 경우 https://mycompany.looker.com:443/api/4.0/login 대신 https://mycompany.looker.com/api/4.0/login에 연결하면 403 오류가 반환됩니다. 고객 호스팅 인스턴스의 경우 API 포트를 정의할 수 있는 Looker 시작 옵션에 대해 자세히 알아볼 수 있습니다.

이 문제는 또한 Ruby SDK gem의 오래된 버전을 사용하는 경우에도 발생할 수 있습니다. 해당 gem을 최신 상태로 유지하세요. https://rubygems.org/gems/looker-sdk에서 확인할 수 있습니다.

URL의 /api/<version number>/ 부분을 포함하지 않는 경우에도 이 오류가 발생할 수 있습니다. 이 경우 사용자가 https://mycompany.looker.com:443/login에 연결하려고 하면 403 응답이 표시됩니다.

찾을 수 없음(404) 오류

404 Not Found 오류는 일반적으로 권한과 같은 문제가 발생할 때의 기본 오류입니다. 404 오류에 대한 응답 메시지는 최소한의 정보를 제공합니다. 이는 잘못된 로그인 사용자 인증 정보 또는 권한이 부족한 사용자에게 404 오류가 표시되기 때문에 의도된 것입니다. Looker API의 '공격 표면'을 매핑하는 데 이 정보를 사용할 수 있으므로 Looker는 404 응답 메시지에 특정 정보를 제공하지 않습니다.

API 로그인 시도가 404 오류를 반환하는 경우 API 클라이언트 ID나 클라이언트 보안 비밀번호가 유효하지 않기 때문일 수 있습니다(이 페이지의 앞부분에 있는 API 사용자 인증 정보 확인 참조). API 로그인 REST 엔드포인트는 다음과 같습니다.

  • https://<your-looker-hostname>:<port>/api/4.0/login

Swagger codegen API 또는 Looker SDK를 사용하는 경우 base_url 값이 올바른지 확인합니다.

  • Swagger codegen 클라이언트의 경우 base_url은 다음과 같아야 합니다.

    • https://<your-looker-hostname>:<port>/api/4.0/

  • looker.ini를 사용하는 Looker SDK 구현의 경우 api_version 값은 4.0이어야 하며 base_url 값은 https://<your-looker-hostname>:<port> 형식의 Looker 인스턴스 API의 URL과 동일해야 합니다. looker.ini 파일 예시는 다음과 같습니다.

    # api_version should be 4.0
api_version=4.0
base_url=https://<your-looker-hostname>:<port>

로그인 후 404 오류도 발생할 수 있습니다. 로그인한 후 404 오류가 발생하는 경우 방금 호출한 API 명령어에 대한 권한이 없는 것입니다.

허용되지 않는 메서드(405) 오류

405 Method Not Allowed 오류는 서버가 요청 메서드를 알고 있지만 대상 리소스가 이 메서드를 지원하지 않음을 나타냅니다.

서버는 405 상태 코드 응답에 Allow 헤더 필드를 생성해야 합니다. 필드에는 대상 리소스가 지원하는 메서드 목록이 포함되어야 합니다.

예를 들어 Looker에서 이 문제가 발생할 수 있는 한 가지 방법은 update_dashboard() 엔드포인트를 사용하여 LookML 대시보드의 메타데이터를 업데이트하려고 시도하는 것입니다. LookML 대시보드의 id 매개변수 변경은 Looker API를 통해 지원되지 않으므로 405 오류가 발생합니다.

충돌(409) 오류

409 Conflict 응답 상태 코드는 대상 리소스의 현재 상태와 충돌하는 요청을 나타냅니다.

PUT 요청에 대한 응답으로 충돌이 발생할 가능성이 가장 높습니다. 이 오류의 일반적인 Looker 외 예시는 서버의 기존 파일보다 오래된 파일을 업로드할 때 발생하며, 버전 제어 충돌을 초래합니다.

API를 사용하여 새 git 브랜치를 체크아웃하려고 하거나 create_group() 또는 create_dashboard()와 같은 엔드포인트를 사용할 때 Looker에서 이 오류가 발생할 수 있습니다. 이 경우 만들려는 객체가 이미 존재하는지 확인합니다.

검증(422) 오류

검증 오류는 요청의 어느 항목이 데이터 검사 수행에 실패할 때 발생합니다. 요청에 다음 유형의 오류가 하나 이상 있습니다(오류 응답은 정확한 오류를 지정함).

  • 누락된 필드: 제공되지 않은 필수 매개변수가 있습니다(오류 응답에는 누락된 필드가 표시됨).
  • 잘못됨: 제공된 값이 기존 값과 일치하지 않거나 값이 올바른 형식이 아닙니다. 예를 들어 Looker를 생성하려는 경우 API 호출에서 제공하는 쿼리 ID가 기존 쿼리와 일치하지 않으면 검증 오류가 발생합니다.
  • 이미 존재함: API 호출에서 Looker 인스턴스에 이미 존재하는 ID 또는 이름으로 객체를 만들려고 합니다. 예를 들어 데이터베이스 연결 이름은 고유해야 합니다. 기존 연결 이름을 사용하는 새 데이터베이스 연결을 만들려고 하면 already_exists 코드와 함께 검증 오류가 발생합니다.

누락되었거나 필요한 필드 또는 잘못된 값을 가질 수 있는 필드에 대한 자세한 내용은 오류 응답 메시지를 참조하십시오. 응답 메시지는 모든 검증 오류를 동시에 제공합니다. 따라서 누락된 필드와 잘못된 필드가 있는 경우 오류 응답에 API 호출과 관련된 모든 문제가 나열됩니다.

응답 예시는 다음과 같습니다.

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

이 경우 API 호출에 필수 dialect 필드가 누락되었으며 db_timezone에 잘못된 값도 지정되었습니다.

요청한 횟수가 너무 많음(429) 오류

429 Too Many Requests 응답 상태 코드는 사용자가 일정 시간 동안 너무 많은 요청을 보냈음을 나타냅니다('비율 제한'). Looker의 커뮤니티 게시 게시물에서 Looker의 비율 제한 정책에 대해 자세히 알아볼 수 있습니다. 한 번에 전송할 수 있는 API 요청 수에 제한이 있나요?

내부 서버 오류(500) 오류

500 Internal Server Error 응답 코드는 서버에서 요청을 수행할 수 없는 예기치 않은 조건을 발생했음을 나타냅니다.

이 오류 응답은 일반적인 '포괄' 응답입니다. 이는 일반적으로 서버가 응답으로 반환할 더 구체적인 5xx 오류 코드를 찾을 수 없음을 나타냅니다. Looker에서 500 응답은 예기치 않은 응답이므로 Looker와의 상호작용을 시도하는 중에 이 오류가 지속적으로 표시되면 지원 요청을 제출하는 것이 좋습니다.