OpenAPI SDK¶
OpenAPI SDK は、さまざまな開発言語で Guance Open API を呼び出すために使用します。SDK は API をモジュール単位でラップし、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 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 を渡す必要があります。
最初の呼び出し¶
初回の呼び出しでは、読み取り専用の API(例:「ダッシュボードリスト取得」)を選択することをお勧めします。この API は、Open API ドキュメントの ダッシュボードリスト取得 に対応します:
SDK 呼び出し時は、ビジネスパラメータのみを渡します。DF-API-KEY は SDK が自動的にリクエストヘッダーに設定します。
呼び出しが成功すると、レスポンスの success は true、code は 200 になり、ビジネスデータは content に格納されます。
パラメータの指定方法¶
各 API ドキュメントを読むときは、まず API タイトル下のリクエストメソッドとパスを確認し、次にパラメータの位置を確認します。Open API は GET と POST の 2 種類のリクエストメソッドのみを使用します:GET はデータの照会・取得に、POST は作成・変更・削除などのデータ変更に使用します。
| API ドキュメントでのパラメータ位置 | 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 のクエリ文字列にエンコードされます。ダッシュボードリスト取得 を例にします:
ルートパラメータ¶
ルートパラメータは API パス内の変数を置き換えます。指定ダッシュボード取得 を例にします:
Body パラメータ¶
Body パラメータは POST リクエストで使用します。現在のワークスペースの変更 を例にします:
レスポンスの見方¶
Open API は共通のレスポンス構造を使用します。主なフィールドは次のとおりです:
| フィールド | 説明 |
|---|---|
code |
返されるステータスコード。HTTP ステータスコードと同じで、エラーがない場合は常に 200 です |
content |
ビジネスデータ。具体的な型は API によって異なります |
pageInfo |
リスト API のページネーション情報 |
errorCode |
エラーステータスコード。空の場合はエラーなしです |
message |
エラーの説明 |
success |
API 呼び出しの成否 |
traceId |
リクエスト追跡 ID。問題の調査に使用します |
リスト API は通常、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 データクエリ API を使用できます。DQL の構文は DQL クエリ、API の説明は 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 のロールが対象 API に必要な権限を持っていること。
- Query、Path、Body パラメータが対応する SDK パラメータに指定されていること。
- リスト API で適切な
pageIndexとpageSizeを設定していること。 - API Key またはワークスペースレベルのレート制限に達していないこと。
- エラー情報の
traceIdを記録していること(後続の調査に使用します)。
関連ドキュメント¶
- 概要:Endpoint、認証方式、共通レスポンス構造を確認します。
- 共通リクエストパラメータ:共通 Header を確認します。
- リクエスト例:GET / POST の生の curl 呼び出し方法を確認します。
- API Keys 管理:API Key の作成と権限設定を確認します。
- Open API 認証の説明:Open API の認証方式、ルーティング仕様、戻り値を確認します。
- DQL クエリ:DQL の構文を確認します。