OpenAPI SDK¶

OpenAPI SDK는 다양한 프로그래밍 언어에서 Guance Open API를 호출하기 위해 사용됩니다. SDK는 모듈별로 인터페이스를 캡슐화하며, URL拼接, DF-API-KEY 인증, 요청 파라미터 인코딩, 공통 응답 구조 및 SDK 오류를 처리합니다.

현재 SDK 목록은 GitHub 저장소 링크를 제공하며, 프로그래밍 언어에 따라 해당 SDK를 선택할 수 있습니다.

프로그래밍 언어	SDK	설명
Python	Python SDK	Guance OpenAPI용 Python SDK
JavaScript / TypeScript	JavaScript / TypeScript SDK	Node.js 18+ / TypeScript SDK
Java	Java SDK	Guance OpenAPI용 Java SDK
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 Key 관리를 참조하세요.

3 Open API Endpoint 선택¶

SDK 초기화 시 Open API Endpoint를 전달해야 합니다. 일반적인 SaaS Endpoint는 다음과 같습니다.

https://openapi.guance.com

추가 사이트 Endpoint는 개요를 참조하세요. 프라이빗 배포판의 경우, 실제 배포된 Endpoint를 기준으로 합니다.

4 환경 변수 설정¶

Endpoint와 API Key를 환경 변수에 먼저 저장해 두면, 이후 각 언어 예제에서 바로 재사용할 수 있습니다.

export DF_OPENAPI_ENDPOINT="https://openapi.guance.com"
export DF_API_KEY="여기에 API Key를 입력하세요"

5 언어 선택 및 SDK 준비¶

PythonJavaScript / TypeScriptJavaPHP

git clone https://github.com/GuanceCloud/guance-sdk-py.git
cd guance-sdk-py
python3 -m pip install -e .

git clone https://github.com/GuanceCloud/guance-sdk-js.git
cd guance-sdk-js
node --version

SDK 저장소에는 dist 산출물이 이미 포함되어 있습니다. 비즈니스 프로젝트에 통합할 때는 저장소의 README를 참조하여 @guance/openapi-sdk를 사용하세요.

git clone https://github.com/GuanceCloud/guance-sdk-java.git
cd guance-sdk-java
mvn test

로컬 Maven 저장소에 설치하려면 다음을 실행하세요.

mvn install

git clone https://github.com/GuanceCloud/guance-sdk-php.git
cd guance-sdk-php
composer dump-autoload

6 Client 초기화¶

Client 초기화 시 최소한 Endpoint와 API Key가 필요합니다.

PythonJavaScript / TypeScriptJavaPHP

import os
from guance_openapi_sdk import Client

client = Client(
    api_key=os.environ["DF_API_KEY"],
    base_url=os.environ["DF_OPENAPI_ENDPOINT"],
    timeout=30,
)

import { Client } from "@guance/openapi-sdk";

const client = new Client({
  apiKey: process.env.DF_API_KEY,
  baseUrl: process.env.DF_OPENAPI_ENDPOINT,
  timeoutMs: 30_000,
});

Client client = new Client(
    System.getenv("DF_OPENAPI_ENDPOINT"),
    System.getenv("DF_API_KEY")
);

<?php

use Guance\OpenAPI\Client;

$client = new Client(
    baseUrl: getenv('DF_OPENAPI_ENDPOINT'),
    apiKey: getenv('DF_API_KEY'),
    timeoutSeconds: 30,
);

첫 번째 호출¶

첫 번째 호출은 "대시보드 목록 가져오기"와 같은 읽기 전용 인터페이스를 선택하는 것이 좋습니다. 이 인터페이스는 Open API 문서의 대시보드 목록 가져오기에 해당합니다.

GET /api/v1/dashboards/list?pageIndex=1&pageSize=10

SDK 호출 시 비즈니스 파라미터만 전달하면 됩니다. DF-API-KEY는 SDK가 자동으로 요청 헤더에 추가합니다.

PythonJavaScript / TypeScriptJavaPHP

response = client.board.list(query={"pageIndex": 1, "pageSize": 10})

print(response.content)
print(response.page_info)
print(response.trace_id)

const response = await client.board.list({
  query: { pageIndex: 1, pageSize: 10 },
});

console.log(response.content);
console.log(response.pageInfo);
console.log(response.traceId);

ApiResponseEnvelope response = client.board.list(
    RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
);

System.out.println(response.contentJson);
System.out.println(response.pageInfo);
System.out.println(response.traceId);

$response = $client->board->list([
    'query' => ['pageIndex' => 1, 'pageSize' => 10],
]);

var_dump($response->content);
var_dump($response->pageInfo);
var_dump($response->traceId);

호출에 성공하면 응답의 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 쿼리 문자열로 인코딩됩니다. 대시보드 목록 가져오기를 예로 들면 다음과 같습니다.

GET /api/v1/dashboards/list?pageIndex=1&pageSize=10

PythonJavaScript / TypeScriptJavaPHP

response = client.board.list(query={"pageIndex": 1, "pageSize": 10})

const response = await client.board.list({
  query: { pageIndex: 1, pageSize: 10 },
});

ApiResponseEnvelope response = client.board.list(
    RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
);

$response = $client->board->list([
    'query' => ['pageIndex' => 1, 'pageSize' => 10],
]);

경로 파라미터¶

경로 파라미터는 인터페이스 경로의 변수를 대체합니다. 특정 대시보드 가져오기를 예로 들면 다음과 같습니다.

GET /api/v1/dashboards/{dashboard_uuid}/get

PythonJavaScript / TypeScriptJavaPHP

response = client.board.get(path={"dashboard_uuid": "dsbd_xxxx32"})

const response = await client.board.get({
  path: { dashboard_uuid: "dsbd_xxxx32" },
});

RequestOptions req = RequestOptions.create();
req.path.put("dashboard_uuid", "dsbd_xxxx32");
ApiResponseEnvelope response = client.board.get(req);

$response = $client->board->get([
    'path' => ['dashboard_uuid' => 'dsbd_xxxx32'],
]);

Body 파라미터¶

Body 파라미터는 POST 요청에 사용됩니다. 현재 워크스페이스 수정을 예로 들면 다음과 같습니다.

POST /api/v1/workspace/modify

PythonJavaScript / TypeScriptJavaPHP

response = client.workspace.modify(body={"name": "demo workspace"})

const response = await client.workspace.modify({
  body: { name: "demo workspace" },
});

RequestOptions req = RequestOptions.create();
req.bodyJson = "{\"name\":\"demo workspace\"}";
ApiResponseEnvelope response = client.workspace.modify(req);

$response = $client->workspace->modify([
    'body' => ['name' => 'demo workspace'],
]);

응답 확인 방법¶

Open API는 통일된 응답 구조를 사용합니다. 일반적으로 사용되는 필드는 다음과 같습니다.

필드	설명
`code`	반환되는 상태 코드로, HTTP 상태 코드와 동일하며 오류가 없으면 항상 `200`입니다.
`content`	비즈니스 데이터로, 구체적인 유형은 인터페이스에 따라 결정됩니다.
`pageInfo`	목록 인터페이스의 페이지 정보입니다.
`errorCode`	오류 상태 코드로, 비어 있으면 오류가 없음을 의미합니다.
`message`	오류 설명입니다.
`success`	인터페이스 호출 성공 여부입니다.
`traceId`	요청 추적 ID로, 문제 해결에 사용됩니다.

목록 인터페이스는 일반적으로 content와 pageInfo를 함께 반환합니다. 예를 들어 pageInfo.totalCount는 조건에 맞는 총 데이터 수를 나타냅니다.

오류 처리 방법¶

SDK는 Open API 오류를 해당 언어의 예외 유형으로 래핑합니다. 문제 해결 시 HTTP 상태 코드, errorCode, message 및 traceId를 우선적으로 확인하세요.

PythonJavaScript / TypeScriptJavaPHP

from guance_openapi_sdk import ApiError

try:
    response = client.board.list(query={"pageIndex": 1, "pageSize": 10})
except ApiError as error:
    print(error.status)
    print(error.error_code)
    print(error.trace_id)
    print(error.envelope)

import { ApiError } from "@guance/openapi-sdk";

try {
  const response = await client.board.list({
    query: { pageIndex: 1, pageSize: 10 },
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status, error.errorCode, error.traceId);
    console.log(error.envelope);
  }
}

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);
}

use Guance\OpenAPI\ApiException;

try {
    $response = $client->board->list([
        'query' => ['pageIndex' => 1, 'pageSize' => 10],
    ]);
} catch (ApiException $error) {
    echo $error->httpStatus . PHP_EOL;
    echo $error->errorCode . PHP_EOL;
    echo $error->traceId . PHP_EOL;
}

일반적인 오류 및 제한 사항:

시나리오	설명
API Key가 유효하지 않음	`ft.InvalidAPIKey` 반환
API Key 수준 속도 제한	동일한 API Key는 분당 최대 200회 요청 가능, 초과 시 `ft.TriggerApiAkCurrentLimiting` 반환
워크스페이스 수준 속도 제한	동일한 워크스페이스는 분당 최대 1000회 Open API 호출 가능, 초과 시 `ft.TriggerApiWorkspaceCurrentLimiting` 반환

자세한 내용은 공통 응답 구조, 공통 오류 정의 및 사용 제한을 참조하세요.

데이터 조회 예시¶

메트릭, 로그, 이벤트 등의 데이터를 조회해야 하는 경우 DQL 데이터 조회 인터페이스를 사용할 수 있습니다. DQL 구문 설명은 DQL 조회를, 인터페이스 설명은 DQL 데이터 조회를 참조하세요.

다음 예시는 cpu 메트릭을 조회합니다.

PythonJavaScript / TypeScriptJavaPHP

response = client.query_data.query_data_v1(body={
    "queries": [
        {
            "qtype": "dql",
            "query": {
                "q": "M::`cpu`:(avg(`usage_idle`))",
                "timeRange": [1708911106000, 1708912906999],
                "interval": 10,
                "maxPointCount": 720,
                "tz": "Asia/Shanghai",
            },
        }
    ],
    "fieldTagDescNeeded": False,
})

print(response.content)

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가 기록되어 이후 문제 해결에 사용할 수 있는지 확인합니다.

OpenAPI SDK¶

빠른 시작¶

1 권한 확인¶

2 API Key 생성¶

3 Open API Endpoint 선택¶

4 환경 변수 설정¶

5 언어 선택 및 SDK 준비¶

6 Client 초기화¶

첫 번째 호출¶

파라미터 입력 방법¶

Query 파라미터¶

경로 파라미터¶

Body 파라미터¶

응답 확인 방법¶

오류 처리 방법¶

데이터 조회 예시¶

문제 해결 체크리스트¶

관련 문서¶

이 페이지가 도움이 되었나요?

OpenAPI SDK¶

빠른 시작¶

1 권한 확인¶

2 API Key 생성¶

3 Open API Endpoint 선택¶

4 환경 변수 설정¶

5 언어 선택 및 SDK 준비¶

6 Client 초기화¶

첫 번째 호출¶

파라미터 입력 방법¶

Query 파라미터¶

경로 파라미터¶

Body 파라미터¶

응답 확인 방법¶

오류 처리 방법¶

데이터 조회 예시¶

문제 해결 체크리스트¶

관련 문서¶

이 페이지가 도움이 되었나요? ×

이 페이지가 도움이 되었나요?