開發自訂 Cloud Pak for Data 連接器程式碼

自訂連接器範例包含名為 com.ibm.es.ama.custom.crawler 的 Java 套件。 此套件包含下列 Java 介面，您可以在撰寫自訂連接器時使用。

IBM Cloud Pak for Data IBM Software Hub

此資訊僅適用於已安裝的部署。

介面和 JavaDoc

本文件中列出的介面可在自訂連接器壓縮檔所包含的 JAR 套件檔案中找到。 After you download and expand the custom-crawler-docs.zip file as described in Downloading the custom-crawler-docs.zip file in Discovery 2.2.1 and later and Downloading the custom-crawler-docs.zip file in Discovery 2.2.0 and earlier, the interface JAR file is available as wexlib/ama-zing-custom-crawler-{version_numbers}.jar from the root level of the expanded compressed file. JAR 檔的 JavaDoc 在相同層次提供為 wexlib/ama-zing-custom-crawler-{version_numbers}-javadoc.jar。

起始設定介面

CustomCrawler

使用 com.ibm.es.ama.custom.crawler.CustomCrawler 介面啟動或停止自訂爬蟲，或從路徑抓取文件。 該介面具有下列方法。

CustomCrawler 方法
方法 說明
init 啟動自訂爬蟲
term 停止自訂爬蟲
crawl 從指定路徑抓取文件

配置介面

CustomCrawlerConfiguration

使用 com.ibm.es.ama.custom.crawler.CustomCrawlerConfiguration 介面可驗證配置以及探索資料來源上的可用搜索範圍。 該介面具有下列方法。

CustomCrawlerConfiguration 方法
方法 說明
validate 驗證配置
getFieldsFor 列出已知欄位及其類型
discoverySubspaces 探索資料來源上的搜索範圍

ConfigProvider

使用 com.ibm.es.ama.custom.crawler.CustomCrawlerConfiguration.ConfigProvider 介面可對映資料來源的設定，並列出資料來源上的搜索範圍設定。 該介面具有下列方法：

ConfigProvider 方法
方法 說明
get 取得區段中設定的對映
getCrawlspaceSettings 取得搜索範圍設定的清單

SubspaceConsumer

使用 com.ibm.es.ama.custom.crawler.CustomCrawlerConfiguration.SubspaceConsumer 介面可新增搜索範圍的路徑。 該介面具有下列方法：

SubspaceConsumer 方法
方法 說明
add 新增搜索範圍的路徑

搜索器介面

RecordKeeper

使用 com.ibm.es.ama.custom.crawler.CustomCrawler.RecordKeeper 介面可保留搜索記錄以及發佈搜索到的文件。 該介面具有下列方法：

RecordKeeper 方法
方法 說明
canContinue 布林值，列出搜索器是否可以繼續。 自訂搜索器必須定期輪詢此值，並在此值傳回 false 時終止。
check 從最後一個搜索到的文件中取得 meta 資料欄位
upsert 發佈文件以供進一步處理
delete 刪除文件

安全介面

CustomCrawlerSecurityHandler

使用 com.ibm.es.ama.custom.crawler.CustomCrawlerSecurityHandler 介面可為自訂搜索器實作安全。 該介面具有下列方法：

CustomCrawlerSecurityHandler 方法
方法 說明
term 終止安全處理程式
getUserAndGroups 取得給定使用者的 ACL

更新連接器的 getUserAndGroups 邏輯時，連接器重新部署後，變更可能需要 10 分鐘才能生效。

自訂連接器範例

範例連線器是 Secure File Transfer 通訊協定 (SFTP) 連線器，可抓取位於 SFTP 伺服器上的檔案。

範例連接器包含三個元件：

  • 連接器的 Java 原始碼
  • 一個 XML 定義檔案，定義連接器用來連接和抓取資料來源的參數
  • 內容檔，用於定義連接器的選用行為

需求

範例連接器的 Java 原始碼具有下列相依關係：

Downloading the custom-crawler-docs.zip file in Discovery 2.2.1 and later

In Discovery version 2.2.1 and later, perform the following steps to download the custom-crawler-docs.zip file to your local machine. 您需要具有對已安裝 Discovery 實例的 root 存取權：

  1. 登入 Discovery 叢集。

  2. 輸入下列指令以取得您的 crawler pod 名稱：

    oc get pods | grep crawler

    您可能會看到類似這樣的輸出：

    wd-discovery-crawler-57985fc5cf-rxk89     1/1     Running     0          85m

  3. 輸入下列指令以取得 custom-crawler-docs.zip 檔案，將 {crawler-pod-name} 改為您在步驟 2 中取得的 crawler pod 名稱：

    oc exec {crawler-pod-name} -- ls -l /opt/ibm/wex/zing/resources/ \
| grep custom-crawler-docs

    您可能會看到類似下列內容的輸出：

    -rw-r--r--. 1 dadmin dadmin 59451 Jan 19 03:50 custom-crawler-docs-${build-version}.zip

  4. 輸入下列指令，以將 custom-crawler-docs.zip 檔案複製到主伺服器，並將 {build-version} 取代為步驟 3 中的建置版本號碼：

    oc cp {crawler-pod-name}:/opt/ibm/wex/zing/resources/custom-crawler-docs-${build-version}.zip custom-crawler-docs.zip

  5. 輸入下列指令，以展開 custom-crawler-docs.zip 檔案：

    unzip custom-crawler-docs.zip -d custom-crawler-docs-primary

    必要的話，請將 custom-crawler-docs.zip 檔案複製到開發伺服器。

    如果您的本機沒有 unzip 公用程式，請嘗試使用 gunzip 指令代替，或參閱本機作業系統的說明文件，以瞭解其他擴充壓縮檔案的替代方法。

    如果您使用早於 2.1.2 的 Discovery 版本，且想要存取 custom-crawler-docs.zip 檔，請輸入下列指令：scp root@{instance_name}:/root/bob/sdk/custom-crawler-docs.zip {local_directory}。

For information about downloading the custom-crawler-docs.zip file to Discovery 2.2.0 and earlier, see Downloading the custom-crawler-docs.zip file to Discovery 2.2.0 and earlier.

Downloading the custom-crawler-docs.zip file to Discovery 2.2.0 and earlier

In Discovery version 2.2.0 and earlier, perform the following steps to download the custom-crawler-docs.zip file to your local machine. 您需要具有對已安裝 Discovery 實例的 root 存取權：

  1. 通過導航到您的 容器軟體庫獲取權限密鑰。

  2. 輸入下列指令，以登入包含 Discovery 映像的 Docker 登錄。 在下列指令中包含您的授權金鑰：

    docker login cp.icr.io -u cp -p {entitlement_key}

  3. 輸入下列指令，取回 custom-crawler-sdk 映像：

    docker pull cp.icr.io/cp/watson-discovery/custom-crawler-sdk:2.1.3

  4. 輸入下列指令，執行 custom-crawler-sdk 映像：

    docker run cp.icr.io/cp/watson-discovery/custom-crawler-sdk:2.1.3

  5. 輸入下列指令，從執行映像的容器中複製 custom-crawler-docs.zip：

    docker cp {container_name}:/crawler/custom-crawler-docs.zip .

    若要尋找映像，請輸入 docker ps -a | grep custom-crawler-sdk。

  6. 解壓縮 custom-crawler-docs.zip 檔案：

    cd {local_directory}

    其中，{local_directory} 是本端機器上已下載 custom-crawler-docs.zip 檔案的目錄。

    unzip custom-crawler-docs.zip

    如果您的本機沒有 unzip 公用程式，請嘗試使用 gunzip 指令代替，或參閱本機作業系統的說明文件，以瞭解其他擴充壓縮檔案的替代方法。

    如果您使用早於 2.1.2 的 Discovery 版本，且想要存取 custom-crawler-docs.zip 檔，請輸入下列指令：scp root@{instance_name}:/root/bob/sdk/custom-crawler-docs.zip {local_directory}。

For information about downloading the custom-crawler-docs.zip file on Discovery version 2.2.1 and later, see Downloading the custom-crawler-docs.zip file in Discovery 2.2.1 and later.

瞭解 custom-crawler-docs.zip 檔案

custom-crawler-docs.zip 檔案會展開為一個名為 custom-crawler-docs-primary 的目錄，其中包含下列內容：

custom-crawler-docs-primary
├── README.md
├── build.gradle
├── config
│   ├── README.md
│   ├── messages.properties
│   └── template.xml
├── scripts
│   └── manage_custom_crawler.sh
├── settings.gradle
├── src
│   └── main
│       └── java
│           └── com
│               └── ibm
│                   └── es
│                       └── ama
│                           └── custom
│                               └── crawler
│                                   └── sample
│                                       └── sftp
│                                           └── SftpCrawler.java
|                                           └── SftpSecurityHandler.java
└── wexlib
    ├── META-INF
    │   └── MANIFEST.MF
    ├── README.md
    ├── ama-zing-custom-crawler-{version_numbers}-javadoc.jar
    └── ama-zing-custom-crawler-{version_numbers}.jar

15 directories, 12 files

下載 JSch

JSch 是安全 Shell 通訊協定第 2 版 (SSH2) 和 sftp（透過延伸）的 Java 實作。 它源自 Java Cryptography Extension(JCE)。 您可以在以下網址找到 SSH2 的規格 www.openssh.com/specs.html.

JSch 目前的版本是 0.1.55 並由範例連線器支援。

下載 JSch 到您的開發目錄 ( {local_directory} )。您可以下載 ZIP 格式或 JAR 格式的套件。 如果您下載的是 .zip 格式的套件，請依照上一節所述將其解壓。

範例連接器的檔案

範例自訂連接器包含三個一起建置的檔案：

  • Java source files that are named SftpCrawler.java and SftpSecurityHandler.java
  • 名為 template.xml 的 XML 定義檔
  • 名為 message.properties 的內容檔

您可以藉由參照瞭解 custom-crawler-docs.zip 檔案中的目錄樹狀結構清單，來找到並檢查這些檔案。

相關資訊

如需 com.ibm.es.ama.custom.crawler 套件中提供之所有介面和方法的詳細文件，請參閱介面和 JavaDoc 中所示的可用 JavaDoc。