コンテンツにスキップ

外部イベントモニターのイベント受付



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.{ユーザー定義フィールド} の制限条件説明

同名フィールドで異なる型がレポートされ、後続の問題を引き起こすことを避けるため、ユーザー定義フィールドは次の制限条件を満たす必要があります。

  1. フィールド値は文字列型でなければなりません(例: "abc"、"123")。
  2. フィールド名をアンダースコア _ または df_ で始めることはできません。
  3. フィールド名は、dimension_tags を展開したフィールド名や labels を展開したフィールド名と重複してはなりません。
  4. フィールド名に次の予約フィールドを使用することはできません(カスタムフィールドはすべて、区別しやすいよう 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 を提供してください。

フィードバック

このページは役に立ちましたか?