HTTP JSON 输入

httpjson 输入在请求之间保持运行时状态。此状态可以通过某些配置选项和转换来访问。

该状态具有以下元素

除了 cursor（其值在定期请求和重启之间持久化）之外，所有提到的对象仅在定期请求执行期间的运行时存储。

转换是一个操作，允许用户修改 输入状态。根据转换的定义位置，它将能够读取或写入 状态的不同元素。

访问限制在相应的配置部分中进行了描述。

将值追加到数组。如果字段不存在，第一个条目将创建一个新数组。如果字段存在，则将值追加到现有字段并将其转换为列表。

- append:
    target: body.foo.bar
    value: '[[.cursor.baz]]'
    default: "a default value"

删除目标字段。

- delete:
    target: body.foo.bar

设置值。

- set:
    target: body.foo.bar
    value: '[[.cursor.baz]]'
    default: "a default value"

某些配置选项和转换可以使用值模板。值模板是具有访问输入状态和某些内置函数功能的 Go 模板。请注意，分隔符已从默认的 {{ }} 更改为 [[ ]]，以提高与其他模板机制的互操作性。

要查看哪些 状态元素 和操作可用，请参阅您要在其中使用值模板的选项或 转换 的文档。

值模板如下所示

- set:
    target: body.foo.bar
    value: '[[.cursor.baz]] more data'
    default: "a default value"

方括号 [[ ]] 内的内容将被评估。有关 Go 模板的更多信息，请参阅 Go 文档。

提供了一些内置辅助函数来处理值模板中的输入状态

除了提供的函数外，还可以对相应的对象使用 time.Time、http.Header 和 url.Values 类型的任何原生函数。示例：[[(now).Day]]，[[.last_response.header.Get "key"]]

httpjson 输入支持以下配置选项以及稍后描述的 常用选项。

重复请求之间的持续时间。如果启用了分页，它可能会根据初始请求响应发出其他分页请求。默认值：60s。

设置为 false 时，将禁用基本身份验证配置。默认值：true。

用于身份验证的用户。

使用的密码。

设置为 false 时，将禁用 oauth2 配置。默认值：true。

用于配置受支持的 oauth2 提供程序。每个受支持的提供程序都需要特定的设置。默认情况下未设置。支持的提供程序包括：azure、google、okta。

用作身份验证流程一部分的客户端 ID。除了使用 google 作为提供程序外，它始终是必需的。对于以下提供程序是必需的：default、azure、okta。

用作身份验证流程一部分的客户端密钥。除了使用 google 或 okta 作为提供程序外，它始终是必需的。对于以下提供程序是必需的：default、azure。

用作身份验证流程一部分的用户。对于身份验证 - grant type password 是必需的。仅适用于 default 提供程序。

用作身份验证流程一部分的密码。对于身份验证 - grant type password 是必需的。仅适用于 default 提供程序。

在 oauth2 流程期间将请求的一系列作用域。对于所有提供程序都是可选的。

将在 oauth2 流程期间用于生成令牌的端点。如果未指定提供程序，则这是必需的。

将发送到 token_url 的每个请求的一组值。每个参数键可以有多个值。可以为除 google 之外的所有提供程序设置。

- type: httpjson
  auth.oauth2:
    endpoint_params:
      Param1:
        - ValueA
        - ValueB
      Param2:
        - Value

在使用 azure 提供程序时用于身份验证。由于它用于生成 token_url 的过程中，因此不能与之结合使用。这不是必需的。

有关在哪里查找它的信息，您可以参考 https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal。

使用 azure 提供程序时访问的 WebAPI 资源。这不是必需的。

Google 的凭据文件。

您的凭据信息（原始 JSON）。

Google 的 JWT 帐户密钥文件。

JWT 帐户密钥文件（原始 JSON）。

您的 Okta 服务应用程序的 RSA JWK 私钥文件，用于与 Okta Org Auth 服务器交互以使用 okta.* 作用域铸造令牌。

您的 Okta 服务应用程序的 RSA JWK 私钥 JSON，用于与 Okta Org Auth 服务器交互以使用 okta.* 作用域铸造令牌。

您的 Okta 服务应用程序的 RSA JWK 私钥 PEM 块，用于与 Okta Org Auth 服务器交互以使用 okta.* 作用域铸造令牌。

用于创建凭据的委托帐户的电子邮件（通常是管理员）。与 auth.oauth2.google.jwt_file、auth.oauth2.google.jwt_json 一起使用，以及在默认为使用 ADC 时使用。

HTTP API 的 URL。必需。

可以通过将 +unix 或 +npipe 添加到 URL 方案来通过 Unix 套接字和 Windows 命名管道访问 API 端点，例如 http+unix:///var/socket/。

发出请求时使用的 HTTP 方法。GET 或 POST 是选项。默认值：GET。

用于编码请求正文的 ContentType。如果设置了它，它将强制以指定的格式进行编码，而不管 Content-Type 标头值如何，否则它将尽可能遵守它或回退到 application/json。默认情况下，请求使用 Content-Type: application/json 发送。支持的值：application/json 和 application/x-www-form-urlencoded。application/x-www-form-urlencoded 将对 url.params 进行 URL 编码并将其设置为正文。默认情况下未设置。

可选的 HTTP POST 正文。配置值必须是一个对象，它将被编码为 JSON。这只在 request.method 为 POST 时有效。默认为 null（无 HTTP 正文）。

- type: httpjson
  request.method: POST
  request.body:
    query:
      bool:
        filter:
          term:
            type: authentication

声明 HTTP 客户端连接超时之前的持续时间。有效的时单位是 ns、us、ms、s、m、h。默认值：30s。

这指定了 SSL/TLS 配置。如果缺少 ssl 部分，则 HTTPS 连接将使用主机 CA。有关更多信息，请参阅 SSL。

这以 http[s]://<user>:<password>@<server name/ip>:<port> 的形式指定代理配置。

filebeat.inputs:
# Fetch your public IP every minute.
- type: httpjson
  interval: 1m
  request.url: https://api.ipify.org/?format=json
  request.proxy_url: http://proxy.example:8080

此选项指定是否禁用 HTTP 端点的 keep-alive 功能。默认值：true。

所有主机上的空闲连接最大数量。零表示无限制。默认值：0。

每个主机保持的空闲连接最大数量。如果为零，则默认为二。默认值：0。

空闲连接在关闭自身之前保持空闲的最大时间。有效的时间单位是 ns、us、ms、s、m、h。零表示无限制。默认值：0s。

HTTP 客户端最大重试次数。默认值：5。

尝试重试之前等待的最小时间。默认值：1s。

尝试重试之前等待的最大时间。默认值：60s。

设置为 true 时，重定向时会转发请求头。默认值：false。

当 redirect.forward_headers 设置为 true 时，将转发此列表中未定义的所有标头。默认值：[]。

请求最多可以跟随的重定向次数。默认值：10。

指定总限制的响应值。它使用 Go 模板值定义。可以读取以下状态：[.last_response.header]

指定速率限制剩余配额的响应值。它使用 Go 模板值定义。可以读取以下状态：[.last_response.header] 如果响应中缺少 remaining 标头，则不会发生速率限制。

指定速率限制将重置的纪元时间的响应值。它使用 Go 模板值定义。可以读取以下状态：[.last_response.header]

可以选择在响应中指定的值之前开始速率限制。

在默认行为下，当 remaining 值非零时，请求将继续。指定 early_limit 将意味着在达到 0 之前就会发生速率限制。

默认情况下未设置此值（默认情况下，遵循响应中指定的速率限制）。

每次执行前应用于请求的转换列表。

可用于请求的转换：[append、delete、set]。

可以读取以下状态：[.first_response.*、.last_response.*、.parent_last_response.* .last_event.*、.cursor.*、.header.*、.url.*、.body.*]。

可以将状态写入：[body.*、header.*、url.*]。

filebeat.inputs:
- type: httpjson
  request.url: https://127.0.0.1:9200/_search?scroll=5m
  request.method: POST
  request.transforms:
    - set:
        target: body.from
        value: '[[now (parseDuration "-1h")]]'

示例配置

  filebeat.inputs:
  - type: httpjson
    enabled: true
    id: my-httpjson-id
    request.url: http://xyz.com/services/data/v1.0/export_ids/page
    request.method: POST
    interval: 1h
    request.retry.max_attempts: 2
    request.retry.wait_min: 5s
    request.transforms:
    - set:
        target: body.page
        value: 0
    response.request_body_on_pagination: true
    response.pagination:
      - set:
          target: body.page
          value: '[[ .last_response.body.page ]]'
          fail_on_template_error: true
          do_not_log_failure: true
    chain:
    - step:
          request.url: http://xyz.com/services/data/v1.0/$.exportId/export_ids/$.files[:].id/info
          request.method: POST
          request.transforms:
          - set:
              target: body.exportId
              value: '[[ .parent_last_response.body.exportId ]]'
          replace: $.files[:].id
          replace_with: '$.exportId,.parent_last_response.body.exportId'

在这里，我们可以看到链步骤仅使用 .parent_last_response.body.exportId 是因为父（根）请求中存在 response.pagination。但是，如果父（根）请求中不存在 response.pagination，则 replace_with 子句应该使用 .first_response.body.exportId。这是因为当父级不存在分页时，出于性能原因，parent_last_response 对象不会填充所需的值，但 first_response 对象始终存储进程链中的第一个响应。

可以将 HTTP 请求和响应记录到本地文件系统以调试配置。通过将 request.tracer.enabled 设置为 true 并设置 request.tracer.filename 值来启用此选项。其他选项可用于调整日志轮转行为。要删除现有日志，请将 request.tracer.enabled 设置为 false，而无需取消设置文件名选项。

启用此选项会影响安全性，应仅用于调试。

为了区分从不同输入实例生成的跟踪文件，可以在文件名中添加占位符 *，它将被替换为输入实例 ID。例如，http-request-trace-*.ndjson。

此值设置日志文件在轮转之前将达到的最大大小（以兆字节为单位）。默认情况下，日志允许达到 1MB 才会轮转。

这指定保留轮转日志文件的日期数。如果未设置，则无限期保留日志文件。

要保留的旧日志数量。如果未设置，则所有旧日志都将根据 request.tracer.maxage 设置进行保留。

是否使用主机的本地时间而不是 UTC 来为轮转日志文件名加时间戳。

这决定是否应压缩轮转的日志。

用于解码响应正文的 ContentType。如果设置了此选项，它将强制以指定的格式进行解码，而不管 Content-Type 标头值如何，否则如果可能，它将遵循此值，或回退到 application/json。支持的值：application/json, application/x-ndjson、text/csv、application/zip、application/xml 和 text/xml。默认情况下未设置。

XML 文档可能需要其他类型信息才能启用正确的解析和提取。可以使用 response.xsd 选项为文档提供 XML 架构定义 (XSD) 作为此信息。

接收响应后应用于响应的转换列表。

可用于响应的转换：[append、delete、set]。

可以读取以下状态：[.last_response.*、.last_event.*、.cursor.*、.header.*、.url.*]。

可以将状态写入：[body.*]。

filebeat.inputs:
- type: httpjson
  request.url: https://127.0.0.1:9200/_search?scroll=5m
  request.method: POST
  response.transforms:
    - delete:
        target: body.very_confidential
  response.split:
    target: body.hits.hits
  response.pagination:
    - set:
        target: url.value
        value: https://127.0.0.1:9200/_search/scroll
    - set:
        target: url.params.scroll_id
        value: '[[.last_response.body._scroll_id]]'
    - set:
        target: body.scroll
        value: 5m

应用于接收响应后的拆分操作。拆分可以将映射、数组或字符串转换为多个事件。如果拆分目标为空，则将保留父文档。如果应删除具有空拆分的文档，则应将 ignore_empty_value 选项设置为 true。

定义将执行拆分操作的目标字段。

定义目标的字段类型。允许的值：array、map、string。string 需要使用 delimiter 选项来指定要拆分字符串的字符。delimiter 的行为始终如同 keep_parent 设置为 true。默认值：array。

可以定义一组转换。此列表将在 response.transforms 之后以及根据 response.split[].keep_parent 和 response.split[].key_field 修改对象之后应用。

可用于响应的转换：[append、delete、set]。

可以读取以下状态：[.last_response.*、.first_event.*、.last_event.*、.cursor.*、.header.*、.url.*]。

可以将状态写入：[body.*]。

如果设置为 true，则将保留父文档中的字段（与 target 相同级别）。否则，将使用 target 作为根创建一个新文档。默认值：false。

如果使用 string 的 split 类型，则需要此参数。这是用于分割字符串的子字符串。例如，如果 delimiter 为 "\n"，字符串为 "line 1\nline 2"，则分割结果为 "line 1" 和 "line 2"。

在与 type: map 一起使用时有效。如果非空，则定义一个新字段，用于存储原始键值。

如果设置为 true，则忽略空值或缺失值，并继续处理下一个嵌套的 split 操作，而不是报错。默认值：false。

请注意，如果 ignore_empty_value 为 true 且最终结果为空，则不会发布任何事件，也不会进行游标更新。如果必须对所有响应进行游标更新，则应将其设置为 false，并且必须将摄取管道配置为容忍空事件集。

嵌套 split 操作。split 操作可以随意嵌套。只有应用最深层的 split 操作后，才会创建事件。

如果设置为 true，则在分页请求中发送 request.body 中的值。默认值：false。

将应用于响应以响应每个新页面请求的转换列表。将执行 request.transform 中的所有转换，然后添加 response.pagination 以根据需要修改下一个请求。对于后续响应，通常会执行 response.transforms 和 response.split。

可用的分页转换：[append，delete，set]。

可以读取以下状态：[.last_response.*，.first_event.*，.last_event.*，.cursor.*，.header.*，.url.*，.body.*]。

可以将状态写入：[body.*、header.*、url.*]。

使用 split 的示例

链是一系列在第一个请求之后要发出的请求。

包含链式调用的基本请求和响应配置。

参见 请求参数。必需。

示例

第一次调用：https://example.com/services/data/v1.0/

第二次调用：https://example.com/services/data/v1.0/1/export_ids

第三次调用：https://example.com/services/data/v1.0/export_ids/file_1/info

参见 response split 参数。

+

用于从先前链式步骤中收集的响应 JSON 中解析值的 JSONPath 字符串。将相同的替换字符串放在应放置先前调用中收集的值的 URL 中。必需。

示例

filebeat.inputs:
- type: httpjson
  enabled: true
  # first call
  request.url: https://example.com/services/data/v1.0/records
  interval: 1h
  chain:
    # second call
    - step:
        request.url: https://example.com/services/data/v1.0/$.records[:].id/export_ids
        request.method: GET
        replace: $.records[:].id
    # third call
    - step:
        request.url: https://example.com/services/data/v1.0/export_ids/$.file_name/info
        request.method: GET
        replace: $.file_name

示例

filebeat.inputs:
- type: httpjson
  enabled: true
  # first call
  request.url: https://example.com/services/data/v1.0/records
  interval: 1h
  chain:
    # second call
    - step:
        request.url: placeholder:$.records[:]
        request.method: GET
        replace: $.records[:]
    # third call
    - step:
        request.url: placeholder:$.file_name
        request.method: GET
        replace: $.file_name

+

replace_with: "pattern,value" 子句用于将 request.url 中定义的固定模式字符串替换为给定的值。固定模式必须具有 $. 前缀，例如：$.xyz。value 可以是硬编码的，也可以从上下文变量中提取，例如 [.last_response.*，.first_response.*，.parent_last_response.*] 等。replace_with 子句可以与 replace 子句结合使用，从而在链式请求的逻辑中提供很大的灵活性。

示例

filebeat.inputs:
- type: httpjson
  enabled: true
  # first call
  request.url: https://example.com/services/data/v1.0/exports
  interval: 1h
  chain:
    # second call
    - step:
        request.url: https://example.com/services/data/v1.0/$.exportId/files
        request.method: GET
        replace_with: '$.exportId,.first_response.body.exportId'

示例

一些有用的要点：-

包含链式 while 调用的基本请求和响应配置。链式 while 调用将继续发出给定次数的请求，直到满足条件或达到最大尝试次数。While 链具有一个属性 until，它保存要评估的表达式。理想情况下，until 字段应始终与属性 request.retry.max_attempts 和 request.retry.wait_min 一起使用，它们分别指定在放弃之前评估 until 的最大尝试次数和这些请求之间的最大等待时间。如果未指定 request.retry.max_attempts，它将只尝试评估一次表达式，如果失败则放弃。如果未指定 request.retry.wait_min，则默认等待时间将始终为 0，因为将立即进行连续调用。

参见 请求参数。

示例

第一次调用：http://example.com/services/data/v1.0/exports

第二次调用：http://example.com/services/data/v1.0/9ef0e6a5/export_ids/status

第三次调用：http://example.com/services/data/v1.0/export_ids/1/info

参见 response split 参数。

参见 chain[].step.replace。

示例

filebeat.inputs:
- type: httpjson
  enabled: true
  # first call
  id: my-httpjson-id
  request.url: http://example.com/services/data/v1.0/exports
  interval: 1h
  chain:
    # second call
    - while:
        request.url: http://example.com/services/data/v1.0/$.exportId/export_ids/status
        request.method: GET
        replace: $.exportId
        until: '[[ eq .last_response.body.status "completed" ]]'
        request.retry.max_attempts: 5
        request.retry.wait_min: 5s
    # third call
    - step:
        request.url: http://example.com/services/data/v1.0/export_ids/$.files[:].id/info
        request.method: GET
        replace: $.files[:].id

示例

filebeat.inputs:
- type: httpjson
  enabled: true
  # first call
  id: my-httpjson-id
  request.url: http://example.com/services/data/v1.0/exports
  interval: 1h
  chain:
    # second call
    - while:
        request.url: placeholder:$.exportId
        request.method: GET
        replace: $.exportId
        until: '[[ eq .last_response.body.status "completed" ]]'
        request.retry.max_attempts: 5
        request.retry.wait_min: 5s
    # third call
    - step:
        request.url: placeholder:$.files[:]
        request.method: GET
        replace: $.files[:]

参见 chain[].step.replace_with。

Cursor 是一个键值对象列表，其中定义了任意值。这些值被解释为 值模板，并且可以设置默认模板。Cursor 状态在输入重启之间保持不变，并在所有针对请求的事件发布后更新。

如果没有发布事件，则不会进行 Cursor 更新。这可能会影响目标 API 返回空响应集时应如何执行 Cursor 更新。

每个 Cursor 条目由以下部分组成：

可以从以下位置读取状态：[.last_response.*，.first_event.*，.last_event.*]。

filebeat.inputs:
- type: httpjson
  interval: 1m
  request.url: https://api.ipify.org/?format=json
  response.transforms:
    - set:
        target: body.last_requested_at
        value: '[[.cursor.last_requested_at]]'
        default: "[[now]]"
  cursor:
    last_requested_at:
      value: '[[now]]'
  processors:
    - decode_json_fields:
        fields: ["message"]
        target: "json"

此输入在 HTTP 监控端点 下公开指标。这些指标在 /inputs 路径下公开。它们可以用于观察输入的活动。

所有输入都支持以下配置选项。

使用 enabled 选项启用和禁用输入。默认情况下，enabled 设置为 true。

Filebeat 在每个发布事件的 tags 字段中包含的一系列标签。标签使在 Kibana 中选择特定事件或在 Logstash 中应用条件过滤变得容易。这些标签将附加到在常规配置中指定的标签列表中。

示例

filebeat.inputs:
- type: httpjson
  . . .
  tags: ["json"]

您可以指定的可选字段，以向输出添加其他信息。例如，您可以添加可用于过滤日志数据的字段。字段可以是标量值、数组、字典或这些的任何嵌套组合。默认情况下，您在此处指定的字段将在输出文档中的 fields 子字典下分组。要将自定义字段存储为顶级字段，请将 fields_under_root 选项设置为 true。如果在常规配置中声明了重复字段，则其值将被此处声明的值覆盖。

filebeat.inputs:
- type: httpjson
  . . .
  fields:
    app_id: query_engine_12

如果将此选项设置为 true，则自定义 fields 将存储为输出文档中的顶级字段，而不是分组在 fields 子字典下。如果自定义字段名称与 Filebeat 添加的其他字段名称冲突，则自定义字段会覆盖其他字段。

要应用于输入数据的处理器列表。

有关在配置中指定处理器的信息，请参见 处理器。

为此输入生成的事件设置的摄取管道 ID。

如果将此选项设置为 true，则输出文档中将发布具有 null 值的字段。默认情况下，keep_null 设置为 false。

如果存在，此格式化字符串将覆盖此输入的事件索引（对于 elasticsearch 输出），或设置事件元数据的 raw_index 字段（对于其他输出）。此字符串只能引用代理名称和版本以及事件时间戳；要访问动态字段，请使用 output.elasticsearch.index 或处理器。

示例值："%{[agent.name]}-myindex-%{+yyyy.MM.dd}" 可能会扩展为 "filebeat-myindex-2019.11.01"。

默认情况下，所有事件都包含 host.name。此选项可以设置为 true 以禁用将此字段添加到所有事件中。默认值为 false。