OpenAPI SDK¶
OpenAPI SDK는 다양한 개발 언어에서 Guance Open API를 호출하기 위해 사용됩니다. SDK는 모듈별로 인터페이스를 캡슐화하고 URL 결합, DF-API-KEY 인증, 요청 매개변수 인코딩, 공통 응답 구조 및 SDK 오류를 처리합니다.
현재 SDK 목록은 GitHub 저장소 링크를 제공하며, 개발 언어에 따라 해당 SDK를 선택할 수 있습니다.
| 개발 언어 | SDK | 설명 |
|---|---|---|
| Python | Python SDK | Python SDK for Guance OpenAPI |
| JavaScript / TypeScript | JavaScript / TypeScript SDK | Node.js 18+ / TypeScript SDK |
| Java | Java SDK | Java SDK for Guance OpenAPI |
| PHP | PHP SDK | PHP 8.1+ SDK |
빠른 시작¶
다음 단계에 따라 준비한 후 SDK를 사용하여 Open API를 호출할 수 있습니다.
1 권한 확인¶
API Key 생성 및 관리를 위해서는 워크스페이스의 관리자 또는 Owner 권한이 필요합니다. 최소 권한 원칙에 따라 API Key 역할을 선택하고, 실제 필요한 권한을 초과하는 권한은 사용하지 않는 것이 좋습니다.
2 API Key 생성¶
- Guance 워크스페이스에 접속합니다.
- 왼쪽 탐색 모음에서 관리 > API Key 관리를 클릭합니다.
- 오른쪽 상단의 Key 생성을 클릭합니다.
- 이름, 역할, 비고를 구성합니다.
- 생성이 완료되면 API Key 상세 페이지로 이동하여 Key(비밀키)를 복사합니다.
자세한 내용은 API Keys 관리를 참조하세요.
3 Open API Endpoint 선택¶
SDK 초기화 시 Open API Endpoint를 전달해야 합니다. 일반적인 SaaS Endpoint는 다음과 같습니다.
더 많은 사이트 Endpoint는 개요를 참조하세요. 프라이빗 배포 플랜은 실제 배포된 Endpoint를 기준으로 합니다.
4 환경 변수 설정¶
Endpoint와 API Key를 먼저 환경 변수에 저장해 두면 이후 각 언어 예제에서 바로 재사용할 수 있습니다.
5 언어 선택 및 SDK 준비¶
SDK 저장소에는 dist 빌드 산출물이 이미 포함되어 있습니다. 비즈니스 프로젝트에 통합할 때는 저장소 README에 따라 @guance/openapi-sdk를 사용할 수 있습니다.
로컬 Maven 저장소에 설치해야 하는 경우 다음을 실행할 수 있습니다:
6 Client 초기화¶
Client를 초기화할 때 최소한 Endpoint와 API Key를 전달해야 합니다.
첫 번째 호출¶
첫 번째 호출은 읽기 전용 인터페이스를 선택하는 것이 좋습니다. 예를 들어 "대시보드 목록 조회"가 있습니다. 이 인터페이스는 Open API 문서의 대시보드 목록 조회에 해당합니다:
SDK 호출 시 비즈니스 매개변수만 전달하면 되며, DF-API-KEY는 SDK가 자동으로 요청 헤더에 추가합니다.
호출이 성공하면 응답의 success는 true, code는 200이며, 비즈니스 데이터는 content에 있습니다.
매개변수 입력 방법¶
각 인터페이스 문서를 읽을 때 먼저 인터페이스 제목 아래의 요청 메서드와 경로를 확인한 후 매개변수의 위치를 확인합니다. Open API는 GET과 POST 두 가지 요청 방식만 사용합니다. GET은 데이터 조회 및 획득에, POST는 생성, 수정, 삭제 등 데이터 변경에 사용됩니다.
| 인터페이스 문서의 매개변수 위치 | SDK 매개변수 | 예시 |
|---|---|---|
| Query 요청 매개변수 | query |
{"pageIndex": 1, "pageSize": 10} |
| 경로 매개변수 | path |
{"dashboard_uuid": "dsbd_xxxx32"} |
| Body 요청 매개변수 | body |
{"name": "demo workspace"} |
| 추가 요청 헤더 | headers |
{"X-Source": "internal-tool"} |
Query 매개변수¶
Query 매개변수는 URL 쿼리 문자열로 인코딩됩니다. 대시보드 목록 조회를 예로 들면:
경로 매개변수¶
경로 매개변수는 인터페이스 경로의 변수를 대체합니다. 특정 대시보드 조회를 예로 들면:
Body 매개변수¶
Body 매개변수는 POST 요청에 사용됩니다. 현재 워크스페이스 수정을 예로 들면:
응답 확인 방법¶
Open API는 통일된 응답 구조를 사용합니다. 주요 필드는 다음과 같습니다:
| 필드 | 설명 |
|---|---|
code |
반환 상태 코드로, HTTP 상태 코드와 동일하며 오류가 없을 때 항상 200입니다 |
content |
비즈니스 데이터로, 구체적인 유형은 인터페이스에 따라 결정됩니다 |
pageInfo |
목록 인터페이스의 페이징 정보 |
errorCode |
오류 상태 코드로, 비어 있으면 오류가 없음을 의미합니다 |
message |
오류 설명 |
success |
인터페이스 호출 성공 여부 |
traceId |
요청 추적 ID로, 문제 해결에 사용됩니다 |
목록 인터페이스는 일반적으로 content와 pageInfo를 함께 반환합니다. 예를 들어 pageInfo.totalCount는 조건에 해당하는 전체 데이터 수를 나타냅니다.
오류 처리 방법¶
SDK는 Open API 오류를 해당 언어의 예외 유형으로 래핑합니다. 문제를 해결할 때는 HTTP 상태 코드, errorCode, message, traceId를 우선적으로 확인합니다.
try {
ApiResponseEnvelope response = client.board.list(
RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
);
} catch (ApiException error) {
System.out.println(error.httpStatus);
System.out.println(error.errorCode);
System.out.println(error.traceId);
System.out.println(error.envelope.rawBody);
}
일반적인 오류 및 제한 사항:
| 시나리오 | 설명 |
|---|---|
| API Key 무효 | ft.InvalidAPIKey 반환 |
| API Key 수준 요청 제한 | 동일한 API Key는 분당 최대 200회 요청할 수 있으며, 초과 시 ft.TriggerApiAkCurrentLimiting 반환 |
| 워크스페이스 수준 요청 제한 | 동일한 워크스페이스는 분당 최대 1000회 Open API 호출을 지원하며, 초과 시 ft.TriggerApiWorkspaceCurrentLimiting 반환 |
자세한 내용은 공통 응답 구조, 공통 오류 정의, 사용 제한을 참조하세요.
데이터 조회 예시¶
메트릭, 로그, 이벤트 등 데이터를 조회해야 하는 경우 DQL 데이터 조회 인터페이스를 사용할 수 있습니다. DQL 문법 설명은 DQL 조회, 인터페이스 설명은 DQL 데이터 조회를 참조하세요.
다음은 cpu 메트릭을 조회하는 예시입니다:
const response = await client.queryData.queryDataV1({
body: {
queries: [
{
qtype: "dql",
query: {
q: "M::`cpu`:(avg(`usage_idle`))",
timeRange: [1708911106000, 1708912906999],
interval: 10,
maxPointCount: 720,
tz: "Asia/Shanghai",
},
},
],
fieldTagDescNeeded: false,
},
});
console.log(response.content);
RequestOptions req = RequestOptions.create();
req.bodyJson = """
{
"queries": [
{
"qtype": "dql",
"query": {
"q": "M::`cpu`:(avg(`usage_idle`))",
"timeRange": [1708911106000, 1708912906999],
"interval": 10,
"maxPointCount": 720,
"tz": "Asia/Shanghai"
}
}
],
"fieldTagDescNeeded": false
}
""";
QueryDataContent content = client.queryData.queryDataV1Content(req);
System.out.println(content.data);
$response = $client->queryData->queryDataV1([
'body' => [
'queries' => [[
'qtype' => 'dql',
'query' => [
'q' => 'M::`cpu`:(avg(`usage_idle`))',
'timeRange' => [1708911106000, 1708912906999],
'interval' => 10,
'maxPointCount' => 720,
'tz' => 'Asia/Shanghai',
],
]],
'fieldTagDescNeeded' => false,
],
]);
var_dump($response->content);
주의
Open API 데이터 조회 시 기본적으로 관리자 역할로 수행되지만, 데이터 액세스 규칙의 제한을 받을 수 있습니다.
문제 해결 체크리스트¶
첫 번째 호출이 실패한 경우 다음 순서로 확인합니다:
DF_OPENAPI_ENDPOINT가 현재 사이트에 해당하는 Open API 주소인지 확인합니다.DF_API_KEY에 API Key 상세 페이지의 Key(비밀키) 값이 입력되었는지 확인합니다. Key ID가 아닙니다.- API Key가 속한 워크스페이스가 조회하거나 수정하려는 워크스페이스인지 확인합니다.
- API Key 역할에 대상 인터페이스에 필요한 권한이 있는지 확인합니다.
- Query, Path, Body 매개변수가 대응하는 SDK 매개변수에 전달되었는지 확인합니다.
- 목록 인터페이스에 적절한
pageIndex와pageSize가 설정되었는지 확인합니다. - API Key 또는 워크스페이스 수준 요청 제한이 트리거되었는지 확인합니다.
- 오류 메시지의
traceId를 기록해 두어 이후 문제 해결에 활용합니다.
관련 문서¶
- 개요: Endpoint, 인증 방식 및 공통 응답 구조를 확인할 수 있습니다.
- 공통 요청 매개변수: 공통 Header를 확인할 수 있습니다.
- 요청 예시: GET / POST의 원시 curl 호출 방식을 확인할 수 있습니다.
- API Keys 관리: API Key 생성 및 권한 구성을 확인할 수 있습니다.
- Open API 인증 설명: Open API 인증 방식, 라우팅 규칙, 반환 결과를 확인할 수 있습니다.
- DQL 조회: DQL 문법 설명을 확인할 수 있습니다.