時系列トレンドチャートの取得¶
GET /api/v1/chart_image/get
概要¶
Client Token を使用して DQL または PromQL の時系列クエリを実行し、PNG トレンドチャートを直接ダウンロードします。
呼び出し前の確認と使用手順¶
このインターフェースは Client Token を使用してワークスペースを特定します。DF-API-KEY やログイン Token は不要です。URL 内の Token は適切に保管し、公開ページや共有リンクに書き込まないでください。データアクセスの識別情報はワークスペース API Key とは異なり、API Key のロール権限からこのインターフェースのアクセス制御を推測することはできません。まず対象ワークスペースで時系列文を検証し、スパンがサイトの制限を超えない実データの時間を選択してから、クエリパラメータを URL エンコードして画像をダウンロードします。例の時刻はあくまで参考です。呼び出し前にデータが存在する時間ウィンドウに置き換えてください。
レスポンス成功時は生の PNG バイナリであり、code/content/success/traceId などの JSON 業務フィールドはありません。エラー時は JSON が返る可能性があるため、クライアントは HTTP ステータス、Content-Type、PNG ファイル署名を同時に確認する必要があり、任意の 200 を有効な画像として保存してはいけません。描画失敗時はサーバー側ログに記録されますが、HTTP200、image/png、空の本文が返る可能性があります。空データでも空の座標図が得られることがあり、リクエスト失敗を意味するものではありません。本文が空の場合は、まず文、タイムゾーン、実際のデータを確認し、レスポンスヘッダー内のトレース情報を保持して管理者にフィードバックしてください。
パラメータ表に記載された Query のみをサポートします。内部的には showLegend の読み取りが存在しますが、公開仕様では開放されていないため、このパラメータは送信できません。デフォルトでは凡例を表示しません。結果はキャッシュされず、レスポンスには no-store が設定されます。Token 情報は本プロセスが依存する Redis に 60 秒間キャッシュされるため、失効後も短時間のキャッシュウィンドウが残る可能性があり、即時失効は保証されません。
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| clientToken | string | Y | 必須。有効状態が 0 の Client Token のみを対象とします。前後の空白は除去されます。Token により照会先のワークスペースが決まります。 null を許可: False 例: <CLIENT-TOKEN>取得または入力方法: 現在のワークスペースのClient Token 管理から実際の Token 値をコピーします。Token レコードの UUID や API Key ではありません。 |
| endTime | integer | Y | 必須の整数。10 桁の秒値はミリ秒に変換され、それ以外はミリ秒として扱われます。0 の場合はサーバー側の現在時刻を使用します。最大スパンはサイトの ChartImageSet.maxTimeSc によって制約され、コードのデフォルトは 3600 秒で、管理者が上書きできます。 null を許可: False 例: 1785429000取得または入力方法: クエリの終点を選択します。startTime 以上である必要があり、同じ単位を使用します。 |
| interval | integer | 任意。デフォルトは 60 秒で、内部的に 1000 を乗算してクエリ間隔とします。0 の場合はスパンとサイトのポイント密度に基づいて計算され、最小は 1 ミリ秒です。負の値は 406 となります。実際のポイント数はクエリサービスとポイント密度の制限も受け、各ポイントにデータがあることは保証されません。 null を許可: False 例: 60取得または入力方法: 画像に必要な粒度に応じて正の整数秒を選択します。自動推定の場合は 0 を渡します。 |
|
| q | string | Y | 必須のクエリ文。時間と数値を含むシーケンスを返す必要があります。DQL と PromQL の構文を混在させることはできません。Tag でグループ化すると複数のラインを生成できます。 null を許可: False 例: M::cpu:(avg(usage_idle)) BY host取得または入力方法: 対象ワークスペースのクエリツールでデータが存在することを確認した時系列クエリを指定し、Query を URL エンコードします。 |
| qtype | string | 任意。dql/promql。ダウンストリームでのデフォルト値の処理に依存しないよう、常に明示的に渡すことを推奨します。ルートにはデフォルト値が設定されていないため、省略するとクエリサービスに None が渡されます。 null を許可: False 選択可能な値: ['dql', 'promql'] 例: dql取得または入力方法: クエリ文の種類に応じて dql または promql を明示的に選択します。DQLとPromQLを参照してください。 |
|
| startTime | integer | Y | 必須の整数。10 桁の値は内部的に 1000 を乗算し、それ以外の桁数はミリ秒としてそのまま使用します。桁数判定に依存しないよう、秒で統一して渡すことを推奨します。0 の場合は endTime から 1 時間を減算した値をフォールバックとして使用し、Unix エポックではありません。 null を許可: False 例: 1785427200取得または入力方法: 実際にデータが存在するクエリ開始点を選択し、Unix 秒のタイムスタンプを使用します。 |
| tz | string | 任意。デフォルトは Asia/Shanghai。クエリのアライメントと画像の横軸表示を制御します。Unix タイムスタンプの意味は変更しません。タイムゾーンの列挙チェックはなく、誤った名前を指定するとダウンストリームのクエリが失敗したり、画像が空になったりする可能性があります。 null を許可: False 例: Asia/Shanghai取得または入力方法: 業務上の表示タイムゾーンに応じて IANA タイムゾーン名を選択します。 |
パラメータ補足説明¶
クエリ説明
注意: 現在のインターフェースは clientToken による認証を行います。clientToken が有効な場合にのみ機能します。現在のインターフェースでは、リクエストヘッダー DF-API-KEY を追加しなくてもかまいません。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/chart_image/get' \
--data-urlencode 'clientToken=<CLIENT-TOKEN>' \
--data-urlencode qtype=dql \
--data-urlencode 'q=M::cpu:(avg(usage_idle)) BY host' \
--data-urlencode startTime=1785427200 \
--data-urlencode endTime=1785429000 \
--data-urlencode interval=60 \
--data-urlencode tz=Asia/Shanghai \
--output chart.png
レスポンス¶
HTTP 200 は生の PNG 画像ストリームです。エラーは通常 JSON で、描画失敗時も 200 と空の本文を返す可能性があるため、ステータス/タイプ/ファイル署名を確認する必要があります。
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Content-Type | string | 成功時は image/png。異常時は実際の JSON またはプロキシのレスポンスタイプに従って処理します。 |
| Cache-Control | string | 成功時は no-store, max-age=0 で、画像レスポンスはキャッシュされません。 |
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store, max-age=0
<PNG バイナリ、ファイルヘッダーの16進数は 89 50 4e 47 0d 0a 1a 0a>
エラー応答¶
本エントリポイントは requireSignIn=false であり、DF-API-KEY の認証/ロールエラーは適用されません。リクエスト検証は引き続き適用されます。クエリサービスは、文、データソース、容量、ネットワークに関連する動的なエラーを返す可能性があり、HTTP ステータスとエラーコードは実際のレスポンスに従います。描画エラーでは 200 と空の PNG 本文のみが返る可能性があり、常に JSON エラーが返るとは限りません。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンス説明 | 処理方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認します。 |
| 406 | ft.DqlParseError | DQL 文の構文または解析構造が無効 | dql parser の解析に失敗しました: {} | まずクエリツールで文を検証し、正しく URL エンコードしたうえで、実際の解析原因を保持します。 |
| 406 | ft.NotSupportedByGroupQuery | BY index によるグループ化を使用 | index フィールドによる by グループ化クエリはサポートされていません | index のグループ化フィールドを削除し、実際の業務 Tag によるグループ化に変更します。 |
| 503 | ft.QueryServiceUnavailable | クエリ上流の HTTP503 が統一的にマッピングされる | クエリサービスは一時的に利用できません。しばらくしてから再試行してください | エラー本文の content.retryable を確認し、バックオフ後に読み取りを再試行してください。高頻度の再試行は避けてください。 |
| 404 | ft.ClientTokenNotExistOrDelete | Client Token が空白除去後に空である、またはキャッシュミスで有効な Token レコードが存在しない | 指定された Client Token は存在しないか、削除されています | 実際の Token 値と対象サイトを確認し、有効な Token を使用してください。レコードの UUID で代用することはできません。 |
| 400 | ft.IllegalStartOrEndTime | 終点が起点より早い、またはスパンがサイトの最大値を超えている | 無効な開始/終了タイムスタンプ | 同じ単位のタイムスタンプを使用し、許容範囲内に縮小してください。 |
| 406 | ft.InvalidParameter | interval が 0 未満 | パラメータ interval が無効です |
正の整数秒または自動推定の 0 に変更してください。 |
| 500 | ft.InternalServerError | キャッシュ/データベースが利用できない、返却データ構造が異常、またはその他の未捕捉エラー | 内部エラー | 返却された Content-Type と本文を確認し、traceId を保持して管理者に連絡してください。エラー JSON を PNG として扱わないでください。 |