加载中

Elastic Salesforce 连接器参考

Elastic Salesforce 连接器 是一个用于 Salesforce 数据源的 连接器。

重要提示

从 Elastic 9.0 开始，Elastic Cloud Hosted 上的托管连接器不再可用。所有连接器必须自托管。

此连接器可作为自托管连接器使用。此自托管连接器兼容 Elastic 版本 8.10.0+。要使用此连接器，请满足所有 自托管连接器要求。

此连接器与以下版本兼容

  • Salesforce
  • Salesforce Sandbox

创建新的 Salesforce 连接器

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

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

例如

 PUT _connector/my-salesforce-connector {
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Salesforce",
  "service_type": "salesforce"
}
您还需要创建一个 API 密钥供连接器使用。
注意

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

为连接器创建 API 密钥

  1. 运行以下命令，替换指示的值。请注意响应中的 encoded 返回值。

     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 文档。

要将此连接器用作 自行管理连接器，请使用 Kibana UI 中的 Connector 工作流。

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

注意

您需要创建一个启用了 OAuth2.0 的 Salesforce 连接应用程序才能使用 Salesforce 进行身份验证。

Salesforce 连接器通过一个连接应用程序来与 Salesforce 进行身份验证。请遵循 Salesforce 官方文档 配置连接应用程序以进行 OAuth 2.0 客户端凭据流。

创建连接应用程序时，在API (启用 OAuth 设置) 部分，请确保以下设置已启用

  • 启用 OAuth 设置

  • 为设备流启用

    • 回调 URL 应为 Salesforce 虚拟回调 URL，https://test.salesforce.com/services/oauth2/success

  • 需要 Web 服务器流的密钥

  • 需要刷新令牌流的密钥

  • 启用客户端凭据流

所有其他选项都应禁用。最后，在选定的 OAuth 范围部分，包括以下 OAuth 范围

  • 通过 API 管理用户数据 (api)
  • 随时执行请求 (refresh_token, offline_access)

默认情况下，Salesforce 连接器需要全局管理员权限才能访问 Salesforce 数据。展开下面的部分，了解如何创建具有最少权限的自定义 Salesforce 用户。

创建具有最少权限的自定义 Salesforce 用户

通过从“设置”菜单创建具有足够权限的自定义配置文件，您可以消除从 Salesforce 获取数据的系统管理员角色要求。

创建新配置文件

  1. 从 Salesforce“设置”菜单，转到管理 ⇒ 用户 ⇒ 配置文件。

  2. 创建新配置文件。

  3. 从现有配置文件下拉菜单中选择 只读 或 标准用户。为配置文件命名并保存。

    提示

    默认情况下，只读 或 标准用户 用户对所有标准对象都具有读取权限。

  4. 编辑新创建的配置文件。在对象权限下，至少为要摄取到 Elasticsearch 的标准对象和自定义对象分配读取访问权限。

  5. 确保新创建的配置文件至少对以下标准对象具有读取访问权限

    • Account

    • Campaign

    • Case

    • Contact

    • EmailMessage

    • Lead

    • Opportunity

    • 用户

      提示

      如果您使用 高级同步规则，您需要在配置文件中为该特定对象分配读取访问权限。

  6. 转到用户 ⇒ 配置文件，并将新创建的配置文件分配给用户。

  7. 转到连接应用程序，选择您的应用程序，然后选择编辑策略。在 Salesforce 中，将客户端凭据流分配给具有自定义配置文件的用户。

    现在，可以为此用户配置文件配置连接器以获取所有对象记录，而无需系统管理员角色。

自托管连接器在您自己的基础设施上运行。

您可以使用 Docker 将 Salesforce 连接器部署为自托管连接器。请遵循这些说明。

步骤 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

如果您运行连接器服务连接到 Dockerized 版本的 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: salesforce
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA>
  1. 可选。如果未提供，连接器将改用 elasticsearch.api_key。

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

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

步骤 3：运行 Docker 镜像

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

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

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

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

提示

我们还提供了一个使用 Docker Compose 的快速入门自托管选项，这样您可以一次性启动所有必需的服务：Elasticsearch、Kibana 和连接器服务。有关更多信息，请参阅 elastic/connectors 仓库中的此README。

设置此连接器需要以下设置

domain (必需)
您 Salesforce 帐户的域名。这是出现在您的 Salesforce URL 中的子域名。例如，如果您的 Salesforce URL 是 foo.my.salesforce.com，则您的域名将是 foo。如果您使用的是 Salesforce Sandbox，您的 URL 将包含额外的子域名，看起来类似于 foo.sandbox.my.salesforce.com。在这种情况下，您的域名将是 foo.sandbox。
client_id (必需)
由您的连接应用程序生成的客户端 ID。Salesforce 文档有时也将其称为消费者密钥。
client_secret (必需)
由您的连接应用程序生成的客户端密钥。Salesforce 文档有时也将其称为消费者密钥。
use_document_level_security

切换以启用文档级别安全性 (DLS)。可选，默认禁用。有关更多信息，包括如何设置各种 Salesforce 权限类型，请参阅 DLS 部分。

启用时

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

创建连接应用程序后，客户端 ID 和客户端密钥不会自动显示给您。您可以通过执行以下步骤找到它们

  • 导航到设置
  • 转到平台工具 > 应用程序 > 应用程序管理器
  • 单击应用程序旁边的三角形，然后选择查看
  • 页面加载后，单击管理消费者详细信息

您的客户端 ID 和客户端密钥现在应该显示在页面顶部。

文档级别安全性 (DLS) 使您能够根据用户的权限限制对文档的访问。此功能默认可用于 Salesforce 连接器，并支持标准和自定义对象。

Salesforce 允许用户通过以下方式设置权限

  • 配置文件
  • 权限集
  • 权限集组

有关指导，请参阅这些关于设置 Salesforce 权限的 视频教程。

要摄取任何标准或自定义对象，用户必须确保至少授予该对象的 读取 权限。这可以通过以下任何一种权限设置方法来授予。

有关通过配置文件设置权限的信息，请参阅 Salesforce 文档。

有关通过权限集设置权限的信息，请参阅 Salesforce 文档。

有关通过权限集组设置权限的信息，请参阅 Salesforce 文档。

设置好权限后，将配置文件、权限集或权限集组分配给用户。请在 Salesforce 中按照以下步骤操作

  1. 在用户部分下导航到管理。
  2. 选择用户并选择要设置权限的用户。
  3. 设置在先前步骤中创建的配置文件、权限集或权限集组。

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

有关更多信息，请阅读 同步规则。

注意

要使高级同步规则生效，需要进行完整同步。

以下部分描述了此连接器的高级同步规则。高级同步规则允许在将数据索引到 Elasticsearch 之前在 Salesforce 中进行筛选。

它们采用以下参数

  1. query：用于筛选文档的 Salesforce 查询。
  2. language：Salesforce 查询语言。允许的值为SOQL 和SOSL。

根据指定的查询和语言获取文档

示例：使用 SOQL 查询获取文档

[
  {
    "query": "SELECT Id, Name FROM Account",
    "language": "SOQL"
  }
]

示例：使用 SOSL 查询获取文档。

[
  {
    "query": "FIND {Salesforce} IN ALL FIELDS",
    "language": "SOSL"
  }
]

使用 SOQL 和 SOSL 查询获取标准和自定义对象

示例：通过 SOQL 和 SOSL 查询获取标准对象的文档。

[
  {
    "query": "SELECT Account_Id, Address, Contact_Number FROM Account",
    "language": "SOQL"
  },
  {
    "query": "FIND {Alex Wilber} IN ALL FIELDS RETURNING Contact(LastModifiedDate, Name, Address)",
    "language": "SOSL"
  }
]

示例：通过 SOQL 和 SOSL 查询获取自定义对象的文档。

[
  {
    "query": "SELECT Connector_Name, Version FROM Connector__c",
    "language": "SOQL"
  },
  {
    "query": "FIND {Salesforce} IN ALL FIELDS RETURNING Connectors__c(Id, Connector_Name, Connector_Version)",
    "language": "SOSL"
  }
]

获取具有标准和自定义字段的文档

示例：获取 Account 对象的所有标准和自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(ALL) FROM Account",
    "language": "SOQL"
  }
]

示例：获取 Connector 对象的所有自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(CUSTOM) FROM Connector__c",
    "language": "SOQL"
  }
]

示例：获取 Account 对象的所有标准字段的文档。

[
  {
    "query": "SELECT FIELDS(STANDARD) FROM Account",
    "language": "SOQL"
  }
]

连接器同步以下 Salesforce 对象

  • Accounts
  • Campaigns
  • 案例
  • Contacts
  • Content Documents (上传到 Salesforce 的文件)
  • Leads
  • Opportunities

连接器不会摄取它没有权限查询的任何对象。

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

所有连接器默认支持完整同步。

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

内容提取

连接器将从您的 Salesforce 源检索 Content Documents，如果它们符合以下标准

  • 已附加到已同步的一个或多个对象
  • 文件类型可提取

这意味着连接器不会摄取您拥有的任何未附加到受支持的 Salesforce 对象的 Content Documents。有关支持的对象类型列表，请参阅 文档和同步。

如果单个 Content Document 附加到多个支持的对象，则只会为其创建一个 Elastic 文档。此文档将在 related_ids 字段中保留指向其连接的每个对象的链接。

有关内容提取的更多详细信息，请参阅 内容提取。

  • DLS 功能是“类型级别”而非“文档级别”

    Salesforce DLS（在 8.13.0 中添加）不适应对特定 Salesforce 对象进行访问控制。相反，如果给定用户/组可以访问任何给定类型的对象（Case、Lead、Opportunity 等），那么该用户/组将出现在该类型所有对象的 \_allow_access_control 列表中。有关更多详细信息，请参阅 https://github.com/elastic/connectors/issues/3028。

  • 仅摄取前 500 个嵌套实体

    Salesforce 连接器获取的一些实体是嵌套的——它们通过 JOIN 查询与父对象一起被摄取。这些实体的示例包括 EmailMessages、CaseComments 和 FeedComments。当 Salesforce 连接器获取这些实体时，它会将每个父对象的摄取实体数限制为最多 500 个。目前唯一的解决方法是 fork Connectors 存储库并修改 Salesforce 连接器中的代码以增加这些限制。

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

请参阅 连接器安全性。

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

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

© . This site is unofficial and not affiliated with Elasticsearch BV.