外部イベントモニターのイベント受付¶
POST /api/v1/push-events/{secret}/{subUri}
概要¶
設定済みの外部イベントWebhookを介して、単一のビジネスイベントを受信します。
呼び出し前の準備と使用手順¶
まず、jsonScript.type=OuterEventChecker のモニターを作成して有効化し、信頼できる詳細情報から secret と subUri を取得して、この専用 Webhook でレポートします。このエントリポイントは requireSignIn=false であり、DF-API-KEY を検証しません。URL 内の secret は特定/アクセスの役割を持ち、認証情報と同様に管理し、実際のアドレスを公開しないでください。subUri は単一のパスセグメントである必要があり、/ を含めることはできません。スラッシュを %2F と記述しても、現在の公開ルートには一致しません。新しい設定では datakit-push などのシンプルな値を使用することを推奨します。
一致しない場合でも、黙って無視されるわけではありません。secret が不明な場合は通常 404 となり、サフィックスが一致しない場合やルールが無効な場合は、対応するビジネスエラーが返されます。ワークスペースがロックされている場合も拒否され、ロック状態は最長約10分間キャッシュされる可能性があります。event の固定フィールド以外のカスタムフィールドは文字列のみ使用でき、ディメンション、バインド済みの key:value タグキー、または予約フィールドを上書きすることはできません。extraData は別途、補助的な JSON を格納します。
検証に通過すると、イベント処理サービスを同期的に呼び出し、モニター/グループ/タグ、およびチャネルのコンテキストを下流に付与します。ルールの isChangeEvent=true は変更イベントのソースとして処理されます。成功レスポンスは下流関数の結果をそのまま包みます。SDK は HTTP ステータスだけで一律に失敗を判定しません。オブジェクト以外かつ非 200、または明示的な ok=false は、通常 ft.OuterFuncFailed に変換されます。一方、オブジェクトの ok が false でない場合、上流が 5xx であっても外側の HTTP が 200 になることがあるため、content のビジネス結果を必ず確認してください。ここでは、イベントがすべての検索/通知ページに表示されることや、イベントのグローバル一意 ID または冪等性クレデンシャルを返すことは保証しません。本インターフェースには biz_ticket などのフィールドに基づく重複排除の保証はありません。タイムアウト後は、イベントが既に生成されているかを先に検索し、そのうえで再試行を判断してください。OpenAPI のこの route では、AIAPI 固有の呼び出し監査コンテキスト処理は行いません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| secret | string | Y | 必須のパスセグメントであり、DF-API-KEY ではありません。保存済みで削除されていないルールに正確に一致する必要があります。 例: SECRET-PLACEHOLDER取得または入力方法: 対象の外部イベントモニターの詳細にある secret から取得します。 |
| subUri | string | Y | 必須の単一パスセグメントであり、大文字と小文字を正確に区別し、スラッシュを含めません。多階層の URL を独自に結合しないでください。 例: datakit-push取得または入力方法: 同じルールの jsonScript.subUri から取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| event.status | string | 必須です。プロトコルに従って小文字を使用し、errorEvent/nodata で代用することはできません。 例: warning取得または入力方法: fatal/critical/error/warning/info/ok から対応するビジネスステータスを選択します。 |
|
| event.date | integer | 任意です。ミリ秒/マイクロ秒ではありません。省略した場合はそのまま下流に渡されず、イベント時刻は下流が決定します。クライアントが未来時刻や異常な時刻を使用できることは保証しません。 例: 1785427200取得または入力方法: 外部イベントの実際の発生日時を Unix 秒の整数に変換します。 |
|
| event.title | string | 任意の文字列です。省略した場合、Studio が固定タイトルを補完することはなく、最終的には受信サービスのプロトコルに従って処理されます。 例: 生产服务异常取得または入力方法: ビジネスアラートのタイトルから取得します。 |
|
| event.message | string | 任意の文字列です。JSON 配列ではありません。秘密情報を含めないでください。 例: 健康检查返回错误。取得または入力方法: 外部の検出結果から、特定可能なイベント内容を入力します。 |
|
| event.dimension_tags | json | 任意のオブジェクトです。ディメンションキーを _ または df_ で始めることはできません。この層ではオブジェクトとキーのみを検査します。値にはイベントディメンションに使用できる単純なデータ型を選択し、カスタムのトップレベル同名フィールドで重複させることはできません。 例: {"host": "web-example", "service": "production"}取得または入力方法: このイベントの実際のホスト/サービスなどのディメンションフィールドと値を選択します。 |
|
| event.dimension_tags.ディメンション名 | any | 動的ディメンション値であり、タグ名の配列ではありません。キーはカスタムのトップレベルフィールドと重複してはなりません。 例: web-example取得または入力方法: たとえば host は、外部システムの対応するリソース識別子から取得します。 |
|
| event.check_value | float | 任意の浮動小数点数/数値です。文字列は渡さないでください。単位は外部の検出によって定義され、Studio は換算しません。 例: 12.5取得または入力方法: 外部の実際の検出値から取得します。 |
|
| event.ビジネスフィールド | string | 任意のカスタムトップレベルフィールドです。値は文字列でなければなりません。biz_/ext_ プレフィックスを推奨します。キーを /df で始めることはできず、dimension_tags のキーやバインド済みのコロン付きタグのキーと重複してはならず、予約フィールドも使用できません。 例: ticket-example取得または入力方法: たとえば biz_ticket は、外部のチケットまたはリクエスト識別子から取得します。 |
|
| extraData.カスタムキー | any | 動的な JSON 値で、対象イベントのデータプロトコルに従います。 例: healthcheck取得または入力方法: 連携元の実際のメタ情報に従って定義します。 |
|
| event | json | Y | 必須の JSON オブジェクトであり、イベント配列ではありません。status は条件付きで必須です。ここでは既存の外部検出結果のみを受信し、しきい値クエリは実行しません。 null を許可: False 例: {"date": 1785427200, "status": "warning", "title": "生产服务异常", "message": "健康检查返回错误。", "dimension_tags": {"host": "web-example", "service": "production"}, "check_value": 12.5, "biz_ticket": "ticket-example"}取得または入力方法: ビジネスシステム/アラートプラットフォームの実際の検出結果から、1 つのイベントオブジェクトを構築します。 |
| extraData | json | 任意の JSON オブジェクトで、デフォルトは {} です。下流イベントの df_meta.extra_data として使用され、event のトップレベルフィールドを置き換えるものではありません。統一された必須サブキーはありません。認証情報を入れないでください。 null を許可: False 例: {"source_system": "healthcheck", "request_id": "request-example"}取得または入力方法: 外部連携から、ソースシステムや外部リクエスト ID などの補助的な特定フィールドを取得します。 |
パラメータ補足説明¶
パラメータ説明:
body リクエストパラメータ本体の構造説明
| パラメータ名 | パラメータ型 | 必須かどうか | パラメータ説明 |
|---|---|---|---|
| event | json | 是 | イベントデータ |
| extraData | json | 否 | 追加データ。最終的にイベントの df_meta.extra_data フィールドに追加されます。key:value に準拠していれば問題ありません。 |
event リクエストパラメータ本体の構造説明
| パラメータ名 | パラメータ型 | 必須かどうか | パラメータ説明 |
|---|---|---|---|
| date | int | 否 | イベント時刻(単位: 秒) |
| status | string | 是 | イベントステータス。選択可能: fatal、critical、error、warning、info、ok |
| title | string | 否 | イベントタイトル |
| message | string | 否 | イベント内容 |
| dimension_tags | json | 否 | ディメンションタグ。例: |
| check_value | float | 否 | 検出値 |
| ユーザー定義フィールド | str | 否 | 2024-09-04 のユーザー定義フィールド。イベントのトップレベルフィールドとして使用され、制限条件を満たす必要があります。 |
event.{ユーザー定義フィールド} の制限条件説明
同名フィールドで異なる型がレポートされ、後続の問題を引き起こすことを避けるため、ユーザー定義フィールドは次の制限条件を満たす必要があります。
- フィールド値は文字列型でなければなりません(例: "abc"、"123")。
- フィールド名をアンダースコア _ または df_ で始めることはできません。
- フィールド名は、dimension_tags を展開したフィールド名や labels を展開したフィールド名と重複してはなりません。
- フィールド名に次の予約フィールドを使用することはできません(カスタムフィールドはすべて、区別しやすいよう ext_xxx、biz_xxx など独自に定義したプレフィックスで始めることを推奨します):
- date
- status
- source
- title
- message
- dimension_tags
- check_value
- time
- time_us
- timestamp
- workspace_uuid
- workspace_name
- extra_data
- create_time
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/push-events/SECRET-PLACEHOLDER/datakit-push' \
-H 'Content-Type: application/json' \
--data-raw '{"event":{"date":1785427200,"status":"warning","title":"生产服务异常","message":"健康检查返回错误。","dimension_tags":{"host":"web-example","service":"production"},"check_value":12.5,"biz_ticket":"ticket-example"},"extraData":{"source_system":"healthcheck","request_id":"request-example"}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object またはその他の JSON | 下流関数の結果をそのまま包みます。以下は既存の一般的なレスポンスフィールドです。バージョンによってはフィールドを省略できます。 |
| content.data | JSON | 下流のビジネス結果で、通常は {} です。イベント ID を必ず含むわけではありません。 |
| content.error | integer または string | 下流のビジネス結果コードです。例: 200。Studio の HTTP ステータスではありません。 |
| content.message | string | 下流のビジネスメッセージ。 |
| content.ok | boolean | 下流関数の結果マーカーです。明示的な false は通常、SDK によって ft.OuterFuncFailed に変換されます。 |
| content.reqCost | number | 下流の生の所要時間統計値です。Studio はその単位を正規化しません。省略可能です。 |
| content.reqTime | string | 下流のリクエスト時刻です。通常は ISO8601 UTC 文字列です。省略可能です。 |
| content.respTime | string | 下流のレスポンス時刻です。通常は ISO8601 UTC 文字列です。省略可能です。 |
| content.traceId | string | 下流実行のトレース識別子です。外側の Studio traceId とは異なる場合があります。 |
| content.declaration | object | 空でないオブジェクトのみが共通宣言を付加します。その他のレスポンス形状では省略できます。 |
{
"code": 200,
"content": {
"data": {},
"error": 200,
"message": "",
"ok": true,
"reqCost": 458,
"reqTime": "2026-07-30T16:00:00.000Z",
"respTime": "2026-07-30T16:00:00.458Z",
"traceId": "FUNC-TRACE-EXAMPLE",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
この Webhook エントリポイントは DF-API-KEY 認証を実行しません。API Key の欠落/権限エラーは、このページの主要な接続経路として扱わないでください。イベント検証、ルール/ワークスペースの状態、および下流のビジネスエラーについては本ページを参照してください。スラッシュを含む subUri はルートに一致せず、直接 404 になる可能性があり、統一された JSON エラーシェルも保証されません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、および値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON Body のトップレベルがオブジェクトではありません(配列/文字列など) | 一部の JSON ファイル形式エラー | 例に従って JSON オブジェクトを送信してください。checkers や event の配列を直接送信することはできません。 |
| 400 | ft.ParamsValidateError | event オブジェクト内の status の欠落/不正、date/check_value/title などの固定サブフィールドの型不一致 | パラメータ検証に失敗しました: {} | 本ページの単一イベントオブジェクトおよびフィールド型に従って送信してください。 |
| 404 | ft.NotFoundRuleInspector | secret に対応する削除されていないルールが存在しない、または所属ワークスペースが使用不可 | 指定されたルール/チェッカーが見つかりません | 作成済みの外部イベントモニターの詳細から Webhook アドレスを再取得してください。API Key を secret として扱わないでください。 |
| 403 | ft.WorkspaceIsLocked | 対象ワークスペースがロックされている、または短期間のロックキャッシュがまだ有効 | ワークスペースがロックされているため、操作できません | 管理者がロック解除状態を確認し、キャッシュが最大約10分間保持された後に再試行してください。 |
| 406 | ft.OuterEventCheckerWebhookSubUriNotValid | パス subUri が該当ルールの保存値と異なる | 外部イベントモニターの Webhook アドレスが無効です。アドレスが正しいか確認してください。 | 信頼できる詳細情報にある完全な Webhook サフィックスに従って呼び出してください。大文字と小文字、およびパスセグメントに注意してください。 |
| 406 | ft.OuterEventCheckerNotAvailable | ルールが現在 status=0 ではない(無効化済みなど) | 外部イベントのモニターが無効化または削除されています | ビジネス上許可されることを確認したうえで、権限を持つ担当者が有効化してからレポートしてください。削除済みルールは通常、先に存在しないエラーが返されます。 |
| 404 | ft.MonitorNotFound | ルールに関連付けられたグループが存在しない、または削除済み | ルールグループが見つかりません | 管理者が過去のルールグループの関連付けを確認して修正します。 |
| 400 | ft.DimensionTagsStartswithError | ディメンションキーが _ または df_ で始まる | dimension_tags のキーは df_、_ で始めることはできません | 通常のビジネスディメンションキーに変更してください。 |
| 400 | ft.CustomEventFieldValueTypeError | カスタムトップレベルフィールドの値が文字列ではない | カスタムフィールドの値は文字列でなければなりません | 取り決められた文字列に変換し、数値の検出値は check_value に格納してください。 |
| 400 | ft.CustomEventFieldStartswithError | カスタムトップレベルキーが _ または df_ で始まる | カスタムフィールドは df_、_ で始めることはできません | biz_/ext_ のビジネスプレフィックスに変更してください。 |
| 400 | ft.CustomEventFieldWithDimensionTagsNotAllowed | カスタムトップレベルキーが dimension_tags のキーと同じ | カスタムフィールド名に dimension_tags 内のキーを使用することはできません | いずれか 1 つの位置に残すか、ビジネスフィールド名を変更してください。 |
| 400 | ft.CustomEventFieldLabelKeyNotAllowed | カスタムフィールドが、ルールにバインドされた key:value タグのキーと重複している | カスタムフィールド名に、このモニターのタグ(key:value)内のキーを使用することはできません | バインド済みタグを確認し、ビジネスフィールド名を変更してください。 |
| 400 | ft.CustomEventFieldNotAllowed | カスタムキーに予約フィールド source/time/time_us/timestamp/workspace_uuid/workspace_name/extra_data/create_time を使用している | カスタムフィールド名に予約フィールドを使用することはできません | ビジネスプレフィックスを使用し、固定フィールドは本ページで規定された位置に送信してください。 |
| 400 | ft.OuterFuncFailed | イベント処理関数が ok=false または JSON 以外の失敗結果を返す | 外部関数の呼び出しに失敗しました | エラーの message と traceId に基づいて下流処理を特定し、既に受信済みかどうかを確認してから再試行してください。 |
| 500 | ft.InternalServerError | 下流のタイムアウト/接続/無効な JSON などの未捕捉例外、キャッシュ/ストレージ、またはレスポンス処理の失敗 | 内部エラー | まず外部リクエスト識別子でイベントが既に生成されているかを検索し、やみくもなリプレイによる重複を避けてください。traceId を提供してください。 |