以编程方式创建 Watson Discovery 服务实例

重要信息： IBM Cloud Pak® for Data 4.6 版本将于 2025 年 7 月 31 日结束支持 (EOS)。欲了解更多信息，请参阅 IBM Cloud Pak for Data 版本 4.X 的停止服务公告。

在 IBM Cloud Pak for Data 4.6 版本支持结束之前，升级到 IBM Software Hub 5.1 版本。更多信息，请参阅 IBM Software Hub 版本 5.1 文档中的升级 IBM Software Hub。

使用应用程序编程接口来创建 Watson Discovery 服务实例。

此任务相当于从 Cloud Pak for Data Web 客户机供应服务实例。更多信息，请参阅从网络客户端创建 Watson Discovery 服务实例。或者，可以使用命令行界面来创建服务实例。有关详细信息，请参阅从命令行创建 Watson Discovery 服务实例。

必需角色: 要使用此 API ，您必须在 Cloud Pak for Data中具有 can_provision 许可权。

先决条件步骤

在可以使用 API 之前，必须获取可用于获取可通过 RESTful API 请求传递的令牌的 API 密钥。遵循生成用于认证的 API 密钥中描述的步骤。

创建服务实例

要使用 API 创建服务实例，请完成以下步骤。

以下命令获取要在其中创建实例的 Cloud Pak for Data 集群的主机名。
```
oc get route cpd -n $PROJECT_CPD_INSTANCE -ojsonpath='{.spec.host}'
```
您将在后续 API 请求中传递此主机名作为 <host> 变量。

发送 POST 请求以创建服务实例。

使用正确的部署值更新以下变量:

<host>: 在上一步中检索到的主机名。
<token>: 完成先决条件步骤时获取的授权令牌。
${VERSION}: 安装的 Cloud Pak for Data 软件版本的环境变量。
<instance-name>: 要用于服务实例的名称。此名称显示在 Cloud Pak for Data Web 客户机的 " 实例 " 页面中。该名称可以包含字母数字字符，空格，短划线，下划线和句点。
${PROJECT_CPD_INSTANCE}: 在安装服务之前定义的项目名称 (以前称为名称空间) 的环境变量。有关更多信息，请参阅设置安装环境变量。

curl --insecure --request POST --url <host>/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>" \
  --header 'Content-Type: application/json' \
  --data "{
    \"addon_type\": \"discovery\", 
    \"addon_version\": \"${VERSION}\", 
    \"create_arguments\": { 
      \"deployment_id\": \"$PROJECT_CPD_INSTANCE-wd\",
      \"parameters\" : {
        \"serviceId\": \"discovery\", 
        \"url\": \"https://wd-discovery-gateway.$PROJECT_CPD_INSTANCE.svc.cluster.local:60443/v2/service_instances\", 
        \"watson\": true 
       } 
     }, 
     \"display_name\": \"<instance-name>\", 
     \"namespace\": \"$PROJECT_CPD_INSTANCE\" 
   }"

示例

以下示例显示如何获取访问令牌，然后发出 API 请求以创建服务实例。

提交以下命令以获取要在其中创建实例的 Cloud Pak for Data 集群的主机名。
```
oc get route cpd -n $PROJECT_CPD_INSTANCE -ojsonpath='{.spec.host}'
```
此示例中返回的主机名为 cpd.apps.my.cluster.example.com。然后，在后续 API 请求中将主机名作为 <host> 变量传递。
获取平台 API 密钥。
1. 获取 Cloud Pak for Data 集群的访问令牌。此请求使用基本认证; 它为管理角色中可以供应服务实例的用户提供用户凭证。
```
curl --request POST --user jdoe:mypassword \
--url <host>/v1/preauth/validateAuth
```
  响应包含包含不记名令牌的 accessToken 字段。存储令牌，以便您可以在下一步中指定该令牌。
2. 生成可用于在提交 RESTful API 请求时识别自己的 API 密钥。此请求将使用先前步骤中返回的令牌进行认证。
  注: 此请求生成的 API 密钥将替换与您的用户标识关联的现有 API 密钥。
```
curl --request POST \
--url <host>/usermgmt/v1/user/apiKey \
--header "Authorization: Bearer <token>"
```
  此响应包含包含 API 密钥的 apiKey 字段。将密钥存储在安全的位置。如果丢失此密钥，将无法恢复。
使用 API 密钥来创建授权您发送 API 请求的令牌。提交以下 POST 请求以创建令牌。
该请求使用基本认证; 它为创建 API 密钥并有权供应服务实例的同一用户提供用户凭证。
```
curl --request POST --user jdoe:mypassword \
--url <host>/icp4d-api/v1/authorize
```
如果显示有关证书错误的消息，那么可以将 --insecure 参数添加到请求以禁用证书验证。
在请求主体中，指定在上一步中获取的 API 密钥。用户名必须与用于认证此请求的名称相同。
```
{
  "username":"jdoe",
  "api_key":"amgbHu4VwDXRho9yLvF2IN5QkUVMWykjAolxYYQp"
}
```
将用于认证请求的令牌将在响应的 token 字段中返回。复制令牌值，以便稍后可以使用该值。

以下 POST 请求将创建 Watson Discovery 服务实例。

在此示例中，项目名称为 zen。

请求主体的 url 参数中指定的 URL 由 Watson 网关微服务使用，该服务用于管理 Watson 服务的 API 请求。

示例请求：

curl --request POST --url https://cpd.apps.my.cluster.example.com/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>" \
  --header 'Content-Type: application/json' \
  --data "{
    \"addon_type\": \"discovery\",
    \"addon_version\": \"4.6.2\",
    \"create_arguments\": {
      \"deployment_id\": \"zen-wd\",
      \"parameters\" : {
        \"serviceId\": \"discovery\", 
        \"url\": \"https://wd-discovery-gateway.zen.svc.cluster.local:60443/v2/service_instances\",
        \"watson\": true
       }
     },
     \"display_name\": \"My instance\",
     \"namespace\": \"zen\"
   }"

响应包含 id 参数，其中包含所创建实例的实例标识。记下实例标识。

响应示例：

{
    "id": "1670881541354464"
}

完成 Watson Discovery 任务

创建实例后，可以使用 Watson Discovery API 来添加项目和数据。

要使用 API ，请完成以下步骤:

要使用服务 API ，请使用以下语法向要使用的方法的相应端点提交请求:
```
https://<url>/<method>
```
您可以通过传递用于供应服务实例的相同不记名令牌来认证请求。
要构造要在请求的 <url> 段中使用的 URL ，请将 URL 的 <host>, <deployment_id>, 和 <instance_id> 段替换为部署中的值。
```
https://<host>/discovery/<deployment_id>/instances/<instance_id>/api
```

请求的 method 段定义要执行的操作。要创建项目，要使用的方法为 v2/projects。

要在您创建的服务实例中创建 "文档检索" 项目，可以向以下端点发送 POST 请求:

https://<host>/discovery/<deployment_id>/instances/<instance_id>/api/v2/projects

例如：

curl --request POST --url https://cpd.apps.my.cluster.example.com/discovery/zen-wd/instances/1670881541354464/api/v2/projects?version=2020-08-30

在请求主体中，定义项目:

{
  "name": "My new project",
  "type": "document_retrieval" 
}

有关可用于以编程方式处理 Watson Discovery 的方法，请参阅 Watson Discovery API 文档。

列出服务实例

以下示例语法列出了 Cloud Pak for Data 服务实例:

curl --request GET \
  --url https://<host>/zen-data/v3/service_instances \
  --header "Authorization: Bearer <token>"

删除服务实例

以下示例语法显示了如何删除由其实例标识指定的服务实例:

curl --request DELETE \
  --url https://<host>/zen-data/v3/service_instances/<instanceId> \
  --header "Authorization: Bearer <token>"