« Encrypting sensitive data in Watcher Watcher triggers »

› ›

观察者输入

edit

观察者输入

edit

当触发一个监视器时，其输入将数据加载到执行上下文中。此有效负载在随后的监视器执行阶段中是可访问的。例如，您可以根据其输入加载的数据来设置监视器的条件。

Watcher 支持四种输入类型：

simple: 将静态数据加载到执行上下文中。
search: 将搜索结果加载到执行上下文中。
http: 将HTTP请求的结果加载到执行上下文中。
chain: 使用一系列输入将数据加载到执行上下文中。

如果你没有为监视定义输入，一个空的载荷将被加载到执行上下文中。

观察者简单输入

edit

使用 simple 输入在监视触发时将静态数据加载到执行上下文中。这使您能够集中存储数据并通过模板引用它。

您可以将静态数据定义为字符串（str）、数值（num）或对象（obj）：

"input" : {
  "simple" : {
    "str" : "val1",
    "num" : 23,
    "obj" : {
      "str" : "val2"
    }
  }
}

例如，以下监视器使用 simple 输入来设置每日提醒电子邮件的收件人名称：

{
  "trigger" : {
    "schedule" : {
      "daily" : { "at" : "noon" }
    }
  },
  "input" : {
    "simple" : {
      "name" : "John"
    }
  },
  "actions" : {
    "reminder_email" : {
      "email" : {
        "to" : "to@host.domain",
        "subject" : "Reminder",
        "body" : "Dear {{ctx.payload.name}}, by the time you read these lines, I'll be gone"
      }
    }
  }
}

观察者搜索输入

edit

使用 search 输入在触发监视时将 Elasticsearch 搜索请求的结果加载到执行上下文中。请参阅搜索输入属性以获取所有支持的属性。

在搜索输入的 request 对象中，您指定：

您要搜索的索引
搜索类型
搜索请求体

搜索请求体支持完整的 Elasticsearch 查询 DSL——它与 Elasticsearch _search 请求的体相同。

例如，以下输入从logs索引中检索所有event文档：

"input" : {
  "search" : {
    "request" : {
      "indices" : [ "logs" ],
      "body" : {
        "query" : { "match_all" : {}}
      }
    }
  }
}

在指定索引时，您可以使用日期数学和通配符。例如，以下输入从今天的每日报价索引中加载最新的VIXZ报价：

{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "<stock-quotes-{now/d}>" ],
        "body" : {
          "size" : 1,
          "sort" : {
            "timestamp" : { "order" : "desc"}
          },
          "query" : {
            "term" : { "symbol" : "vix"}
          }
        }
      }
    }
  }
}

提取特定字段

edit

您可以使用extract属性指定要将搜索响应中的哪些字段加载到监视负载中。这在搜索生成大型响应而您只对特定字段感兴趣时非常有用。

例如，以下输入仅将点击总数加载到监视有效载荷中：

"input": {
    "search": {
      "request": {
        "indices": [ ".watcher-history*" ]
      },
      "extract": [ "hits.total.value" ]
    }
  },

使用模板

edit

输入支持搜索模板。例如，以下代码片段引用了名为my_template的索引模板，并将值23传递给模板的value参数：

{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "template" : {
          "id" : "my_template",
          "params" : {
            "value" : 23
          }
        }
      }
    }
  }
  ...
}

应用条件

edit

输入search通常与script条件一起使用。例如，以下代码片段添加了一个条件，用于检查搜索是否返回了超过五个匹配项：

{
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : { "match_all" : {} }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 5 }}
  }
  ...
}

访问搜索结果

edit

条件、转换和操作可以通过监视执行上下文访问搜索结果。例如：

要将所有搜索结果加载到电子邮件正文中，请使用 ctx.payload.hits。
要引用命中总数，请使用 ctx.payload.hits.total。
要访问特定命中，请使用其基于零的数组索引。例如，要获取第三个命中，请使用 ctx.payload.hits.hits.2。
要从特定命中获取字段值，请使用 ctx.payload.hits.hits..fields.。例如，要从第一个命中获取消息字段，请使用 ctx.payload.hits.hits.0.fields.message。

搜索响应中的总点击次数作为响应中的一个对象返回。它包含一个value，即点击次数，以及一个relation，用于指示该值是否准确（"eq"）或匹配查询的总点击次数的下限（"gte"）。您可以在搜索请求中将track_total_hits设置为true，以告知Elasticsearch始终准确跟踪点击次数。

搜索输入属性

edit

Name	Required	Default	Description
`request.search_type`	否	`query_then_fetch`	要执行的搜索请求类型。有效值为：`dfs_query_then_fetch` 和 `query_then_fetch`。 Elasticsearch 默认值为 `query_then_fetch`。
`request.indices`	否	-	要搜索的索引。如果省略，则搜索所有索引，这是 Elasticsearch 中的默认行为。
`request.body`	否	-	请求的主体。请求体遵循您通常在REST `_search`请求主体中发送的相同结构。主体可以是静态文本或包含`mustache` 模板。
`request.template`	否	-	搜索模板的主体。更多信息请参见配置模板。
`request.indices_options.expand_wildcards`	否	`打开`	如何扩展通配符。有效值为：`all`、`open`、`closed` 和 `none` 请参阅 `expand_wildcards` 了解更多信息。
`request.indices_options.ignore_unavailable`	否	`真`	搜索是否应忽略不可用的索引。更多信息请参见 `ignore_unavailable`。
`request.indices_options.allow_no_indices`	否	`真`	是否允许在通配符索引表达式结果为无具体索引时进行搜索。更多信息请参见allow_no_indices。
`extract`	否	-	从搜索响应中提取并加载为有效负载的JSON键数组。当搜索生成大型响应时，您可以使用`extract`来选择相关字段，而不是加载整个响应。
`timeout`	否	1米	等待搜索API调用返回的超时时间。如果在此时限内没有返回响应，搜索输入将超时并失败。此设置会覆盖默认的搜索操作超时。

在指定请求body时，您可以在执行上下文中引用以下变量：

Name	Description
`ctx.watch_id`	当前正在执行的监视器的ID。
`ctx.execution_time`	此手表的计时开始时间。
`ctx.trigger.triggered_time`	触发此监视器的时间。
`ctx.trigger.scheduled_time`	这个监视器应该被触发的时间。
`ctx.metadata.*`	与该观察相关的任何元数据。

观察者 HTTP 输入

edit

使用 http 输入向 HTTP 端点提交请求，并在触发监视时将响应加载到监视执行上下文中。有关所有支持的属性，请参阅 HTTP 输入属性。

使用 http 输入，您可以：

查询外部Elasticsearch集群。http输入提供了一种方法，可以将搜索请求提交到Watcher正在运行的集群以外的集群。当你运行一个专用的Watcher集群或需要搜索运行不同Elasticsearch版本的集群时，这非常有用。
查询除搜索API之外的Elasticsearch API。例如，你可能希望从节点统计信息、集群健康状况或集群状态API加载数据。
查询外部Web服务。http输入使你能够从任何公开HTTP端点的服务加载数据。这为Elasticsearch集群和其他系统之间提供了一座桥梁。

查询外部 Elasticsearch 集群

edit

要查询外部 Elasticsearch 集群，您需要指定集群的 host 和 port 属性，并将索引的搜索端点作为 path。如果您省略搜索体，请求将返回指定索引中的所有文档：

"input" : {
  "http" : {
    "request" : {
      "host" : "example.com",
      "port" : 9200,
      "path" : "/idx/_search"
    }
  }
}

您可以使用完整的 Elasticsearch Query DSL 来执行更复杂的搜索。例如，以下 http 输入检索在 category 字段中包含 event 的所有文档：

"input" : {
  "http" : {
    "request" : {
      "host" : "host.domain",
      "port" : 9200,
      "path" : "/idx/_search",
      "body" :  "{\"query\" :  {  \"match\" : { \"category\" : \"event\"}}}"
    }
  }
}

调用 Elasticsearch API

edit

要从其他 Elasticsearch API 加载数据，请将 API 端点指定为 path 属性。使用 params 属性来指定查询字符串参数。例如，以下 http 输入调用集群统计信息 API 并启用 human 属性：

"input" : {
  "http" : {
    "request" : {
      "host" : "host.domain",
      "port" : 9200,
      "path" : "/_cluster/stats",
      "params" : {
        "human" : "true" 
      }
    }
  }
}

启用此属性后，响应中的 bytes 值将以人类可读的格式返回。

调用外部Web服务

edit

您可以使用 http 输入从任何外部 Web 服务获取数据。http 输入支持基本身份验证。例如，以下输入提供用户名和密码以访问 myservice：

"input" : {
  "http" : {
    "request" : {
      "host" : "host.domain",
      "port" : 9200,
      "path" : "/myservice",
      "auth" : {
        "basic" : {
          "username" : "user",
          "password" : "pass"
        }
      }
    }
  }
}

您还可以通过params属性传递特定服务的API密钥和其他信息。例如，以下http输入从OpenWeatherMap服务加载阿姆斯特丹的当前天气预报：

"input" : {
  "http" : {
    "request" : {
      "url" : "http://api.openweathermap.org/data/2.5/weather",
      "params" : {
        "lat" : "52.374031",
        "lon" : "4.88969",
        "appid" : "<your openweathermap appid>"
      }
    }
  }
}

使用基于令牌的身份验证

edit

您也可以使用Bearer token来调用API，而不是使用基本认证。request.headers对象包含HTTP头信息：

"input" : {
  "http" : {
    "request" : {
      "url": "https://api.example.com/v1/something",
      "headers": {
        "authorization" : "Bearer ABCD1234...",
        "content-type": "application/json"
        # other headers params..
        },
      "connection_timeout": "30s"
    }
  }
}

使用模板

edit

The http 输入支持模板化。您可以在指定 path、body、header 值和参数值时使用模板。

例如，以下代码片段使用模板来指定要查询的索引，并将结果限制为在过去五分钟内添加的文档：

"input" : {
  "http" : {
    "request" : {
      "host" : "host.domain",
      "port" : 9200,
      "path" : "/{{ctx.watch_id}}/_search",
      "body" : "{\"query\" : {\"range\": {\"@timestamp\" : {\"from\": \"{{ctx.trigger.triggered_time}}||-5m\",\"to\": \"{{ctx.trigger.triggered_time}}\"}}}}"
      }
    }
  }

访问 HTTP 响应

edit

如果响应体是以JSON或YAML格式化的，它会被解析并加载到执行上下文中。如果响应体不是以JSON或YAML格式化的，它会被加载到payload的_value字段中。

条件、转换和操作通过执行上下文访问响应数据。例如，如果响应包含一个message对象，您可以使用ctx.payload.message来访问消息数据。

此外，可以使用ctx.payload._headers字段访问响应中的所有标头，以及使用ctx.payload._status_code字段访问响应的HTTP状态码。

HTTP 输入属性

edit

Name	Required	Default	Description
`request.scheme`	否	http	URL方案。有效值为：`http` 或 `https`。
`request.host`	是	-	要连接的主机。
`request.port`	是	-	http服务正在监听的端口。
`request.path`	否	-	URL 路径。路径可以是静态文本或包含 `mustache` 模板。URL 查询字符串参数必须通过 `request.params` 属性指定。
`request.method`	否	获取	HTTP 方法。支持的值有：`head`、`get`、`post`、 `put` 和 `delete`。
`request.headers`	否	-	HTTP 请求头。头值可以是静态文本，也可以包含 `mustache` 模板。
`request.params`	否	-	URL查询字符串参数。参数值可以是静态文本或包含`mustache` 模板。
`request.url`	否	-	允许您通过指定一个真实的URL，如`https://www.example.org:1234/mypath?foo=bar`，一次性设置`request.scheme`、`request.host`、`request.port`和`request.params`。不能与这四个参数中的任何一个结合使用。由于这些参数已被设置，单独指定它们可能会覆盖它们。
`request.auth.basic.username`	否	-	HTTP基本认证用户名
`request.auth.basic.password`	否	-	HTTP 基本认证密码
`request.proxy.host`	否	-	连接到主机时使用的代理主机。
`request.proxy.port`	否	-	连接到主机时使用的代理端口。
`request.connection_timeout`	否	10秒	设置http连接的超时时间。如果在该时间内无法建立连接，输入将超时并失败。
`request.read_timeout`	否	10秒	从http连接读取数据的超时时间。如果在此时长内未收到响应，输入将超时并失败。
`request.body`	否	-	HTTP 请求体。请求体可以是静态文本或包含 `mustache` 模板。
`extract`	否	-	从输入响应中提取并作为有效负载使用的JSON键数组。在输入生成大型响应的情况下，这可以用于过滤响应中相关部分以作为有效负载使用。
`response_content_type`	否	JSON	响应体中预期的内容类型。支持的值为 `json`、`yaml` 和 `text`。如果格式为 `text`，则不能存在 `extract` 属性。请注意，这将覆盖 HTTP 响应中返回的标头。如果设置为 `text`，则响应的正文将被分配并可通过负载的 `_value` 变量访问。

在指定path、params、headers和body值时，可以在执行上下文中引用以下变量：

Name	Description
`ctx.watch_id`	当前正在执行的监视器的ID。
`ctx.execution_time`	此手表的计时开始时间。
`ctx.trigger.triggered_time`	触发此监视器的时间。
`ctx.trigger.scheduled_time`	这个监视器应该被触发的时间。
`ctx.metadata.*`	与该观察相关的任何元数据。

观察者链输入

edit

使用 chain 输入在触发监视时从多个源加载数据到监视执行上下文中。链中的输入按顺序处理，并且由一个输入加载的数据可以被链中的后续输入访问。

The chain 输入使您能够基于来自多个源的数据执行操作。您还可以使用一个输入收集的数据从另一个源加载数据。

例如，以下链输入使用由simple输入设置的路径从HTTP服务器加载数据：

"input" : {
  "chain" : {
    "inputs" : [ 
      {
        "first" : {
          "simple" : { "path" : "/_search" }
        }
      },
      {
        "second" : {
          "http" : {
            "request" : {
              "host" : "localhost",
              "port" : 9200,
              "path" : "{{ctx.payload.first.path}}" 
            }
          }
        }
      }
    ]
  }
}

	链中的输入被指定为一个数组，以保证输入的处理顺序。（JSON不保证任意对象的顺序。）
	加载由`first`输入设置的`path`。

访问链式输入数据

edit

要引用由特定输入加载的数据，您可以使用输入的名称， ctx.payload..。

转换链式输入数据

edit

在某些用例中，第一个输入的输出应作为后续输入的输入。这要求你在将数据传递到下一个输入之前进行转换。

为了实现这一点，您可以在两个指定的输入之间使用一个转换输入，请参见以下示例。请注意，第一个输入仍然可以在其原始形式中通过ctx.payload.first获得。

"input" : {
  "chain" : {
    "inputs" : [ 
      {
        "first" : {
          "simple" : { "path" : "/_search" }
        }
      },
      {
        "second" : {
          "transform" : {
            "script" : "return [ 'path' : ctx.payload.first.path + '/' ]"
          }
        }
      },
      {
        "third" : {
          "http" : {
            "request" : {
              "host" : "localhost",
              "port" : 9200,
              "path" : "{{ctx.payload.second.path}}" 
            }
          }
        }
      }
    ]
  }
}

« Encrypting sensitive data in Watcher Watcher triggers »