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-jira-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Jira",
  "service_type": "jira",
  "is_native": true
}

您还需要为连接器创建一个 API 密钥以供使用。

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

要为连接器创建 API 密钥

运行以下命令，在指示的位置替换值。请注意响应中的 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
        }
      ]
    }
  }
}

使用 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"
}

使用 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。

兼容性

编辑

Jira Cloud、Jira Server 和 Jira Data Center 7 或更高版本。

配置

编辑

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

Jira 数据源

用于确定 Jira 平台类型的下拉列表：Jira Cloud、Jira Server 或 Jira Data Center。默认值为 Jira Cloud。

Jira Data Center 用户名

Jira Data Center 帐户的用户名。

Jira Data Center 密码

用于 Jira Data Center 的帐户密码。

Jira Cloud 服务帐户 ID

用于通过 Jira Cloud 进行身份验证的电子邮件地址。示例：[email protected]

Jira Cloud API 令牌

用于通过 Jira Cloud 进行身份验证的 API 令牌。

Jira Server 用户名

Jira Server 帐户的用户名。

Jira Server 密码

用于 Jira Server 的帐户密码。

Jira Cloud 服务帐户 ID

Jira Cloud 的帐户电子邮件。

Jira Cloud API 令牌

用于通过 Jira Cloud 进行身份验证的 API 令牌。

Jira 主机 URL

Jira 托管的域。示例

Jira 项目密钥

要从 Jira 服务器或云中获取数据的项目密钥的逗号分隔列表。如果值为 *，则连接器将从配置的项目中存在的所有项目获取数据。默认值为 *。示例

EC, TP
*

启用 SSL

是否启用 SSL 验证。默认值为 False。

SSL 证书

SSL 证书的内容。注意：如果 ssl_enabled 为 False，则将忽略 ssl_ca 值。示例证书

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

启用文档级别安全性

切换以启用文档级别安全性 (DLS)。启用后，完整同步将提取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。访问控制同步将提取用户的访问控制列表，并将其存储在单独的索引中。

要访问 Jira 管理中的用户数据，您创建的帐户必须被授予 Jira 管理的 产品访问权限。此访问权限需要由Atlassian 管理员提供，并且授予的访问级别应为 Product Admin。

文档和同步

编辑

连接器同步以下对象和实体

项目
- 包括诸如描述、项目密钥、项目类型、负责人姓名等元数据。
问题
- 所有类型的问题，包括任务、错误、子任务、增强、故事等。
- 包括诸如问题类型、父问题详细信息、修复版本、受影响版本、解决方法、附件、评论、子任务详细信息、优先级、自定义字段等元数据。
附件

注意：已存档的项目和问题不会被索引。

不会提取大于 10 MB 的文件中的内容。（自托管连接器可以使用自托管本地提取服务来处理更大的二进制文件。）
默认情况下，不会同步权限。您必须先启用DLS。否则，索引到 Elastic 部署的所有文档都将对所有有权访问该 Elastic 部署的用户可见。

同步类型

编辑

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

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

同步规则

编辑

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

此连接器支持用于远程过滤的高级同步规则。这些规则涵盖了无法用基本同步规则表达的复杂查询和筛选场景。高级同步规则通过特定于源的 DSL JSON 代码片段定义。

高级同步规则示例

编辑

示例 1：根据 Jira 问题的状态查询以索引内容。

[
  {
    "query": "project = Collaboration AND status = 'In Progress'"
  },
  {
    "query": "status IN ('To Do', 'In Progress', 'Closed')"
  }
]

示例 2：查询以根据给定项目的优先级索引数据。

[
  {
    "query": "priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)"
  }
]

示例 3：查询以根据受让人和创建时间索引数据。

[
  {
    "query": "assignee is EMPTY and created < -1d"
  }
]

文档级别安全性

编辑

文档级别安全性 (DLS) 使您能够根据用户的权限限制对文档的访问。有关如何为此连接器启用 DLS，请参阅此页面上的配置。

为您的连接器启用 DLS 将会导致严重的性能下降，因为此功能所需的数据源的 API 调用受到速率限制。这会影响检索内容的速度。

当 data_source 设置为 Confluence Data Center 或 Server 时，由于所使用的 API 存在限制，连接器仅会提取 1000 个用户进行访问控制同步。

请参阅搜索应用程序中的 DLS，了解如何在构建搜索应用程序时提取启用 DLS 的连接器中的数据。示例使用 SharePoint Online 作为数据源，但相同的步骤适用于每个连接器。

内容提取

编辑

请参阅内容提取。

已知问题

编辑

启用文档级别安全性会影响性能。

为您的连接器启用 DLS 将会导致严重的性能下降，因为此功能所需的数据源的 API 调用受到速率限制。这会影响检索内容的速度。

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

自管理连接器

编辑

查看自管理连接器参考

可用性和先决条件

编辑

此连接器作为自管理的自管理连接器提供。此自管理连接器与 Elastic 版本 8.7.0+ 兼容。

要使用此连接器，请满足所有自管理连接器要求。

创建 Jira 连接器

编辑

使用 UI

编辑

要创建新的 Jira 连接器

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

使用 API

编辑

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

例如

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-jira-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Jira",
  "service_type": "jira"
}

您还需要为连接器创建一个 API 密钥以供使用。

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

要为连接器创建 API 密钥

运行以下命令，替换指示的值。请注意响应中的 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
        }
      ]
    }
  }
}

使用 API 密钥 encoded 值更新您的 config.yml 文件。

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

用法

编辑

要将此连接器用作自管理连接器，请参阅自管理连接器。有关其他使用操作，请参阅Kibana 中的连接器 UI。

兼容性

编辑

Jira Cloud、Jira Server 和 Jira Data Center 7 或更高版本。

配置

编辑

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

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

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

data_source

用于确定 Jira 平台类型的下拉列表：Jira Cloud、Jira Server 或 Jira Data Center。默认值为 Jira Cloud。

data_center_username

Jira Data Center 帐户的用户名。

data_center_password

用于 Jira Data Center 的帐户密码。

username

Jira Server 帐户的用户名。

password

用于 Jira Server 的帐户密码。

account_email

用于通过 Jira Cloud 进行身份验证的电子邮件地址。示例：[email protected]

api_token

用于通过 Jira Cloud 进行身份验证的 API 令牌。

jira_url

Jira 托管的域。示例

projects

要从 Jira 服务器或云中获取数据的项目密钥的逗号分隔列表。如果值为 *，则连接器将从配置的项目中存在的所有项目获取数据。默认值为 *。示例

EC, TP
*

可以通过高级同步规则绕过此字段。

ssl_enabled

是否启用 SSL 验证。默认值为 False。

ssl_ca

SSL 证书的内容。注意：如果 ssl_enabled 为 False，则将忽略 ssl_ca 值。示例证书

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

retry_count

请求 Jira 失败后重试的次数。默认值为 3。

concurrent_downloads

用于获取附件内容的并发下载次数。这加快了附件的内容提取速度。默认为 100。

use_document_level_security

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要摄取管道设置禁用文本提取。默认值为 False。

使用 Docker 部署

编辑

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

步骤 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: jira
    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。

文档和同步

编辑

连接器同步以下对象和实体

项目
- 包括诸如描述、项目密钥、项目类型、负责人姓名等元数据。
问题
- 所有类型的问题，包括任务、错误、子任务、增强、故事等。
- 包括诸如问题类型、父问题详细信息、修复版本、受影响版本、解决方法、附件、评论、子任务详细信息、优先级、自定义字段等元数据。
附件

注意：已存档的项目和问题不会被索引。

不会提取大于 10 MB 的文件内容
默认情况下不会同步权限。您必须首先启用DLS。否则，索引到 Elastic 部署的所有文档将对所有有权访问该 Elastic 部署的用户可见。

同步类型

编辑

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

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

同步规则

编辑

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

高级同步规则示例

编辑

示例 1：根据 Jira 问题的状态查询以索引内容。

[
  {
    "query": "project = Collaboration AND status = 'In Progress'"
  },
  {
    "query": "status IN ('To Do', 'In Progress', 'Closed')"
  }
]

示例 2：查询以根据给定项目的优先级索引数据。

[
  {
    "query": "priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)"
  }
]

示例 3：查询以根据受让人和创建时间索引数据。

[
  {
    "query": "assignee is EMPTY and created < -1d"
  }
]

文档级安全性

编辑

文档级安全性 (DLS) 使您能够根据用户的权限限制对文档的访问。有关如何为此连接器启用 DLS，请参阅本页上的配置。

为您的连接器启用 DLS 将会导致严重的性能下降，因为此功能所需的数据源的 API 调用受到速率限制。这会影响检索内容的速度。

当 data_source 设置为 Confluence Data Center 或 Server 时，由于所使用的 API 存在限制，连接器仅会提取 1000 个用户进行访问控制同步。

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

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

$ make ftest NAME=jira

为了加快测试速度，请添加 DATA_SIZE=small 标志

make ftest NAME=jira DATA_SIZE=small

已知问题

编辑

启用文档级别安全性会影响性能。

为您的连接器启用 DLS 将会导致严重的性能下降，因为此功能所需的数据源的 API 调用受到速率限制。这会影响检索内容的速度。

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

« Elastic GraphQL 连接器参考 Elastic Microsoft SQL 连接器参考 »

Elastic Jira 连接器参考