« Elastic 网络驱动器连接器参考 Elastic OneDrive 连接器参考 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›使用 Elastic 连接器提取内容 ›连接器参考

Elastic Notion 连接器参考

编辑

Elastic Notion 连接器参考

编辑

Notion 连接器使用 Python 编写，并使用了 Elastic 连接器框架。查看此连接器的源代码（分支 8.17，与 Elastic 8.17 兼容）。

Elastic 托管连接器参考

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

此托管连接器在 Elastic 8.14.0 中作为 Elastic Cloud 上的托管服务引入。

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

此连接器为 beta 版本，可能会发生更改。其设计和代码不如正式 GA 版本成熟，按原样提供，不提供任何保证。Beta 功能不受正式 GA 功能的支持 SLA 约束。

用法
编辑

要在 UI 中使用此连接器，请在 搜索 → 连接器 下创建新连接器时选择 Notion 图块。

如果您已经熟悉连接器的工作方式，也可以使用连接器 API。

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

创建 Notion 连接器
编辑

使用 UI

编辑

要创建新的 Notion 连接器

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

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

使用 API

编辑

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

例如

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-notion-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Notion",
  "service_type": "notion",
  "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 文档。

连接到 Notion
编辑

要连接到 Notion，用户需要为其 Notion 工作区创建一个内部集成，该集成可以使用内部集成密钥令牌访问资源。使用以下设置配置集成

  1. 用户必须在“功能”选项卡中为该集成授予内容、评论和用户功能的 READ 权限。
  2. 用户必须手动将集成添加为连接到工作区中的顶级页面。子页面将自动继承父页面的连接。
配置
编辑

请注意以下配置字段

Notion 密钥（必需）

分配给您的集成（针对特定工作区）的密钥令牌。示例

  • zyx-123453-12a2-100a-1123-93fd09d67394
数据库（必需）

连接器要提取的数据库名称的逗号分隔列表。如果值为 *，则连接器将提取工作区中所有可用的数据库。示例

  • database1, database2
  • *
页面（必需）

连接器要提取的页面名称的逗号分隔列表。如果值为 *，则连接器将提取工作区中所有可用的页面。示例

  • *
  • Page1, Page2
索引评论
切换以启用从 Notion 工作区为配置的页面、数据库和相应的子块提取和索引评论。默认值为 False。

启用评论索引可能会因网络调用增加而影响连接器性能。因此，默认情况下，此值为 False。

内容提取
编辑

请参阅内容提取。

文档和同步
编辑

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

  • 页面

    • 包括 页面名称、id、上次更新时间 等元数据。

  • 块

    • 包括 标题、类型、id、内容（对于文件块）等元数据。

  • 数据库

    • 包括 名称、id、记录、大小 等元数据。

  • 用户

    • 包括 名称、id、电子邮件地址 等元数据。

  • 评论

    • 包括内容和 id、上次更新时间、创建者 等元数据。
    • 注意：默认情况下排除评论。
  • 大于 10 MB 的文件将不会被提取。
  • 权限未同步。所有 索引到 Elastic 部署的文档对于所有可以访问相关 Elasticsearch 索引的用户可见。
同步规则
编辑

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

高级同步规则
编辑

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

以下部分介绍了此连接器的 高级同步规则，以便在索引到 Elasticsearch 之前 过滤 Notion 中的数据。高级同步规则通过特定于源的 DSL JSON 片段定义。

Notion 的高级同步规则采用以下参数

  1. searches：Notion 的搜索过滤器，按标题搜索。
  2. query：Notion 的数据库查询过滤器，用于提取特定数据库。
示例
编辑

示例 1

索引标题包含 Demo Page 的每个页面

  {
    "searches": [
      {
        "filter": {
          "value": "page"
        },
        "query": "Demo Page"
      }
    ]
  }

示例 2

索引标题包含 Demo Database 的每个数据库

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    }
  ]
}

示例 3

索引标题包含 Demo Database 的每个数据库以及标题包含 Demo Page 的每个页面

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    },
    {
      "filter": {
        "value": "page"
      },
      "query": "Demo Page"
    }
  ]
}

示例 4

索引工作区中的所有页面

{
  "searches": [
    {
      "filter": {
        "value": "page"
      },
      "query": ""
    }
  ]
}

示例 5

索引连接到工作区的所有页面和数据库

{
  "searches":[
    {
      "query":""
    }
  ]
}

示例 6

索引数据库的所有行，其中 Task completed 列的记录为 true，且其属性（数据类型）为复选框

{
  "database_query_filters": [
    {
      "filter": {
          "property": "Task completed",
          "checkbox": {
            "equals": true
          }
      },
      "database_id": "database_id"
    }
  ]
}

示例 7

索引特定数据库的所有行

{
  "database_query_filters": [
    {
      "database_id": "database_id"
    }
  ]
}

示例 8

索引在 searches 和 database_query_filters 中定义的所有块

{
  "searches":[
    {
      "query":"External tasks",
      "filter":{
        "value":"database"
      }
    },
    {
      "query":"External tasks",
      "filter":{
        "value":"page"
      }
    }
  ],
  "database_query_filters":[
    {
      "database_id":"notion_database_id1",
      "filter":{
        "property":"Task completed",
        "checkbox":{
          "equals":true
        }
      }
    }
  ]
}

在此示例中，database_query_filters 的 filter 对象语法是根据Notion 文档定义的。

已知问题
编辑

  • 对新页面的更新可能不会立即反映在 Notion API 中。

    如果在添加页面后立即启动同步，则这可能会导致这些页面未被连接器索引。为了确保所有页面都被索引，请在向 Notion 添加页面后几分钟启动同步。

  • Notion 的公共 API 不支持链接数据库。

    Notion 中的链接数据库是可以进行筛选、排序和不同查看的数据库副本。要提取链接数据库中的信息，您需要定位原始 源 数据库。有关更多详细信息，请参阅Notion 文档。

  • 文档的 properties 对象在 details 下序列化为字符串.

    Notion 的 properties 架构不一致，如果作为对象索引到 Elasticsearch，可能会导致 document_parsing_exceptions。因此，properties 对象将序列化为 JSON 字符串，并存储在 details 字段下。如果您需要从 properties 中搜索子对象，您可能需要在提取管道中对 details 字段进行后处理，以提取所需的子字段。

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

故障排除
编辑

请参阅故障排除。

安全性
编辑

请参阅安全性。

自管理连接器参考

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

此连接器在 Elastic 8.13.0 版本中引入，作为 自管理 连接器提供。

要使用此连接器，请满足所有自管理连接器先决条件。重要的是，您必须在自己的基础设施上部署连接器服务。您有两种部署选项：

此连接器为 beta 版本，可能会发生更改。其设计和代码不如正式 GA 版本成熟，按原样提供，不提供任何保证。Beta 功能不受正式 GA 功能的支持 SLA 约束。

用法
编辑

要在 UI 中使用此连接器，请在 搜索 → 连接器 下创建新连接器时选择 Notion 图块。

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

创建 Notion 连接器
编辑

使用用户界面

编辑

要创建新的 Notion 连接器

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

使用 API

编辑

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

例如

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-notion-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Notion",
  "service_type": "notion"
}
您还需要为连接器创建一个 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 文档。

连接到 Notion
编辑

要连接到 Notion，用户需要为其 Notion 工作区创建一个内部集成，该集成可以使用内部集成密钥令牌访问资源。使用以下设置配置集成

  1. 用户必须在“功能”选项卡中为该集成授予内容、评论和用户功能的 READ 权限。
  2. 用户必须手动将集成添加为连接到工作区中的顶级页面。子页面将自动继承父页面的连接。
使用 Docker 部署
编辑

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

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

配置
编辑

请注意以下配置字段

Notion 密钥（必需）

分配给您的集成（针对特定工作区）的密钥令牌。示例

  • zyx-123453-12a2-100a-1123-93fd09d67394
数据库（必需）

连接器要提取的数据库名称的逗号分隔列表。如果值为 *，则连接器将提取工作区中所有可用的数据库。示例

  • database1, database2
  • *
页面（必需）

连接器要提取的页面名称的逗号分隔列表。如果值为 *，则连接器将提取工作区中所有可用的页面。示例

  • *
  • Page1, Page2
索引评论
切换以启用从 Notion 工作区为配置的页面、数据库和相应的子块提取和索引评论。默认值为 False。

启用评论索引可能会因网络调用增加而影响连接器性能。因此，默认情况下，此值为 False。

内容提取
编辑

请参阅内容提取。

文档和同步
编辑

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

  • 页面

    • 包括 页面名称、id、上次更新时间 等元数据。

  • 块

    • 包括 标题、类型、id、内容（对于文件块）等元数据。

  • 数据库

    • 包括 名称、id、记录、大小 等元数据。

  • 用户

    • 包括 名称、id、电子邮件地址 等元数据。

  • 评论

    • 包括内容和 id、上次更新时间、创建者 等元数据。
    • 注意：默认情况下排除评论。
  • 大于 10 MB 的文件将不会被提取。
  • 权限未同步。所有 索引到 Elastic 部署的文档对于所有可以访问相关 Elasticsearch 索引的用户可见。
同步规则
编辑

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

高级同步规则
编辑

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

以下部分介绍了此连接器的 高级同步规则，以便在索引到 Elasticsearch 之前 过滤 Notion 中的数据。高级同步规则通过特定于源的 DSL JSON 片段定义。

Notion 的高级同步规则采用以下参数

  1. searches：Notion 的搜索过滤器，按标题搜索。
  2. query：Notion 的数据库查询过滤器，用于提取特定数据库。
示例
编辑

示例 1

索引标题包含 Demo Page 的每个页面

  {
    "searches": [
      {
        "filter": {
          "value": "page"
        },
        "query": "Demo Page"
      }
    ]
  }

示例 2

索引标题包含 Demo Database 的每个数据库

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    }
  ]
}

示例 3

索引标题包含 Demo Database 的每个数据库以及标题包含 Demo Page 的每个页面

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    },
    {
      "filter": {
        "value": "page"
      },
      "query": "Demo Page"
    }
  ]
}

示例 4

索引工作区中的所有页面

{
  "searches": [
    {
      "filter": {
        "value": "page"
      },
      "query": ""
    }
  ]
}

示例 5

索引连接到工作区的所有页面和数据库

{
  "searches":[
    {
      "query":""
    }
  ]
}

示例 6

索引数据库的所有行，其中 Task completed 列的记录为 true，且其属性（数据类型）为复选框

{
  "database_query_filters": [
    {
      "filter": {
          "property": "Task completed",
          "checkbox": {
            "equals": true
          }
      },
      "database_id": "database_id"
    }
  ]
}

示例 7

索引特定数据库的所有行

{
  "database_query_filters": [
    {
      "database_id": "database_id"
    }
  ]
}

示例 8

索引在 searches 和 database_query_filters 中定义的所有块

{
  "searches":[
    {
      "query":"External tasks",
      "filter":{
        "value":"database"
      }
    },
    {
      "query":"External tasks",
      "filter":{
        "value":"page"
      }
    }
  ],
  "database_query_filters":[
    {
      "database_id":"notion_database_id1",
      "filter":{
        "property":"Task completed",
        "checkbox":{
          "equals":true
        }
      }
    }
  ]
}

在此示例中，database_query_filters 的 filter 对象语法是根据Notion 文档定义的。

连接器客户端操作
编辑
端到端测试
编辑

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 Notion 源即可运行此测试。

有关更多详细信息，请参阅连接器测试。

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

$ make ftest NAME=notion

要进行更快的测试，请添加 DATA_SIZE=small 标志

make ftest NAME=notion DATA_SIZE=small

默认情况下，DATA_SIZE=MEDIUM。

已知问题
编辑

  • 对新页面的更新可能不会立即反映在 Notion API 中。

    如果在添加页面后立即启动同步，则这可能会导致这些页面未被连接器索引。为了确保所有页面都被索引，请在向 Notion 添加页面后几分钟启动同步。

  • Notion 的公共 API 不支持链接数据库。

    Notion 中的链接数据库是可以进行筛选、排序和不同查看的数据库副本。要提取链接数据库中的信息，您需要定位原始 源 数据库。有关更多详细信息，请参阅Notion 文档。

  • 文档的 properties 对象在 details 下序列化为字符串.

    Notion 的 properties 架构不一致，如果作为对象索引到 Elasticsearch，可能会导致 document_parsing_exceptions。因此，properties 对象将序列化为 JSON 字符串，并存储在 details 字段下。如果您需要从 properties 中搜索子对象，您可能需要在提取管道中对 details 字段进行后处理，以提取所需的子字段。

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

故障排除
编辑

请参阅故障排除。

安全
编辑

请参阅安全性。

« Elastic 网络驱动器连接器参考 Elastic OneDrive 连接器参考 »