Link Search Menu Expand Document Documentation Menu
文档

IP2Geo 处理器

2.10 版引入

ip2geo 处理器添加有关 IPv4 或 IPv6 地址地理位置的信息。ip2geo 处理器使用来自外部端点的 IP 地理位置（GeoIP）数据，因此需要一个额外的组件 datasource，用于定义从何处下载 GeoIP 数据以及更新数据的频率。

信息图标 注意
ip2geo 处理器在系统索引中维护 GeoIP 数据映射。在数据摄取期间从这些索引检索 GeoIP 映射，以对传入数据执行 IP 到地理位置的转换。为了获得最佳性能，最好有一个同时具有摄取和数据角色的节点，因为这种配置可以避免节点间调用，从而减少延迟。此外，由于 ip2geo 处理器从索引中搜索 GeoIP 映射数据，因此搜索性能会受到影响。

入门

要开始使用 ip2geo 处理器，必须安装 opensearch-geospatial 插件。有关更多信息，请参阅安装插件。

集群设置

下表列出了 IP2Geo 数据源和 ip2geo 处理器节点设置。此表中的所有设置都是动态的。要了解有关静态和动态设置的更多信息，请参阅配置 OpenSearch。

键 描述 默认值
plugins.geospatial.ip2geo.datasource.endpoint 创建数据源 API 的默认端点。 默认值为 https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json。
plugins.geospatial.ip2geo.datasource.update_interval_in_days 创建数据源 API 的默认更新间隔。 默认值为 3。
plugins.geospatial.ip2geo.datasource.batch_size IP2Geo 数据源创建过程中批量请求中要摄取的最大文档数。 默认值为 10,000。
plugins.geospatial.ip2geo.processor.cache_size 可缓存的最大结果数。每个节点中所有 IP2Geo 处理器只使用一个缓存。 默认值为 1,000。
plugins.geospatial.ip2geo.timeout 等待来自端点和集群响应的时间量。 默认值为 30 秒。

创建 IP2Geo 数据源

在使用 ip2geo 处理器创建管道之前，请创建 IP2Geo 数据源。数据源定义了用于下载 GeoIP 数据的端点值，并指定了更新间隔。

OpenSearch 提供以下来自 MaxMind 的 GeoLite2 City、GeoLite2 Country 和 GeoLite2 ASN 数据库的端点，这些数据库在 CC BY-SA 4.0 许可下共享

  • GeoLite2 City: https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json
  • GeoLite2 Country: https://geoip.maps.opensearch.org/v1/geolite2-country/manifest.json
  • GeoLite2 ASN: https://geoip.maps.opensearch.org/v1/geolite2-asn/manifest.json

如果 OpenSearch 集群在 30 天内无法从端点更新数据源，则集群不会向文档添加 GeoIP 数据，而是添加 "error":"ip2geo_data_expired"。

数据源选项

下表列出了 ip2geo 处理器的数据源选项。

名称 必需 默认值 描述
endpoint 可选 https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json 下载 GeoIP 数据的端点。
update_interval_in_days 可选 3 GeoIP 数据更新的频率（以天为单位）。最小值为 1。

要创建 IP2Geo 数据源，请运行以下查询

PUT /_plugins/geospatial/ip2geo/datasource/my-datasource
{
    "endpoint" : "https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json",
    "update_interval_in_days" : 3
}

true 响应表示请求成功，服务器能够处理该请求。false 响应表示您应该检查请求以确保其有效，检查 URL 以确保其正确，或重试。

发送 GET 请求

要获取一个或多个 IP2Geo 数据源的信息，请发送 GET 请求

GET /_plugins/geospatial/ip2geo/datasource/my-datasource

您将收到以下响应

{
  "datasources": [
    {
      "name": "my-datasource",
      "state": "AVAILABLE",
      "endpoint": "https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json",
      "update_interval_in_days": 3,
      "next_update_at_in_epoch_millis": 1685125612373,
      "database": {
        "provider": "maxmind",
        "sha256_hash": "0SmTZgtTRjWa5lXR+XFCqrZcT495jL5XUcJlpMj0uEA=",
        "updated_at_in_epoch_millis": 1684429230000,
        "valid_for_in_days": 30,
        "fields": [
          "country_iso_code",
          "country_name",
          "continent_name",
          "region_iso_code",
          "region_name",
          "city_name",
          "time_zone",
          "location"
        ]
      },
      "update_stats": {
        "last_succeeded_at_in_epoch_millis": 1684866730192,
        "last_processing_time_in_millis": 317640,
        "last_failed_at_in_epoch_millis": 1684866730492,
        "last_skipped_at_in_epoch_millis": 1684866730292
      }
    }
  ]
}

更新 IP2Geo 数据源

请参阅“创建 IP2Geo 数据源”部分，了解端点和请求字段的列表。

要更新日期源，请运行以下查询

PUT /_plugins/geospatial/ip2geo/datasource/my-datasource/_settings
{
    "endpoint": https://geoip.maps.opensearch.org/v1/geolite2-city/manifest.json,
    "update_interval_in_days": 10
}

删除 IP2Geo 数据源

要删除 IP2Geo 数据源，您必须首先删除与该数据源关联的所有处理器。否则，请求将失败。

要删除数据源，请运行以下查询

DELETE /_plugins/geospatial/ip2geo/datasource/my-datasource

创建管道

数据源创建后，您可以创建管道。

语法

以下是 ip2geo 处理器的语法

{
  "ip2geo": {
    "field":"ip",
    "datasource":"my-datasource"
  }
}

配置参数

下表列出了 ip2geo 处理器的必需和可选参数。

参数 必需/可选 描述
datasource 必需 用于检索地理信息的数据源名称。
field 必需 包含用于地理查找的 IP 地址的字段。
ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true，则如果字段不存在或为 null，处理器将不会修改文档。默认值为 false。
properties 可选 控制从 datasource 向 target_field 添加哪些属性的字段。默认值为 datasource 中的所有字段。
target_field 可选 包含从数据源检索到的地理信息的字段。默认值为 ip2geo。

使用处理器

按照以下步骤在管道中使用处理器。

步骤 1：创建管道

以下查询创建一个名为 my-pipeline 的管道，用于将 IP 地址转换为地理信息

PUT /_ingest/pipeline/my-pipeline
{
   "description":"convert ip to geo",
   "processors":[
    {
        "ip2geo":{
            "field":"ip",
            "datasource":"my-datasource"
        }
    }
   ] 
}

步骤 2（可选）：测试管道

信息图标 注意
建议在摄取文档之前测试您的管道。

要测试管道，请运行以下查询

POST _ingest/pipeline/my-pipeline/_simulate
{
  "docs": [
    {
      "_index": "testindex1",
      "_id": "1",
      "_source": {
        "ip": "172.0.0.1"
      }
    }
  ]
}

响应

以下响应确认管道按预期工作

{
  "docs": [
    {
      "_index":"testindex1",
      "_id":"1",
      "_source":{
        "ip":"172.0.0.1",
        "ip2geo":{
         "continent_name":"North America",
         "region_iso_code":"AL",
         "city_name":"Calera",
         "country_iso_code":"US",
         "country_name":"United States",
         "region_name":"Alabama",
         "location":"33.1063,-86.7583",
         "time_zone":"America/Chicago"
         }
      }
    }
  ]
}

步骤 3：摄取文档

以下查询将文档摄取到名为 my-index 的索引中

PUT /my-index/_doc/my-id?pipeline=my-pipeline
{
  "ip": "172.0.0.1"
}

步骤 4（可选）：检索文档

要检索文档，请运行以下查询

GET /my-index/_doc/my-id

剩余 350 字符

有问题？。

想要贡献？ 或。