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-gmail-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Gmail",
  "service_type": "gmail",
  "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 中将此连接器用作托管连接器，请使用 Kibana UI 中的连接器工作流程。

要创建新的 Gmail 连接器

在 Kibana UI 中导航到搜索 → 连接器页面。
选择新建原生连接器按钮。
选择Gmail连接器。

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

连接器身份验证先决条件

编辑

在从 GMail 同步任何数据之前，您需要创建一个具有对 GMail 和 Google Directory API（这是 Google Admin SDK API 的一部分）的适当访问权限的服务帐户。您还需要启用域范围内的委派，以模拟您从中获取消息的用户。

要开始使用，请登录Google Cloud Platform并转到控制台。

创建 Google Cloud 项目。为您的项目命名，更改项目 ID，然后单击“创建”按钮。
启用 Google API。从左侧菜单中选择“API 和服务”，然后单击启用 API 和服务。您需要启用GMail API和Google Admin SDK API。
创建服务帐户。在API 和服务部分，单击凭据，然后单击创建凭据以创建服务帐户。为您的服务帐户命名并提供一个服务帐户 ID。这就像一个电子邮件地址，将来将用于识别您的服务帐户。单击完成以完成创建服务帐户。

您的服务帐户需要至少具有以下范围的访问权限
- https://www.googleapis.com/auth/gmail.readonly
创建密钥文件.
- 在 Cloud Console 中，转到IAM 和管理 > 服务帐户页面。
- 单击要为其创建密钥的服务帐户的电子邮件地址。
- 单击密钥选项卡。单击添加密钥下拉菜单，然后选择创建新密钥。
- 选择 JSON 作为密钥类型，然后单击创建。这将下载一个包含服务帐户凭据的 JSON 文件。
Google Workspace 域范围内的授权委派.

要访问 Google Workspace 域中的用户数据（如消息），您创建的服务帐户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围内的授权委派。

您需要向您的服务帐户授予以下OAuth 范围
- https://www.googleapis.com/auth/admin.directory.user.readonly
此步骤允许连接器访问您 Google Workspace 组织中的用户数据及其组成员身份。

配置

编辑

以下配置字段是必需的

GMail 服务帐户 JSON

从 Google Cloud Platform 生成的服务帐户凭据（JSON 字符串）。有关详细信息，请参阅Google Cloud 文档。

Google Workspace 管理员电子邮件

Google Workspace 管理员电子邮件。启用文档级安全 (DLS) 所必需。具有委派权限的服务帐户可以模拟具有访问 Google Workspace 用户数据及其组成员身份权限的管理员用户。有关详细信息，请参阅Google Cloud 文档。

Google 客户 ID

Google 客户 ID。提取消息和启用文档级安全 (DLS) 所必需。转到Google Workspace 管理控制台 → 帐户，然后复制客户 ID下的值。

包括垃圾邮件和已删除邮件

切换以提取垃圾邮件和已删除邮件。也适用于文档级安全 (DLS)。

启用文档级安全

切换以启用文档级安全 (DLS)。GMail 连接器支持 DLS。启用后

完全同步将提取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。
访问控制同步将提取用户的访问控制列表，并将其存储在单独的索引中。

文档和同步

编辑

连接器将提取服务帐户有权访问的所有用户的全部消息。

同步类型

编辑

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

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

同步规则

编辑

所有连接器的基本同步规则都相同，并且默认情况下可用。

此连接器可以使用高级同步规则。连接器在 messages 字段下支持GMail 高级搜索语法。

例如

{
  "messages": [
    "before:2021/10/10",
    "from:amy"
  ]
}

文档级安全

编辑

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

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

已知问题

编辑

此连接器目前没有已知问题。

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

框架和源

编辑

此连接器是使用Elastic 连接器框架用 Python 构建的。

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

自管理连接器参考

编辑

查看自管理连接器参考

可用性和先决条件

编辑

此连接器作为来自Elastic 连接器框架的自管理自管理连接器提供。

此自管理连接器与 Elastic 版本 8.10.0+ 兼容。

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

创建 Gmail 连接器

编辑

使用 UI

编辑

要创建新的 Gmail 连接器

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

使用 API

编辑

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

例如

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

您还需要为连接器创建 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 中的 连接器 工作流程。

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

连接器身份验证先决条件

编辑

要开始使用，请登录Google Cloud Platform并转到控制台。

创建 Google Cloud 项目。为您的项目命名，更改项目 ID，然后单击“创建”按钮。
启用 Google API。从左侧菜单中选择“API 和服务”，然后单击启用 API 和服务。您需要启用GMail API和Google Admin SDK API。
创建服务帐户。在API 和服务部分，单击凭据，然后单击创建凭据以创建服务帐户。为您的服务帐户命名并提供一个服务帐户 ID。这就像一个电子邮件地址，将来将用于识别您的服务帐户。单击完成以完成创建服务帐户。

您的服务帐户需要至少具有以下范围的访问权限
- https://www.googleapis.com/auth/gmail.readonly
创建密钥文件.
- 在 Cloud Console 中，转到IAM 和管理 > 服务帐户页面。
- 单击要为其创建密钥的服务帐户的电子邮件地址。
- 单击密钥选项卡。单击添加密钥下拉菜单，然后选择创建新密钥。
- 选择 JSON 作为密钥类型，然后单击创建。这将下载一个包含服务帐户凭据的 JSON 文件。
Google Workspace 域范围内的授权委派.

要访问 Google Workspace 域中的用户数据（如消息），您创建的服务帐户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围内的授权委派。

您需要向您的服务帐户授予以下OAuth 范围
- https://www.googleapis.com/auth/admin.directory.user.readonly
此步骤允许连接器访问您 Google Workspace 组织中的用户数据及其组成员身份。

配置

编辑

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

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

以下配置字段是必需的

GMail 服务帐户 JSON

从 Google Cloud Platform 生成的服务帐户凭据（JSON 字符串）。有关详细信息，请参阅Google Cloud 文档。

Google Workspace 管理员电子邮件

Google 客户 ID

Google 客户 ID。提取消息和启用文档级安全 (DLS) 所必需。转到Google Workspace 管理控制台 → 帐户，然后复制客户 ID下的值。

包括垃圾邮件和已删除邮件

切换以获取垃圾邮件和已删除邮件。也适用于 DLS。

启用文档级安全

切换以启用文档级安全 (DLS)。GMail 连接器支持 DLS。启用后

完全同步将提取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。
访问控制同步将提取用户的访问控制列表，并将其存储在单独的索引中。

使用 Docker 部署

编辑

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

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

文档和同步

编辑

连接器将提取服务帐户有权访问的所有用户的全部消息。

同步类型

编辑

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

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

同步规则

编辑

所有连接器的基本同步规则都相同，并且默认情况下可用。

此连接器可以使用高级同步规则。连接器在 messages 字段下支持GMail 高级搜索语法。

例如

{
  "messages": [
    "before:2021/10/10",
    "from:amy"
  ]
}

文档级安全性

编辑

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

已知问题

编辑

此连接器目前没有已知问题。

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

框架和源代码

编辑

此连接器是使用Elastic 连接器框架用 Python 构建的。

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

« Elastic GitHub 连接器参考 Google Cloud Storage 连接器 »