« Elastic Salesforce 连接器参考 Elastic SharePoint Online 连接器参考 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›使用 Elastic 连接器提取内容 ›连接器参考

Elastic ServiceNow 连接器参考

编辑

Elastic ServiceNow 连接器参考

编辑

Elastic ServiceNow 连接器是适用于 ServiceNow 的连接器。

此连接器使用 Elastic 连接器框架以 Python 编写。

查看此连接器的源代码（分支 8.17，与 Elastic 8.17 兼容）。

选择您的连接器参考

您正在 Elastic Cloud 上使用托管连接器还是自托管连接器？根据您的部署方法展开文档。

Elastic 托管连接器参考

编辑
查看 Elastic 托管连接器 参考
可用性和先决条件
编辑

ServiceNow 连接器自 8.10.0 版本起在 Elastic Cloud 中原生可用。

要在 Elastic Cloud 中原生使用此连接器，请满足所有托管连接器要求。

创建 ServiceNow 连接器
编辑

使用 UI

编辑

要创建新的 ServiceNow 连接器

  1. 在 Kibana UI 中，从主菜单导航至搜索 → 内容 → 连接器页面，或使用全局搜索字段。
  2. 按照说明创建新的原生 ServiceNow 连接器。

有关其他操作，请参阅Kibana 中的连接器 UI。

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API 来创建新的原生 ServiceNow 连接器。

例如

resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
    is_native=True,
)
print(resp)
const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
  is_native: true,
});
console.log(response);
PUT _connector/my-servicenow-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from ServiceNow",
  "service_type": "servicenow",
  "is_native": true
}
您还需要为连接器创建一个API 密钥以供使用。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建 API 密钥

  1. 运行以下命令，并在指定位置替换值。记下响应中的 id 和 encoded 返回值

    resp = client.security.create_api_key(
    name="my-connector-api-key",
    role_descriptors={
        "my-connector-connector-role": {
            "cluster": [
                "monitor",
                "manage_connector"
            ],
            "indices": [
                {
                    "names": [
                        "my-index_name",
                        ".search-acl-filter-my-index_name",
                        ".elastic-connectors*"
                    ],
                    "privileges": [
                        "all"
                    ],
                    "allow_restricted_indices": False
                }
            ]
        }
    },
)
print(resp)
    const response = await client.security.createApiKey({
  name: "my-connector-api-key",
  role_descriptors: {
    "my-connector-connector-role": {
      cluster: ["monitor", "manage_connector"],
      indices: [
        {
          names: [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*",
          ],
          privileges: ["all"],
          allow_restricted_indices: false,
        },
      ],
    },
  },
});
console.log(response);
    POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

  2. 使用 encoded 值来存储连接器密钥，并记下此响应中的 id 返回值

    resp = client.connector.secret_post(
    body={
        "value": "encoded_api_key"
    },
)
print(resp)
    const response = await client.connector.secretPost({
  body: {
    value: "encoded_api_key",
  },
});
console.log(response);
    POST _connector/_secret
{
  "value": "encoded_api_key"
}

  3. 使用 API 密钥 id 和连接器密钥 id 来更新连接器

    resp = client.connector.update_api_key_id(
    connector_id="my_connector_id>",
    api_key_id="API key_id",
    api_key_secret_id="secret_id",
)
print(resp)
    const response = await client.connector.updateApiKeyId({
  connector_id: "my_connector_id>",
  api_key_id: "API key_id",
  api_key_secret_id: "secret_id",
});
console.log(response);
    PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器 API 的详细信息，请参阅Elasticsearch API 文档。

用法
编辑

要在 Elastic Cloud 中原生使用此连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅Kibana 中的连接器 UI

兼容性
编辑

ServiceNow 连接器与以下版本的 ServiceNow 兼容

  • ServiceNow "东京"
  • ServiceNow "圣地亚哥"
  • ServiceNow "罗马"
  • ServiceNow "犹他"
  • ServiceNow "温哥华"
  • ServiceNow "华盛顿"
  • ServiceNow "世外桃源"
配置
编辑

需要以下配置字段来设置连接器

ServiceNow URL
ServiceNow 实例的主机 URL。
用户名
用于 ServiceNow 的帐户的用户名。
密码
用于 ServiceNow 的帐户的密码。
以逗号分隔的服务列表

从 ServiceNow 获取数据的以逗号分隔的服务列表。如果值为 *，则连接器将从 ServiceNow 提供的基本服务列表中获取数据

  • 用户
  • 事件
  • 请求的项目
  • 知识

  • 更改请求

    如果您配置了自定义服务，则默认情况下，* 值不会从上述基本服务中获取数据。在这种情况下，您需要明确提及这些服务名称。

    默认值为 *。示例

  • 用户、事件、请求的项目、知识、更改请求
  • *
启用文档级安全性
根据用户的权限限制对文档的访问。有关更多详细信息，请参阅文档级安全性。
文档和同步
编辑

用户有权访问的所有服务和记录都将根据提供的配置进行索引。连接器会同步以下 ServiceNow 对象类型

  • 记录
  • 附件
  • 不会提取大于 10 MB 的文件的内容。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
  • 默认情况下不同步权限。有关更多详细信息，请参阅文档级安全性。
同步类型
编辑

默认情况下，所有连接器都支持完整同步。

此连接器还支持增量同步。

文档级安全性
编辑

文档级安全性 (DLS) 可确保在 ServiceNow 中设置的身份和权限在 Elasticsearch 中保持不变。这使您可以限制和个性化用户和组对该索引中文档的读取访问权限。访问控制同步可确保此元数据在您的 Elasticsearch 文档中保持最新。

ServiceNow 连接器支持访问控制列表 (ACL) 的角色，以便在 Elasticsearch 中启用文档级安全性。对于默认服务，连接器使用以下角色来查找有权访问文档的用户。

服务 角色

用户

管理员

事件

admin、sn_incident_read、ml_report_user、ml_admin、itil

请求的项目

admin、sn_request_read、asset、atf_test_designer、atf_test_admin

知识

admin、knowledge、knowledge_manager、knowledge_admin

更改请求

admin、sn_change_read、itil

对于这些默认服务之外的服务，连接器会迭代带有 read 操作的访问控制，并查找这些服务的相应角色。

ServiceNow 连接器不支持脚本和条件权限。

同步规则
编辑

基本同步规则对于所有连接器都是相同的，并且默认可用。

高级同步规则
编辑

需要完整同步才能使高级同步规则生效。

高级同步规则通过特定于源的 DSL JSON 片段定义。

以下部分提供了此连接器的高级同步规则示例。

基于“事件”服务的事件编号索引文档

[
  {
    "service": "Incident",
    "query": "numberSTARTSWITHINC001"
  }
]

基于“用户”服务的用户活动状态索引文档

[
  {
    "service": "User",
    "query": "active=False"
  }
]

基于“知识”服务的作者姓名索引文档

[
  {
    "service": "Knowledge",
    "query": "author.nameSTARTSWITHSystem Administrator"
  }
]
已知问题
编辑

此连接器没有已知问题。有关影响所有连接器的已知问题列表，请参阅已知问题。

故障排除
编辑

请参阅故障排除。

安全性
编辑

请参阅安全性。

内容提取
编辑

请参阅内容提取。

自托管连接器

编辑
查看自托管连接器参考
可用性和先决条件
编辑

ServiceNow 连接器是在 Elastic 8.9.0 版本中引入的。此连接器作为自托管的自托管连接器提供。要将此连接器用作自托管连接器，请满足所有自托管连接器要求。

创建 ServiceNow 连接器
编辑

使用 UI

编辑

要创建新的 ServiceNow 连接器

  1. 在 Kibana UI 中，从主菜单导航至搜索 → 内容 → 连接器页面，或使用全局搜索字段。
  2. 按照说明创建新的 ServiceNow 自托管连接器。

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API 来创建新的自托管 ServiceNow 自托管连接器。

例如

resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
)
print(resp)
const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
});
console.log(response);
PUT _connector/my-servicenow-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from ServiceNow",
  "service_type": "servicenow"
}
您还需要为连接器创建一个API 密钥以供使用。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建 API 密钥

  1. 运行以下命令，并在指定位置替换值。记下响应中的 encoded 返回值

    resp = client.security.create_api_key(
    name="connector_name-connector-api-key",
    role_descriptors={
        "connector_name-connector-role": {
            "cluster": [
                "monitor",
                "manage_connector"
            ],
            "indices": [
                {
                    "names": [
                        "index_name",
                        ".search-acl-filter-index_name",
                        ".elastic-connectors*"
                    ],
                    "privileges": [
                        "all"
                    ],
                    "allow_restricted_indices": False
                }
            ]
        }
    },
)
print(resp)
    const response = await client.security.createApiKey({
  name: "connector_name-connector-api-key",
  role_descriptors: {
    "connector_name-connector-role": {
      cluster: ["monitor", "manage_connector"],
      indices: [
        {
          names: [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*",
          ],
          privileges: ["all"],
          allow_restricted_indices: false,
        },
      ],
    },
  },
});
console.log(response);
    POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}
  2. 使用 API 密钥 encoded 值更新您的 config.yml 文件。

有关所有可用连接器 API 的详细信息，请参阅Elasticsearch API 文档。

用法
编辑

要将此连接器用作自托管连接器，请使用自定义连接器工作流。

有关其他操作，请参阅用法。

兼容性
编辑

ServiceNow 连接器与以下版本的 ServiceNow 兼容

  • ServiceNow "东京"
  • ServiceNow "圣地亚哥"
  • ServiceNow "罗马"
  • ServiceNow "犹他"
  • ServiceNow "温哥华"
  • ServiceNow "华盛顿"
  • ServiceNow "世外桃源"
配置
编辑

当使用自管理连接器工作流程时，这些字段最初将使用在连接器源代码中设置的默认配置。这些配置在 get_default_configuration 函数定义中设置。

这些可配置字段将在 Kibana UI 中使用它们各自的标签呈现。连接后，您将能够在 Kibana 中更新这些值。

需要以下配置字段来设置连接器

url
ServiceNow 实例的主机 URL。
username
ServiceNow 帐户的用户名。
password
用于 ServiceNow 的帐户的密码。
services

从 ServiceNow 获取数据的以逗号分隔的服务列表。如果值为 *，则连接器将从 ServiceNow 提供的基本服务列表中获取数据

  • 用户
  • 事件
  • 请求的项目
  • 知识

  • 更改请求

    如果您配置了自定义服务，则默认情况下，* 值不会从上述基本服务中获取数据。在这种情况下，您需要明确提及这些服务名称。

    默认值为 *。示例

  • 用户、事件、请求的项目、知识、更改请求
  • *
retry_count
在向 ServiceNow 发出请求失败后，重试尝试的次数。默认值为 3。
concurrent_downloads
用于获取附件内容的并发下载数量。这可以加快附件的内容提取速度。默认为 10。
use_text_extraction_service
需要单独部署Elastic 文本提取服务。需要禁用文本提取的摄取管道设置。默认值为 False。
use_document_level_security
根据用户的权限限制对文档的访问。有关更多详细信息，请参阅文档级安全。
文档和同步
编辑

用户有权访问的所有服务和记录都将根据提供的配置进行索引。连接器会同步以下 ServiceNow 对象类型

  • 记录
  • 附件
  • 不会提取大于 10 MB 的文件的内容。使用自管理的本地提取服务来处理较大的二进制文件。
  • 默认情况下，权限不会同步。您必须启用文档级安全。否则，索引到 Elastic 部署中的所有文档将对所有有权访问该 Elastic 部署的用户可见。
同步类型
编辑

默认情况下，所有连接器都支持完整同步。

此连接器还支持增量同步。

文档级安全
编辑

文档级安全性 (DLS) 可确保在 ServiceNow 中设置的身份和权限在 Elasticsearch 中保持不变。这使您可以限制和个性化用户和组对该索引中文档的读取访问权限。访问控制同步可确保此元数据在您的 Elasticsearch 文档中保持最新。

ServiceNow 连接器支持访问控制列表 (ACL) 的角色，以便在 Elasticsearch 中启用文档级安全性。对于默认服务，连接器使用以下角色来查找有权访问文档的用户。

服务 角色

用户

管理员

事件

admin、sn_incident_read、ml_report_user、ml_admin、itil

请求的项目

admin、sn_request_read、asset、atf_test_designer、atf_test_admin

知识

admin、knowledge、knowledge_manager、knowledge_admin

更改请求

admin、sn_change_read、itil

对于这些默认服务之外的服务，连接器会迭代带有 read 操作的访问控制，并查找这些服务的相应角色。

ServiceNow 连接器不支持脚本和条件权限。

使用 Docker 部署
编辑

您可以使用 Docker 将 ServiceNow 连接器部署为自管理连接器。请按照以下说明进行操作。

步骤 1：下载示例配置文件

下载示例配置文件。您可以手动下载它，也可以运行以下命令

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

如果您的目录名称不同，或者您想使用不同的配置文件名称，请记住更新 --output 参数值。

步骤 2：更新自管理连接器的配置文件

使用以下设置更新配置文件，以匹配您的环境

  • elasticsearch.host
  • elasticsearch.api_key
  • connectors

如果您针对 Docker 化的 Elasticsearch 和 Kibana 版本运行连接器服务，您的配置文件将如下所示

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: servicenow
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

建议使用 elasticsearch.api_key 作为身份验证方法。但是，您也可以使用 elasticsearch.username 和 elasticsearch.password 来对您的 Elasticsearch 实例进行身份验证。

注意：您可以通过简单地取消注释配置文件中的特定设置并修改其值来更改其他默认配置。

步骤 3：运行 Docker 镜像

使用以下命令运行带有连接器服务的 Docker 镜像

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.17.0.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

有关更多详细信息，请参阅 elastic/connectors 存储库中的 DOCKER.md。

在官方注册表中查找所有可用的 Docker 镜像。

我们还有一个使用 Docker Compose 的快速启动自管理选项，因此您可以一次启动所有必需的服务：Elasticsearch、Kibana 和连接器服务。有关更多信息，请参阅 elastic/connectors 存储库中的 README。

同步规则
编辑

基本同步规则对于所有连接器都是相同的，并且默认可用。

高级同步规则
编辑

需要完整同步才能使高级同步规则生效。

高级同步规则通过特定于源的 DSL JSON 片段定义。

以下部分提供了此连接器的高级同步规则示例。

基于 Incident 服务的事件编号索引文档

[
  {
    "service": "Incident",
    "query": "numberSTARTSWITHINC001"
  }
]

基于 User 服务的用户活动状态索引文档

[
  {
    "service": "User",
    "query": "active=False"
  }
]

基于 Knowledge 服务的作者姓名索引文档

[
  {
    "service": "Knowledge",
    "query": "author.nameSTARTSWITHSystem Administrator"
  }
]
端到端测试
编辑

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 ServiceNow 连接器执行 E2E 测试，请运行以下命令

$ make ftest NAME=servicenow

使用以下标志生成性能报告：PERF8=yes。使用参数 DATA_SIZE= 在 SMALL、MEDIUM 和 LARGE 之间切换测试数据集大小。默认情况下，它设置为 MEDIUM。

用户无需运行 Elasticsearch 实例或 ServiceNow 源即可运行此测试。Docker Compose 管理开发环境的完整设置。

已知问题
编辑

此连接器没有已知问题。有关影响所有连接器的已知问题列表，请参阅已知问题。

故障排除
编辑

请参阅故障排除。

安全性
编辑

请参阅安全性。

内容提取
编辑

请参阅内容提取。

« Elastic Salesforce 连接器参考 Elastic SharePoint Online 连接器参考 »