이 페이지에는 Looker API에서 발생할 수 있는 다음 문제에 대한 문제 해결 절차가 나와 있습니다.
- API 엔드포인트에 연결할 수 없음
- API 결과가 무의미한 텍스트임
- API 호출이 응답하지 않음
- 잘못된 인코딩 오류
- 메서드를 찾을 수 없음 오류
- 잘못된 요청 (400) 오류
- 금지됨 (403) 오류
- 찾을 수 없음 (404) 오류
- 허용되지 않는 방법 (405) 오류
- 충돌 (409) 오류
- 유효성 검사 (422) 오류
- 요청이 너무 많음 (429) 오류
- 내부 서버 오류 (500) 오류
API 엔드포인트에 도달할 수 없습니다.
API 엔드포인트에 도달할 수 없는 경우:
API 사용자 인증 정보 확인하기
Looker API 엔드포인트에 연결할 수 없는 경우 먼저 API 사용자 인증 정보가 올바른지 확인하세요. API 사용자 인증 정보를 보는 방법은 다음과 같습니다.
- Looker에서 왼쪽 탐색 패널의 관리자 옵션을 선택하여 관리자 패널에 액세스합니다.
- 관리 페이지의 왼쪽 패널에서 아래로 스크롤하여 사용자를 클릭합니다.
- 사용자 목록에서 사용자 이름을 검색하고 클릭하여 사용자 페이지를 수정합니다.
- 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을 보려면 다음 안내를 따르세요.
- 왼쪽 탐색 패널에서 관리자 옵션을 선택하여 관리자 패널에 액세스합니다.
- 관리자 패널에서 API를 클릭합니다.
API 호스트 URL을 확인합니다.
API 호스트 URL 필드가 비어 있으면 Looker 인스턴스는 기본 형식인 다음과 같은 형식을 사용합니다.
https://<instance_name>.looker.com:<port>
API 호스트 URL을 테스트하는 방법은 다음과 같습니다.
- 브라우저를 열고 브라우저 콘솔을 엽니다. 브라우저용 콘솔을 여는 방법을 알아야 하는 경우 ConcreteCMS.org의 이 도움말이 도움이 될 수 있습니다.
API 호스트 URL을 입력한 다음
/alive를 입력합니다. 예를 들어 API 호스트 URL이https://company.api.looker.com이면 다음을 입력합니다.https://company.api.looker.com/aliveAPI 호스트 URL 입력란이 비어 있으면 기본 API URL을 사용합니다. 예를 들어 Google Cloud, Microsoft Azure에서 호스팅되는 인스턴스 및 2020년 7월 7일 이후에 생성된 Amazon Web Services (AWS)에서 호스팅되는 인스턴스의 경우 기본 Looker API 경로가 포트
443을 사용합니다.https://<instance_name>.looker.com:443/alive2020년 7월 7일 이전에 생성된 AWS에서 호스팅되는 인스턴스의 경우 기본 Looker API 경로는 포트 19999를 사용합니다.
https://<instance_name>.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 탐색기, Looker의 개발자 포털 또는 API 참조 문서에서 API 엔드포인트의 URL 형식을 가져올 수 있습니다.
예를 들어 API 4.0 참조는 모든 실행 중인 쿼리 가져오기 엔드포인트에 다음과 같은 상대 경로를 제공합니다.
따라서 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 문서 페이지 참고)에서 API 호스트 URL을 볼 수 있습니다.
잘못된 인코딩 오류
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 오류가 이미 인증을 통과했으므로 오류 응답 메시지에서 오류에 대한 보다 구체적인 정보를 제공합니다.
Forbidden (403) 오류
사용자가 LookML 객체 또는 권한이 없는 다른 콘텐츠에 액세스하려고 할 때마다 Looker API는 403 오류를 반환하지 않습니다. 404 오류 대신 403 오류를 반환하면 소유자가 알 수 없다고 하는 특정 탐색, 대시보드 또는 LookML 객체가 있는지 확인할 수 있습니다. 이를 방지하기 위해 이러한 경우 Looker에서 404를 반환하며 Looker UI에 함께 발생하는 오류("quot;요청한 페이지)를 찾을 수 없습니다. 보기 권한이 없거나 파일을 볼 권한이 없습니다."
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의 오래된 버전을 사용하는 경우에도 발생할 수 있습니다. 보석을 계속 업데이트하세요. https://rubygems.org/gems/looker-sdk에서 확인할 수 있습니다.
URL의 /api/<version number>/ 부분을 포함하지 않는 경우에도 발생할 수 있습니다. 이 경우 사용자가 https://mycompany.looker.com:443/login에 연결하려고 하면 403 응답이 표시됩니다.
찾을 수 없음 (404) 오류
404 Not Found 오류는 일반적으로 권한이 있는 것과 관련된 문제가 발생할 경우 기본 오류입니다. 404 오류에 대한 응답 메시지는 최소한의 정보만 제공합니다. 이는 잘못된 로그인 사용자 인증 정보 또는 권한이 없는 사용자에게 404 오류가 표시되기 때문에 의도된 것입니다. Looker는 404 응답 메시지에 특정 정보를 제공하고 싶지 않습니다. Looker API의 '공격 표면'을 매핑하는 데 이 정보를 사용할 수 있기 때문입니다.
API 로그인 시도에서 404 오류를 반환하는 것은 API3 클라이언트 ID 또는 클라이언트 보안 비밀번호가 유효하지 않기 때문일 수 있습니다 (이 페이지 앞부분의 API 사용자 인증 정보 확인하기 참고). API 로그인 REST 엔드포인트는 사용 중인 API 버전에 따라 다음 중 하나입니다.
https://<your-looker-hostname>:<port>/api/4.0/login
https://<your-looker-hostname>:<port>/api/3.1/login
Swagger codegen API 또는 Looker SDK를 사용하는 경우 base_url 값이 올바른지 확인하세요.
- Swagger codegen 클라이언트의 경우
base_url는 사용 중인 API 버전에 따라 다음 중 하나여야 합니다.https://<your-looker-hostname>:<port>/api/4.0/https://<your-looker-hostname>:<port>/api/3.1/
looker.ini를 사용하는 Looker SDK 구현의 경우api_version값은4.0또는3.1이고,base_url값은https://<your-looker-hostname>:<port>형식의 Looker 인스턴스 API의 URL과 동일해야 합니다.looker.ini파일의 예는 다음과 같습니다.# api_version should be either 4.0 or 3.1 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 API의 id 매개변수 변경은 Looker API를 통해 지원되지 않으므로 405 오류가 발생합니다.
충돌 (409) 오류
409 Conflict 응답 상태 코드는 요청이 대상 리소스의 현재 상태와 충돌함을 나타냅니다.
충돌은 PUT 요청에 대한 응답으로 발생할 가능성이 높습니다. 이 오류는 Looker에서 서버의 기존 파일보다 오래된 파일을 업로드할 때 발생하므로 버전 제어 충돌이 발생합니다.
API를 사용하여 새 git 브랜치를 체크아웃하려고 하거나 create_group() 또는 create_dashboard() 같은 엔드포인트를 사용할 때 Looker에서 이 오류가 발생할 수 있습니다. 이러한 경우 생성하려는 객체가 이미 있는지 확인해야 합니다.
유효성 검사 (422) 오류
유효성 검사 오류는 요청의 데이터 검사가 실패한 경우 발생합니다. 요청에 다음 유형의 오류가 하나 이상 있습니다 (오류 응답이 정확한 오류를 지정함).
- 누락된 필드: 필수 매개변수가 제공되지 않았습니다 (오류 응답에 누락된 필드가 표시됨).
- 잘못됨: 제공된 값이 기존 값과 일치하지 않거나 값이 올바른 형식이 아닙니다. 예를 들어 Look을 생성하려고 할 때 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 커뮤니티 도움말에서 한 번에 보낼 수 있는 API 요청 수에 제한이 있나요?에서 Looker의 비율 제한 정책을 자세히 알아볼 수 있습니다.
내부 서버 오류 (500) 오류
500 Internal Server Error 응답 코드는 서버가 요청을 처리하지 못하는 예기치 못한 조건을 발생했음을 나타냅니다.
이 오류 응답은 일반 'catch-all" 응답입니다. 이는 일반적으로 서버에서 반환될 더 구체적인 5xx 오류 코드를 찾을 수 없음을 나타냅니다. Looker에서 500 응답을 받으면 예기치 않게 발생하므로 Looker와 상호작용하려고 할 때 이 오류가 일관되게 표시되면 Looker 지원팀에 문의하는 것이 좋습니다.