콘텐츠로 이동

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 생성

  1. Guance 워크스페이스에 접속합니다.
  2. 왼쪽 탐색 모음에서 관리 > API Key 관리를 클릭합니다.
  3. 오른쪽 상단의 Key 생성을 클릭합니다.
  4. 이름, 역할, 비고를 구성합니다.
  5. 생성이 완료되면 API Key 상세 페이지로 이동하여 Key(비밀키)를 복사합니다.

자세한 내용은 API Keys 관리를 참조하세요.

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 준비

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를 전달해야 합니다.

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 네임스페이스는 설치된 SDK 패키지와 일치해야 합니다. use 문의 코드 식별자는 번역할 필요가 없습니다.

<?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가 자동으로 요청 헤더에 추가합니다.

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
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
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
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를 우선적으로 확인합니다.

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 메트릭을 조회하는 예시입니다:

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 데이터 조회 시 기본적으로 관리자 역할로 수행되지만, 데이터 액세스 규칙의 제한을 받을 수 있습니다.

문제 해결 체크리스트

첫 번째 호출이 실패한 경우 다음 순서로 확인합니다:

  1. DF_OPENAPI_ENDPOINT가 현재 사이트에 해당하는 Open API 주소인지 확인합니다.
  2. DF_API_KEY에 API Key 상세 페이지의 Key(비밀키) 값이 입력되었는지 확인합니다. Key ID가 아닙니다.
  3. API Key가 속한 워크스페이스가 조회하거나 수정하려는 워크스페이스인지 확인합니다.
  4. API Key 역할에 대상 인터페이스에 필요한 권한이 있는지 확인합니다.
  5. Query, Path, Body 매개변수가 대응하는 SDK 매개변수에 전달되었는지 확인합니다.
  6. 목록 인터페이스에 적절한 pageIndex와 pageSize가 설정되었는지 확인합니다.
  7. API Key 또는 워크스페이스 수준 요청 제한이 트리거되었는지 확인합니다.
  8. 오류 메시지의 traceId를 기록해 두어 이후 문제 해결에 활용합니다.

관련 문서

  • 개요: Endpoint, 인증 방식 및 공통 응답 구조를 확인할 수 있습니다.
  • 공통 요청 매개변수: 공통 Header를 확인할 수 있습니다.
  • 요청 예시: GET / POST의 원시 curl 호출 방식을 확인할 수 있습니다.
  • API Keys 관리: API Key 생성 및 권한 구성을 확인할 수 있습니다.
  • Open API 인증 설명: Open API 인증 방식, 라우팅 규칙, 반환 결과를 확인할 수 있습니다.
  • DQL 조회: DQL 문법 설명을 확인할 수 있습니다.

문서 평가

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