创建连接器 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
删除连接器 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
获取连接器 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
列出连接器 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器API密钥ID [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器配置 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器功能 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器过滤 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器索引名称 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器名称和描述 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器管道 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器调度 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
更新连接器服务类型 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且按原样提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。

同步作业API

edit

您可以使用这些API来创建、取消、删除和更新同步作业。

使用以下API来管理同步作业：

创建连接器同步作业 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且以“原样”提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
取消连接器同步作业 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且以“原样”提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
删除连接器同步作业 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且以“原样”提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
获取连接器同步作业 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且以“原样”提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。
列出连接器同步作业 [beta] 此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且以“原样”提供，不提供任何保证。测试功能不受正式发布功能的SLA支持。

服务API

edit

此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。

连接器服务API是连接器API端点的一个子集，代表了在连接器协议中定义的框架级操作。这些API并不旨在供用户直接管理连接器，而是为了支持使用连接器协议与Elasticsearch进行通信的服务的实现。

所有Elastic连接器都是使用我们的Python连接器框架构建的。源代码可在GitHub上的elastic/connectors仓库中获取。

连接器服务API

edit

Check in a connector [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
更新连接器错误 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
更新连接器最后同步统计信息 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
更新连接器状态 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

同步作业服务API

edit

Check in connector sync job [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
Claim connector sync job [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
Set connector sync job error [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
Set connector sync job stats [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

创建连接器 API

edit

创建一个Elastic连接器。连接器是Elasticsearch集成，用于从第三方数据源引入内容，可以在Elastic Cloud上部署或托管在自己的基础设施上：

托管连接器 是 Elastic Cloud 上的托管服务
自托管连接器 是在您的基础设施上自行托管的

在连接器文档中查找所有支持的服务类型的列表。

要开始使用连接器API，请查看我们的教程。

PUT _connector/my-connector
{
  "index_name": "search-google-drive",
  "name": "My Connector",
  "service_type": "google_drive"
}

请求

edit

POST _connector
PUT _connector/

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
service_type 参数应引用受支持的第三方服务。请参阅 Elastic 管理的和自管理的连接器的可用服务类型。这也可以引用您的自定义连接器的服务类型。

描述

edit

在内部索引中创建一个连接器文档，并使用默认值初始化其配置、过滤和调度。这些值可以根据需要稍后更新。

路径参数

edit

<connector_id>: (可选, 字符串) 连接器的唯一标识符。

请求体

edit

description: (可选，字符串) 连接器的描述。
index_name: (可选, 字符串) 目标索引用于同步数据。如果该索引不存在，将在第一次同步时创建。
name: (可选, 字符串) 连接器的名称。在 Kibana 中管理连接器时，设置连接器名称是推荐的。
is_native: (可选，布尔值) 指示是否为托管连接器。默认为 false。
language: （可选，字符串）数据的语言分析器。仅限于支持的语言。
service_type: (可选, 字符串) 连接器服务类型。可以引用Elastic支持的第三方服务或自定义连接器类型。请参阅Elastic托管和自托管连接器的可用服务类型。

响应体

edit

id: (字符串) 与连接器文档关联的ID。在使用POST请求时返回。
result: (字符串) 索引操作的结果，created 或 updated。在使用 PUT 请求时返回。

响应代码

edit

200: 表示已成功更新现有连接器。
201: 表示连接器已成功创建。
400: 表示请求格式不正确。

示例

edit

PUT _connector/my-connector
{
  "index_name": "search-google-drive",
  "name": "My Connector",
  "description": "My Connector to sync data to Elastic index from Google Drive",
  "service_type": "google_drive",
  "language": "en"
}

API返回以下结果：

{
  "result": "created",
  "id": "my-connector"
}

删除连接器 API

edit

移除一个连接器及其相关的同步作业。这是一个不可恢复的破坏性操作。

注意：此操作不会删除与连接器关联的任何API密钥、摄取管道或数据索引。这些需要手动删除。

要开始使用连接器API，请查看我们的教程。

请求

edit

DELETE _connector/

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）
delete_sync_jobs: (可选, 布尔值) 一个标志，指示是否也应删除关联的同步作业。默认为 false。

响应代码

edit

400: 未提供connector_id。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例删除了ID为 my-connector 的连接器：

DELETE _connector/another-connector?delete_sync_jobs=true

{
    "acknowledged": true
}

以下示例删除了ID为another-connector的连接器及其关联的同步作业。

获取连接器 API

edit

检索有关连接器的详细信息。

要开始使用连接器API，请查看我们的教程。

请求

edit

GET _connector/

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。

路径参数

edit

<connector_id>: （必需，字符串）

响应代码

edit

400: 未提供connector_id。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例获取连接器 my-connector：

GET _connector/my-connector

列出连接器 API

edit

返回有关所有已创建连接器的信息。

要开始使用连接器API，请查看我们的教程。

请求

edit

GET _connector

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。

路径参数

edit

size: (可选，整数) 要检索的最大结果数。默认为 100。
from: (可选，整数) 从第一个结果开始获取的偏移量。默认为 0。
index_name: (可选，字符串) 与连接器关联的索引名称的逗号分隔列表，用于过滤搜索结果。
connector_name: (可选, 字符串) 一个以逗号分隔的连接器名称列表，用于过滤搜索结果。
service_type: (可选，字符串) 用于过滤搜索结果的连接器服务类型的逗号分隔列表。

示例

edit

以下示例列出了所有连接器：

GET _connector

以下示例列出了前两个连接器：

GET _connector?from=0&size=2

一个列出与 search-google-drive Elasticsearch 索引关联的连接器的示例：

GET _connector?index_name=search-google-drive

一个列出所有服务类型为 sharepoint_online 的连接器的示例：

GET _connector?service_type=sharepoint_online

一个列出所有服务类型为 sharepoint_online 或 google_drive 的连接器的示例：

GET _connector?service_type=sharepoint_online,google_drive

更新连接器API密钥ID API

edit

更新连接器的 api_key_id 和/或 api_key_secret_id 字段，指定：

用于授权的API密钥的ID
存储API密钥的连接器密钥的ID

连接器密钥ID仅适用于Elastic管理的连接器。自管理的连接器不使用此字段。有关更多详细信息，请参阅以编程方式管理连接器API密钥的文档。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_api_key_id

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有的连接器。
api_key_id 参数应引用现有的 API 密钥。
api_key_secret_id 参数应引用包含编码 API 密钥值的现有连接器密钥。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

api_key_id: (可选, 字符串) 连接器将用于授权访问所需索引的API密钥ID。每个连接器最多可以关联一个API密钥。
api_key_secret_id: (可选，字符串) 包含编码 API 密钥的连接器密钥的 ID。这应与 api_key_id 引用的 API 密钥相同。这仅适用于 Elastic 管理的连接器。

响应代码

edit

200: 连接器 api_key_id 和/或 api_key_secret_id 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了连接器ID为my-connector的api_key_id和api_key_secret_id字段：

PUT _connector/my-connector/_api_key_id
{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

{
    "result": "updated"
}

更新连接器配置 API

edit

更新连接器的配置，允许在已注册的配置架构中更新配置值。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_configuration

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。
要更新配置 values，必须首先通过正在运行的 Elastic 连接器服务实例注册连接器 configuration 架构。
确保配置字段与第三方数据源的配置架构兼容。有关详细信息，请参阅各个连接器参考。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

values: （可选，对象）连接器的配置值，表示为在已注册模式中配置字段与其各自值之间的映射。
configuration: (可选, 对象) 连接器的配置模式定义。配置字段是一个映射，其中每个键代表一个特定的配置字段名称，值是一个 ConnectorConfiguration 对象。对于连接器管理，使用 values 传递配置值。configuration 对象由 Elastic 连接器服务用于注册连接器配置模式。

响应代码

edit

200: 连接器配置已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例配置了一个sharepoint_online连接器。您可以在SharePoint Online连接器文档中找到支持的配置选项，或者通过使用获取连接器检查连接器的configuration字段中的模式。

PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "tenant_id": "my-tenant-id",
        "tenant_name": "my-sharepoint-site",
        "client_id": "foo",
        "secret_value": "bar",
        "site_collections": "*"
    }
}

{
    "result": "updated"
}

当您首次设置连接器时，您需要提供所有必需的配置详细信息以开始运行同步。但您也可以使用此API仅更新字段的一个子集。以下是一个示例，仅更新sharepoint_online连接器的secret_value字段。其他配置值不会改变。

PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "secret_value": "foo-bar"
    }
}

{
    "result": "updated"
}

更新连接器索引名称 API

edit

更新连接器的 index_name 字段，指定连接器摄取的数据存储的索引。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_index_name

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

index_name: (必需, 字符串) 连接器导入数据的索引名称。每个索引名称最多可以关联一个连接器。

响应代码

edit

200: 连接器 index_name 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的index_name字段：

PUT _connector/my-connector/_index_name
{
    "index_name": "data-from-my-google-drive"
}

{
    "result": "updated"
}

更新连接器功能 API

edit

管理连接器的features。此端点可用于控制连接器的以下方面：

文档级安全
增量同步
高级同步规则
基本同步规则

通常，运行的连接器服务会自动管理这些功能。但是，您可以使用此API来覆盖默认行为。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_features

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

features

(必需，对象) 包含连接器特性的对象。

document_level_security (可选，对象) 控制是否通过enabled标志启用文档级安全性。
incremental_sync (可选，对象) 控制是否通过enabled标志启用增量同步。
native_connector_api_keys(可选，对象) 控制是否通过enabled标志启用托管连接器API密钥。
sync_rules（可选，对象）控制同步规则。
- advanced (可选，对象) 控制是否通过enabled标志启用高级同步规则。
- basic(可选，对象) 控制是否通过enabled标志启用基本同步规则。

响应代码

edit

200: 连接器 features 已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的features字段：

PUT _connector/my-connector/_features
{
  "features": {
    "document_level_security": {
      "enabled": true
    },
    "incremental_sync": {
      "enabled": true
    },
    "sync_rules": {
      "advanced": {
        "enabled": false
      },
      "basic": {
        "enabled": true
      }
    }
  }
}

{
    "result": "updated"
}

该端点支持对features字段的局部更新。例如，要仅更新document_level_security功能，您可以发送以下请求：

PUT _connector/my-connector/_features
{
  "features": {
    "document_level_security": {
      "enabled": true
    }
  }
}

{
    "result": "updated"
}

更新连接器过滤API

edit

更新连接器的草稿过滤配置，并将草稿验证状态标记为已编辑。过滤草稿在通过运行的Elastic连接器服务验证后将被激活。

过滤属性用于配置连接器的同步规则（包括基本和高级规则）。了解更多信息，请参阅同步规则。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_filtering

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。
过滤草稿在运行中的 Elastic 连接器服务验证后激活，draft.validation.state 必须为 valid。
如果在验证尝试后，draft.validation.state 等于 invalid，请检查 draft.validation.errors 并修复任何问题。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

rules

(可选，对象数组) 一个包含基本同步规则的数组，每个规则具有以下子属性：

id (必需，字符串)
规则的唯一标识符。
policy (必需，字符串)
指定策略，例如 include 或 exclude。
field (必需，字符串)
此规则适用的文档中的字段。
rule (必需，字符串)
规则的类型，例如 regex、starts_with、ends_with、contains、equals、<、> 等。
value (必需，字符串)
与规则一起用于匹配文档字段内容的值。
order (必需，数字)
规则应用的顺序。第一个匹配的规则将应用其策略。
created_at (可选，日期时间)
规则添加时的时间戳。默认为 now UTC 时间戳。
updated_at (可选，日期时间)
规则最后编辑时的时间戳。默认为 now UTC 时间戳。

advanced_snippet

(可选, 对象) 用于在查询时进行高级过滤, 具有以下子属性:

value (必需, 对象或数组)
直接传递给连接器的JSON对象/数组，用于高级过滤。
created_at (可选, 日期时间)
此JSON对象创建的时间戳。默认为now UTC时间戳。
updated_at (可选, 日期时间)
此JSON对象最后编辑的时间戳。默认为now UTC时间戳。

响应代码

edit

200: 连接器草稿过滤已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-g-drive-connector的Google Drive连接器的草稿基本同步规则。所有扩展名为.txt的Google Drive文件将被跳过：

PUT _connector/my-g-drive-connector/_filtering
{
    "rules": [
         {
            "field": "file_extension",
            "id": "exclude-txt-files",
            "order": 0,
            "policy": "exclude",
            "rule": "equals",
            "value": "txt"
        },
        {
            "field": "_",
            "id": "DEFAULT",
            "order": 1,
            "policy": "include",
            "rule": "regex",
            "value": ".*"
        }
    ]
}

{
    "result": "updated"
}

以下示例更新了ID为my-sql-connector的MySQL连接器的草稿高级同步规则。高级同步规则是每个连接器类型特有的。请参阅支持高级同步规则的连接器的参考资料，以获取语法和示例。

PUT _connector/my-sql-connector/_filtering
{
    "advanced_snippet": {
        "value": [{
            "tables": [
                "users",
                "orders"
            ],
            "query": "SELECT users.id AS id, orders.order_id AS order_id FROM users JOIN orders ON users.id = orders.user_id"
        }]
    }
}

{
    "result": "updated"
}

注意，您也可以在单个请求中更新草稿 rules 和 advanced_snippet。

一旦草稿更新，其验证状态将设置为edited。连接器服务随后将验证规则，并将验证状态报告为invalid或valid。如果状态为valid，则运行的Elastic连接器服务将激活草稿过滤。

更新连接器名称和描述 API

edit

更新连接器的name和description字段。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_name

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

name: （必需，字符串）连接器的名称。
description: (可选, 字符串) 连接器的描述。

响应代码

edit

200: 连接器 name 和 description 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的name和description字段：

PUT _connector/my-connector/_name
{
    "name": "Custom connector",
    "description": "This is my customized connector"
}

{
    "result": "updated"
}

更新连接器管道 API

edit

更新连接器的pipeline配置。

当您创建一个新的连接器时，摄取管道的配置会填充默认设置。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_pipeline

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

pipeline: (必需，对象) 连接器的管道配置。管道决定了数据在摄取到 Elasticsearch 期间如何处理。

管道配置必须包含以下属性：

extract_binary_content（必需，布尔值）一个标志，指示是否在摄取期间提取二进制内容。
name（必需，字符串）摄取管道的名称。
reduce_whitespace（必需，布尔值）一个标志，指示是否减少摄取内容中的额外空白。
run_ml_inference（必需，布尔值）一个标志，指示是否对摄取的内容运行机器学习推理。

响应代码

edit

200: 连接器 pipeline 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的pipeline属性：

PUT _connector/my-connector/_pipeline
{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}

{
    "result": "updated"
}

更新连接器调度API

edit

更新连接器的调度配置。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_scheduling

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

scheduling: (必需, 对象) 连接器的调度配置。此配置决定了连接器的同步操作频率。

调度配置包括以下属性，每个属性都表示为一个ScheduleConfig对象。如果scheduling对象不包含所有调度类型，则只会更新提供的那些；其他的将保持不变。

access_control（可选，ScheduleConfig 对象）定义了同步连接器访问控制设置的时间表。
full（可选，ScheduleConfig 对象）定义了完整内容同步的时间表。
incremental（可选，ScheduleConfig 对象）定义了增量内容同步的时间表。

每个ScheduleConfig对象包括以下子属性：

enabled（必需，布尔值）一个启用或禁用调度的标志。
interval（必需，字符串）一个表示同步调度计划的CRON表达式。该表达式定义了同步操作应发生的频率。它必须以有效的CRON格式提供。

响应代码

edit

200: 连接器 scheduling 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的scheduling属性：

PUT _connector/my-connector/_scheduling
{
    "scheduling": {
        "access_control": {
            "enabled": true,
            "interval": "0 10 0 * * ?"
        },
        "full": {
            "enabled": true,
            "interval": "0 20 0 * * ?"
        },
        "incremental": {
            "enabled": false,
            "interval": "0 30 0 * * ?"
        }
    }
}

{
    "result": "updated"
}

以下示例仅更新 full 同步计划，其他计划类型保持不变：

PUT _connector/my-connector/_scheduling
{
    "scheduling": {
        "full": {
            "enabled": true,
            "interval": "0 10 0 * * ?"
        }
    }
}

{
    "result": "updated"
}

更新连接器服务类型 API

edit

更新连接器的service_type。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_service_type

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。
The service_type 必须是连接器框架定义的有效类型。
- 当您更改已配置连接器的 service_type 时，您还需要重置其配置以确保兼容性。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

service_type: (必需，字符串) 在 Connector framework 中定义的连接器服务类型。

响应代码

edit

200: 连接器 service_type 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的service_type：

PUT _connector/my-connector/_service_type
{
    "service_type": "sharepoint_online"
}

{
    "result": "updated"
}

创建连接器同步作业 API

edit

创建一个连接器同步作业。

要开始使用连接器API，请查看我们的教程。

POST _connector/_sync_job
{
  "id": "connector-id",
  "job_type": "full",
  "trigger_method": "on_demand"
}

请求

edit

POST _connector/_sync_job

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。
id 参数应引用现有连接器。

描述

edit

在内部索引中创建一个连接器同步作业文档，并使用默认值初始化其计数器和时间戳。某些值可以通过API进行更新。

请求体

edit

id: (必需，字符串) 要为其创建同步作业的连接器的ID。
job_type: (可选，字符串) 创建的同步作业的作业类型。默认为 full。
trigger_method: (可选，字符串) 创建的同步作业的触发方式。默认为 on_demand。

响应体

edit

id: (字符串) 与连接器同步作业文档关联的ID。

响应代码

edit

201: 表示连接器同步作业已成功创建。
400: 表示请求格式不正确。
404: 表示索引或引用的连接器缺失。

取消连接器同步作业 API

edit

取消连接器同步作业。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector/_sync_job//_cancel

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_sync_job_id 参数应引用现有的连接器同步作业。

描述

edit

取消连接器同步作业，将status设置为cancelling，并将cancellation_requested_at更新为当前时间。连接器服务随后负责将连接器同步作业的status设置为cancelled。

路径参数

edit

connector_sync_job_id: （必需，字符串）

响应代码

edit

200: 连接器同步作业取消请求已成功提交。
404: 未找到与 connector_sync_job_id 匹配的连接器同步任务。

示例

edit

以下示例取消ID为my-connector-sync-job-id的连接器同步作业：

PUT _connector/_sync_job/my-connector-sync-job-id/_cancel

删除连接器同步作业 API

edit

移除一个连接器同步任务及其关联数据。这是一个不可恢复的破坏性操作。

要开始使用连接器API，请查看我们的教程。

请求

edit

DELETE _connector/_sync_job/

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。

路径参数

edit

<connector_sync_job_id>: （必需，字符串）

响应代码

edit

400: 未提供connector_sync_job_id。
404: 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例删除了ID为 my-connector-sync-job-id 的连接器同步作业：

DELETE _connector/_sync_job/my-connector-sync-job-id

{
    "acknowledged": true
}

获取连接器同步作业 API

edit

检索有关连接器同步作业的详细信息。

要开始使用连接器API，请查看我们的教程。

请求

edit

GET _connector/_sync_job/

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。

路径参数

edit

<connector_sync_job_id>: （必需，字符串）

响应代码

edit

400: 未提供connector_sync_job_id。
404 (Missing resources): 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例获取连接器同步作业 my-connector-sync-job：

GET _connector/_sync_job/my-connector-sync-job

列出连接器同步作业 API

edit

返回按创建日期升序排列的所有存储连接器同步作业的信息。

要开始使用连接器API，请查看我们的教程。

请求

edit

GET _connector/_sync_job

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 托管连接器，此服务在 Elastic Cloud 上自动运行。

路径参数

edit

size: (可选，整数) 要检索的最大结果数。默认为 100。
from: (可选，整数) 从第一个结果开始获取的偏移量。默认为 0。
status: (可选，作业状态) 用于过滤结果的作业状态。可用状态包括：canceling（取消中）、canceled（已取消）、completed（已完成）、error（错误）、in_progress（进行中）、pending（待处理）、suspended（已暂停）。
connector_id: (可选，字符串) 获取的同步作业需要具有的连接器ID。
job_type: (可选，作业类型) 以逗号分隔的作业类型列表。可用的作业类型有：full、incremental 和 access_control。

示例

edit

以下示例列出了所有连接器同步作业：

GET _connector/_sync_job

以下示例列出了前两个连接器同步作业：

GET _connector/_sync_job?from=0&size=2

以下示例列出了待处理的连接器同步作业（默认情况下每页显示前100个）：

GET _connector/_sync_job?status=pending

以下示例列出了连接器同步作业（默认情况下为前100个），适用于ID为connector-1的连接器：

GET _connector/_sync_job?connector_id=connector-1

以下示例列出了连接器的同步作业（默认情况下为前100个），作业类型为full或incremental：

GET _connector/_sync_job?job_type=full,incremental

响应代码

edit

200: 表示结果已成功返回（结果也可能为空）。

400: 表示请求格式错误。

签到连接器 API

edit

更新连接器的 last_seen 字段为当前时间戳。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_check_in

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

响应代码

edit

200: 连接器 last_seen 字段已成功更新为当前时间戳。
400: 未提供connector_id。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新ID为my-connector的连接器的last_seen属性为当前时间戳：

PUT _connector/my-connector/_check_in

{
    "result": "updated"
}

更新连接器错误 API

edit

更新连接器的error字段。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_error

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

描述

edit

设置指定连接器的error字段。如果在请求体中提供的error是非空的，连接器的状态将更新为error。否则，如果error被重置为null，连接器的状态将更新为connected。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

error: (必需，字符串) 与连接器遇到的最后一个错误相关的消息。

响应代码

edit

200: 连接器 error 字段已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的error字段：

PUT _connector/my-connector/_error
{
    "error": "Houston, we have a problem!"
}

{
    "result": "updated"
}

更新连接器最后同步统计信息 API

edit

更新与连接器上次同步相关的字段。

此操作用于分析和监控。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_last_sync

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

last_access_control_sync_error: (可选，字符串) 与访问控制同步相关的最后错误消息（如果有）。
last_access_control_sync_scheduled_at: (可选, 日期时间) 指示上次访问控制同步计划时间的日期时间。
last_access_control_sync_status: (可选, ConnectorSyncStatus) 上次访问控制同步的状态。
last_deleted_document_count: (可选, 长整型) 在上一次同步过程中删除的文档数量。
last_incremental_sync_scheduled_at: (可选, 日期时间) 上次增量同步计划的时间。
last_indexed_document_count: (可选, 长整型) 在上一次同步中索引的文档数量。
last_sync_error: (可选，字符串) 如果在同步过程中遇到任何错误，显示的最后一条错误消息。
last_sync_scheduled_at: (可选, 日期时间) 上次同步计划的时间。
last_sync_status: (可选, ConnectorSyncStatus) 上次同步的状态。
last_synced: (可选, 日期时间) 最后一次成功同步的日期时间。

The value of ConnectorSyncStatus 是以下表示不同同步状态的小写字符串之一：

canceling: 同步过程正在被取消。
canceled: 同步过程已被取消。
completed: 同步过程已成功完成。
error: 同步过程中发生了错误。
in_progress: 同步过程正在进行中。
pending: 同步处于待定状态，尚未开始。
suspended: 同步过程已被暂时挂起。

响应代码

edit

200: 连接器上次同步统计信息已成功更新。
400: 未提供connector_id或请求负载格式不正确。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的最后同步统计信息：

PUT _connector/my-connector/_last_sync
{
    "last_access_control_sync_error": "Houston, we have a problem!",
    "last_access_control_sync_scheduled_at": "2023-11-09T15:13:08.231Z",
    "last_access_control_sync_status": "pending",
    "last_deleted_document_count": 42,
    "last_incremental_sync_scheduled_at": "2023-11-09T15:13:08.231Z",
    "last_indexed_document_count": 42,
    "last_sync_error": "Houston, we have a problem!",
    "last_sync_scheduled_at": "2024-11-09T15:13:08.231Z",
    "last_sync_status": "completed",
    "last_synced": "2024-11-09T15:13:08.231Z"
}

{
    "result": "updated"
}

更新连接器状态 API

edit

更新连接器的状态。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector//_status

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_id 参数应引用现有连接器。
status 的更改必须根据连接器协议进行有效的状态转换。

路径参数

edit

<connector_id>: （必需，字符串）

请求体

edit

status: (必需，字符串) 在连接器框架中定义的有效连接器状态字符串。

响应代码

edit

200: 连接器 status 字段已成功更新。
400: 未提供connector_id，请求负载格式错误，或给定的状态转换不受支持。
404 (Missing resources): 未找到与 connector_id 匹配的连接器。

示例

edit

以下示例更新了ID为my-connector的连接器的status：

PUT _connector/my-connector/_status
{
    "status": "needs_configuration"
}

{
    "result": "updated"
}

签到连接器同步作业 API

edit

检查连接器同步作业（将 last_seen 更新为当前时间）。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector/_sync_job//_check_in/

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_sync_job_id 参数应引用现有的连接器同步作业。

描述

edit

检查连接器同步作业，并将last_seen设置为在内部索引中更新之前的时间。

路径参数

edit

<connector_sync_job_id>: （必需，字符串）

响应代码

edit

200: 连接器同步作业已成功签入。
404: 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例检查连接器同步作业 my-connector-sync-job：

PUT _connector/_sync_job/my-connector-sync-job/_check_in

认领连接器同步作业 API

edit

声明一个连接器同步作业。

The _claim endpoint 不是为用户直接管理连接器而设计的。它的存在是为了支持使用 Connector Protocol 与 Elasticsearch 进行通信的服务的实现。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector/_sync_job//_claim

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_sync_job_id 参数应引用现有的连接器同步作业。

描述

edit

声明一个连接器同步作业。此操作将作业的状态更新为进行中，并将最后查看时间和开始时间时间戳设置为当前时间。此外，它还可以为同步作业设置同步游标属性。

路径参数

edit

connector_sync_job_id: （必需，字符串）

请求体

edit

worker_hostname: (必需，字符串) 将执行作业的当前系统的主机名。
sync_cursor: (可选, 对象) 上一次增量同步作业的光标对象。这应该引用执行作业的连接器状态中的 sync_cursor 字段。

响应代码

edit

200: 连接器同步任务已成功认领。
404: 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例声明了ID为 my-connector-sync-job-id 的连接器同步作业：

PUT _connector/_sync_job/my-connector-sync-job-id/_claim
{
  "worker_hostname": "some-machine"
}

设置连接器同步作业错误 API

edit

设置连接器同步作业错误。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector/_sync_job//_error

前提条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_sync_job_id 参数应引用现有的连接器同步作业。

描述

edit

为指定的连接器同步作业设置错误字段，并将其状态设置为错误。

路径参数

edit

<connector_sync_job_id>: （必需，字符串）

请求体

edit

error: (必需，字符串) 要设置连接器同步作业 error 字段的错误。

响应代码

edit

200: 表示连接器同步作业错误已成功设置。
404: 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例在连接器同步作业 my-connector-sync-job 中设置了错误 some-error：

PUT _connector/_sync_job/my-connector-sync-job/_error
{
    "error": "some-error"
}

设置连接器同步作业统计信息API

edit

设置连接器同步作业统计信息。

要开始使用连接器API，请查看我们的教程。

请求

edit

PUT _connector/_sync_job//_stats

先决条件

edit

要使用自管理连接器同步数据，您需要在自己的基础设施上部署Elastic 连接器服务。对于 Elastic 管理的连接器，此服务在 Elastic Cloud 上自动运行。
connector_sync_job_id 参数应引用现有的连接器同步作业。

描述

edit

设置连接器同步作业的统计信息。统计信息包括：deleted_document_count、indexed_document_count、indexed_document_volume 和 total_document_count。 last_seen 也可以使用此API进行更新。此API主要由连接器服务用于更新同步作业信息。

路径参数

edit

<connector_sync_job_id>: （必需，字符串）

请求体

edit

deleted_document_count: (必需，整数) 同步作业删除的文档数量。
indexed_document_count: (必需, 整数) 同步作业索引的文档数量。
indexed_document_volume: (必需，整数) 同步作业索引的数据总大小（以 MiB 为单位）。
total_document_count: (可选, 整数) 同步作业完成后目标索引中的文档总数。
last_seen: (可选，即时) 设置连接器同步作业的 last_seen 属性的时间戳。
metadata: (可选, 对象) 连接器特定的元数据。

响应代码

edit

200: 表示连接器同步作业统计信息已成功更新。
404: 未找到与 connector_sync_job_id 匹配的连接器同步作业。

示例

edit

以下示例为连接器同步作业 my-connector-sync-job 设置了所有必需和可选的统计信息：

PUT _connector/_sync_job/my-connector-sync-job/_stats
{
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
}

« Cross-cluster replication APIs Data stream APIs »