イベントの作成¶
POST /api/v1/events/create
概要¶
現在のワークスペースに df_source=custom のカスタムイベントを非同期で書き込みます。
呼び出し前の準備と使用手順¶
13 桁の Unix ミリ秒 date、空でない title、および必要な status を準備します。作成成功時の content=true は書き込みタスクが送信されたことのみを示し、イベント ID は返されず、データが格納済みであることも保証しません。後からDQL クエリで df_source=custom、タイトル、またはカスタムフィールドを指定して書き込みを確認でき、異常状態は未復旧イベント一覧でも確認できます。同一の業務オブジェクトの後続イベントでは customTags.monitor_checker_event_ref を再利用できますが、書き込みごとに新しい df_event_id が作成されるため、この関連付け値は冪等キーではありません。同一のカスタムイベントグループを終了する必要がある場合は、本 API を再度呼び出して同じ関連付け値と status=ok を持つイベントを書き込みます。manual recover は monitor ソースに適用されます。タイムアウトや再試行の前に、すでに書き込まれているかどうかを照会し、重複イベントを避けてください。本 API は現在の API Key が属するワークスペースを使用し、ワークスペース間またはサイト間のパラメータは宣言していません。他のワークスペースやサイトの場合は、それぞれ対応するサイトの Endpoint と、対応するワークスペースの API Key を使用して個別に呼び出してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| customTags.<key> | string/number/boolean | 任意のカスタム業務フィールド。フィールド名の先頭に連続する df_ プレフィックスは除去されます(例: df_df_service は service として書き込まれます)。正規化後の重複名は避けてください。 例: checkout-api取得または入力方法: 業務上の意味に応じて service、env などと命名します。同一フィールドでは安定した型を維持してください。 |
|
| customTags.monitor_checker_event_ref | string | 任意のカスタムイベント関連付け識別子。df_monitor_checker_event_ref を渡すこともでき、プレフィックス正規化後は同じ効果になります。省略または空値の場合、サーバー側で毎回新しい識別子が生成されます。 例: checkout-prod-latency取得または入力方法: 業務側で同一のトリガー対象に対して安定した識別子を生成して保存します。例えばサービス+環境+検出項目です。 |
|
| customTags | json | カスタムフィールドの JSON オブジェクト。省略または {} の場合、通常の業務フィールドは追加されません。文字列、数値、ブール値など明確な型を使用することを推奨します。 null 許容: False 例: {"service": "checkout-api", "env": "production", "monitor_checker_event_ref": "checkout-prod-latency"}取得または入力方法: 業務コンテキストからフィールド名と値を取得します。イベントフィールドリファレンスを参照できます。カスタム関連付け識別子は呼び出し側で安定して生成し、保存してください。 |
|
| date | integer | Y | イベントの発生時刻(Unix ミリ秒)。現在の検証では 13 桁が必要です。 null 許容: False 例: 1785430800000取得または入力方法: 業務イベントが実際に発生した時刻を取得します。JavaScript の Date.getTime() の結果など、13 桁の正の整数ミリ秒を使用してください。 |
| message | string | 詳細な説明。省略した場合は空文字列が使用されます。 null 許容: False 例: 直近 5 分間の平均応答時間が 500 ms を超えています。取得または入力方法: 業務上の現象、しきい値、メトリクス、および必要なコンテキストを記入してください。シークレットなどの機密情報は含めないでください。 |
|
| origin | string | 任意のソースラベル。df_origin に書き込まれます。固定の df_source=custom は変更されません。 null 許容: False 例: release取得または入力方法: 業務上の必要に応じて release などのカスタムソースラベルを記入します。省略した場合はこのラベルは追加されません。 |
|
| status | string | Y | イベントのステータス。必須で、デフォルト値による省略はできません。 null 許容: False 選択可能な値: ['fatal', 'critical', 'error', 'warning', 'ok', 'info', 'nodata'] 例: critical取得または入力方法: 業務上の異常レベルに応じて fatal、critical、error、warning、nodata を選択します。正常復旧には ok、情報記録には info を使用します。 |
| title | string | Y | イベントのタイトル。必須です。空文字列はバックエンドで書き込まれません。 null 許容: False 例: checkout-api の応答時間がしきい値を超えています取得または入力方法: 検索と識別が容易になるよう、簡潔で空でない業務タイトルを記入してください。 |
パラメータの補足説明¶
customTags という名前には Tags が含まれますが、これらの通常のカスタムフィールドはイベントフィールドに書き込まれるものであり、名前からすべてがインデックス用タグであると想定しないでください。monitor_checker_event_ref は df_monitor_checker_event_ref の生成に専用で使用されます。複雑な値は、データ型の不整合を避けるため、業務上の必要に応じて明示的に JSON 文字列へシリアライズしてください。書き込み後に他のクエリが __docid を提供する場合、イベント詳細で詳細を取得できます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/events/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"date":1785430800000,"status":"critical","title":"checkout-api の応答時間がしきい値を超えています","message":"直近 5 分間の平均応答時間が 500 ms を超えています。","customTags":{"service":"checkout-api","env":"production","monitor_checker_event_ref":"checkout-prod-latency"}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | true は非同期イベント書き込みタスクが送信済みであることを示します。ドキュメント ID、タスク ID、格納確認のフィールドはありません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
バックエンドの書き込み失敗によって、すでに返された HTTP 200 が変更されることはなく、今回のレスポンスで DataWay エラーが返されることもありません。後続のイベントクエリで結果を確認してください。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | 単一の JSON オブジェクトを送信し、配列や文字列を渡さないでください。 |
| 406 | ft.NotMillisecondTimestamp | date が現在の検証条件に合う 13 桁のミリ秒タイムスタンプでない | 有効なミリ秒タイムスタンプではありません | 13 桁の Unix ミリ秒整数を使用してください。10 桁の秒や単位付き文字列を送信しないでください。 |
| 500 | ft.InternalServerError | ワークスペースの照会またはタスクの送信に失敗 | 内部エラー | まず同一の業務イベントが書き込み済みかどうかを照会してから再試行を判断してください。失敗が続く場合は traceId を提供してください。 |