Enterprise：如何将自定义数据导入 Elastic Workplace Search - 一个简单的CSV示例

Elastic Workplace Search 可以立即从各种内容源（例如 Google Drive，GitHub 和 Salesforce）中提取数据。 但是您可能需要额外的灵活性来满足您自己独特的组织数据需求。

Workplace Search 自定义源 API 提供了一种轻量级的，由 API 驱动的方式，用于将内容提取到 Workplace Search 中。 此灵活的工具可帮助你防止自定义内容被孤立，并使其完全显示在 Workplace Search 搜索结果中，就好像它源自现成的内容源集成一样。

如果你还对 Elastic 的 Workplace Search 还不是很了解的话，请阅读我之前的文章：

          - Solutions：Elastic workplace 搜索：随时随地搜索所有内容 （一）

          - Solutions：Elastic workplace 搜索：随时随地搜索所有内容 （二）

通过这两篇文章的学习，你将对 Elastic Workplace Search 有一个比较清楚的理解，并可以正确地安装好 Workplace Search。

 

定制源到底是什么？

定制源以企业级源为目标，在这种情况下，数据源的内容适合向许多 Workplace Search 用户公开。定制源通常由系统管理员最初配置，然后由系统管理员为开发提供 API 凭据，以将内容推送到 Workplace Search。这些凭据以及提供的身份验证可标识源本身，以确保任何推送的数据都出现在适当的自定义源中。

因此，定制源通常包含来自存储库的内容，以及与组织中许多个人相关的有用信息。一个简单的示例可能是联系人的 CSV 文件。一个复杂的示例可能是自定义存储库，例如 Trello。在解决 Trello 的后续问题之前，我们将在这里讨论其中的简单问题。

添加自定义源需要使用 REST API。这涉及一些编码，我们选择在此处根据需要在 Python 中实现。尽管不需要任何 Python 技能，但也欢迎更多技术的读者实际使用。

 

从简单开始

企业数据通常位于托管存储库中，但是你可能仍然具有文件格式（例如 CSV）的旧数据。 这个例子虽然有些有意为之，但可以让我们在解决更复杂的用例之前，通过简单的教程来学习自定义资源。

在 Workplace 搜索结果中公开联系信息可能会缩短用户查找同事或客户详细信息所需的时间。 在这里，我们假设这些联系人以 CSV 的形式存在。 随意使用我们的数据集或生成自己的数据集。在本例程中所使用的文档是这样的：

当我们在 Workplace Search 中创建自定义源时，我们有效地为内容创建了一个单独的容器。 该内容将具有唯一的架构及其自己的相关性模型。 配置完成后，源将像其他任何文档存储库一样暴露于结果中，并获得所有相关的好处，例如按组对相关性进行优先级排序。

 

在 Workplace Search 中创建 Custom API 源

如果你还没有安装好自己的 Workplace Search，请参阅我之前的文章  Solutions：Elastic workplace 搜索：随时随地搜索所有内容 （一）。在那篇文章中，有详细的介绍如何安装 Workplace Search。

我们打开 Workplace Search 的地址，并登陆进去：

点击 Log In:

点击 Launch Workplace Search:

点击 Add  sources:

点击 Custom API Source:

输入 customer_contacts 作为源的名字，并点击 Create Custom API Source 按钮：

在上面显示了 Access Token 及 Key。Access Token 提供身份验证，而 Key 唯一地标识定制源。 我们分别把这两个字符串记录下来，并在以下的练习中使用。

 

使用 Workplace Search API

Workplace Search 提供了一个直观的 REST API，用于将内容提取到自定义源。 在我们的情况下，我们只需要将联系人发送到_bulk_create 端点。 为简单起见，我们将 CSV 中的行数限制为 100，因为这意味着我们可以在单个请求中发送所有联系人。 如果用户拥有更多数据或需要更多的索引弹性，建议你使用你所喜欢的语言之一（例如Python）。

 

快速查看请求接口

在开始发送数据之前，让我们快速看一下 Workplace Search 请求本身：

POST http://localhost:3002/api/ws/v1/sources/[KEY]/documents/bulk_create

我们需要向 Workplace Search URL 发出 HTTP POST。 此处的操作由 url 后缀 document/bulk_create 指出。 这里的 [KEY] 是你上面指出的值，它唯一地标识了我们的新来源。 要添加到此源的文档以 JSON 形式在主体有效负载中发送。 另外，我们需要设置两个 http header：一个包含上述 token（带有 Bearer 前缀）的授权 header ，以及一个指示 POST 正文包含 JSON 的 Content-Type。 假设我们使用 curl，这将导致以下请求结构：

curl -X POST http://localhost:3002/api/ws/v1/sources/[KEY]/documents/bulk_create \-H "Authorization: Bearer [AUTH_TOKEN]" \-H "Content-Type: application/json" \-d '[ 
{ 
    "id" : 1, 
    "first_name" : "Emilio", 
    "last_name" : "Hughes", 
    "email" : "emilio.hughes@magiciansinc.co", 
    "created_at": "2019-06-01T12:00:00+00:00", 
    "company": "Magicians Inc", 
    "job_title": "Procurement Manager" 
}, 
{ 
    "id" : 2, 
    "first_name" : "Joe", 
    "last_name" : "Blogs", 
    "email" : "joe.blogs@magiciansinc.co", 
    "created_at": "2019-06-01T12:00:00+00:00", 
    "company": "Magicians Inc", 
    "job_title": "Technical Specialist" 
} 
]'

记得在上面换上自己的 Key 及 Access Token。

当我们执行完上面的命令后：

点击 Return to sources:

点击 Details：

我们可以看到最新导入的两个文档。

在此阶段，我们不考虑权限，并假设 Workplace Search 的所有用户都可以找到任何联系人。 上面的请求使用三种不同的字段类型发送两个文档：number，date 和 text。 这里的数字字段也是一个 ID，用于唯一标识我们的联系人。 实际上，这可能会更加复杂，应考虑适当的值。

一点脚本

如上所述，Workplace Search API 要求以 JSON 格式提供文档。 要将 CSV 文件转换为 JSON，我们使用流行的工具 jq 并将结果传递给 curl：

jq --slurp --raw-input --raw-output \
  'split("\n") | .[1:101] | map(split(",")) |
      map({"id": .[0],
           "first_name": .[1],
           "last_name": .[2],
           "title": (.[1] + " " + .[2]),
           "description":  (.[1] + " " + .[2] +" works as a "+.[7] + " at " + .[8] + " in the "+ .[6] +" department. Their email is " + .[3]+"."),
           "email": .[3],
           "gender": .[4],
           "skills": .[5],
           "department": .[6],
           "job_title": .[7],
           "company": .[8],
           "url": .[8] })' \
  customer_contacts.csv  | \
curl -X POST --data-binary @- http://localhost:3002/api/ws/v1/sources/[KEY]/documents/bulk_create \
-H "Authorization: Bearer [API_TOKEN]" \
-H "Content-Type: application/json"

在这里，jq 只是用新行将文件内容分割开，并使用 map 函数生成每个 JSON 文档。 [1：101] 确保我们不考虑第一行，也不超过 Workplace Search 批量 API 规定的100个文档限制。 最后，将其传递给 curl，由于--data-binary @-参数，它接受输入。

在上面的命令中，我们把自己的 Key 及 Access Token 带入。执行完上面的命令：

重新刷新我们的 Workplace Search。我们将看到如上所示的画面。我们可以看到有100个文档。

定制结果显示

你可能已经注意到，除了将 CSV 文件中的每一列映射到 JSON 中的字段之外，我们还创建了字段 title，description 和 url。 虽然 Workplace Search 会自动使用这些内容进行显示，并使用 url 字段使结果可点击链接，但它还提供了一种简单的方法来进一步优化来源的演示文稿。 在来源的配置页上，导航至 “Display Settings”。 我们在此处所做的更改将确定如何向用户显示联系结果。 考虑到我们有限的字段集，所需的设置很简单。

最后，选择 “Result Detail” 选项卡以修改单击时显示结果的方式。 这里的一点点工作可以大大确保结果得到最佳呈现。

修改完后，就是这个样子：

 

查看搜索结果

现在，我们可以在 Workplace Search 中看到我们的联系数据。 这些结果看起来完全集成，并且受益于统一搜索体验的经典优势。

在上面我们搜索 Harris Ferrini。如果我们的 Workplace 含有其他的源，比如 Google Drive, Salesforce 等等，那么我们可能看到如下的搜索结果：

在屏幕的右方，我们可以看到刚才我们定制的 Result Detail 布局。

总结

通过首先解决磁盘上的联系人列表文件的简单用例，我们展示了如何轻松使用 “Custom Source” API 将企业级源添加到 Workplace Search。