安全注意事项

成功使用 POST /v1/register_callback 方法注册了回调 URL 时，服务会将该 URL 列入允许名单，以指示该 URL 已经过验证，可用于回调通知。 如果在注册调用中指定了用户私钥，那么列入允许名单还意味着该 URL 已经过验证，增加了安全性。 如果指定用户私钥，可为通过异步 HTTP 接口使用回调 URL 的请求提供认证功能和数据完整性。

服务使用用户秘密对其发送到 URL 的每个回调通知的有效载荷计算 HMAC-SHA256 签名。 服务通过每个通知中的 X-Callback-Signature 头来发送签名。 客户机可以使用私钥来计算其自己针对每个通知有效内容的签名。 如果其签名与 X-Callback-Signature 头的值相匹配，那么客户机就可确定通知是由服务发送的，并且其内容在传输期间未变更。 此确认可保证客户机不是中间人攻击的受害者。

对于生产应用程序，HTTPS 最为理想。 但是，在应用程序开发和原型设计期间，服务支持的基于 HTTP 的回调通知可通过避免 HTTPS 的开销，从而简化并加速开发过程。

注销回调 URL

您可以随时通过调用 POST /v1/unregister_callback 方法来注销列入允许名单的回调 URL。 注销回调 URL 对于使用服务测试应用程序可能非常有用。 注销回调 URL 后，即无法再将其用于异步识别请求。

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

回调通知

如果创建作业时使用了回调 URL，那么服务会在发生指定事件时，向注册的 URL 发送 HTTP POST 回调通知。 基本通知的主体包含一个 JSON 对象，其结构如下：

{
  "id": "{job_id}",
  "event": "{recognitions_status}",
  "user_token": "{user_token}"
}

id 字段标识生成了回调的作业的标识，event 字段标识触发了回调的事件。 如果指定了作业的用户令牌，那么 user_token 字段会包含此令牌。 否则，此字段为空字符串。 如果事件为 recognitions.completed_with_results，那么该对象会包含 results 字段，用于提供识别请求的结果。 客户机可以使用状态码 200 来响应回调通知。

如果注册回调 URL 时使用了用户私钥，那么服务还会在回调通知中发送 X-Callback-Signature 头。 该标头指定了请求正文的 HMAC-SHA256 签名。 服务会将用户私钥用作密钥来计算该签名。 客户机可以计算回调通知的有效内容的签名，以确保它与此头中的签名相匹配。 例如，以下简单 Python 代码基于字符串 notification_payload 计算签名：

import hmac
import base64
from hashlib import sha256
# 'user_secret' and 'notification_payload' must be bytes
hashed = hmac.new(user_secret, notification_payload, sha256)
signature = base64.b64encode(hashed.digest()).decode().rstrip('\n')

创建一个带有回拨功能的职位 URL 示例

以下示例创建与先前列入允许名单的回调 URL http://{user_callback_path}/results 关联的作业。 此示例传递用户令牌 job25 以在服务发送的回调通知中标识作业。 此调用使用的是缺省事件，因此用户必须调用 GET /v1/recognitions/{id} 方法，以在服务发送回调通知指示作业完成时检索结果。 此调用将识别请求的 timestamps 查询参数设置为 true。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

服务返回了请求的状态 waiting，指示服务正在准备作业以供处理。 响应包含作业创建时间、作业标识和用于获取作业更多相关信息的 URL。

{
  "created": "2016-08-17T19:15:17.926Z",
  "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
  "url": "{url}/v1/recognitions/4bd734c0-e575-21f3-de03-f932aa0468a0",
  "status": "waiting"
}

使用投票创建一个职位示例

以下示例创建未与回调 URL 关联的作业。 用户必须轮询服务来了解作业何时完成，然后使用 GET /v1/recognitions/{id} 方法来检索结果。 与先前的示例类似，此调用也将识别请求的 timestamps 参数设置为 true。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

服务返回了 processing 状态，指示服务已经在处理作业，同时返回了作业创建时间、作业标识和用于获取作业相关信息的 URL。

{
  "created": "2016-08-17T19:13:23.622Z",
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "url": "{url}/v1/recognitions/4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "status": "processing"
}

检查工作状态，无结果示例

下面的示例检查了指定 ID 的作业的状态：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

该作业尚未完成，因此响应未包含结果。

{
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "created": "2016-08-17T19:13:23.622Z",
  "updated": "2016-08-17T19:13:24.434Z",
  "status": "processing"
}

查看工作状态，结果示例

下面的示例要求查看指定 ID 的作业的状态：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

该作业已完成，因此响应包含请求的结果。

{
  "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
  "results": [
    {
      "result_index": 0,
      "results": [
        {
          "final": true,
          "alternatives": [
            {
              "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
              "timestamps": [
                [
                  "several",
                  1,
                  1.52
                ],
                [
                  "tornadoes",
                  1.52,
                  2.15
                ],
                . . .
                [
                  "Sunday",
                  5.74,
                  6.33
                ]
              ],
              "confidence": 0.96
            }
          ]
        }
      ]
    }
  ],
  "created": "2016-08-17T19:11:04.298Z",
  "updated": "2016-08-17T19:11:16.003Z",
  "status": "completed"
}

查看最新工作状态示例

下面的示例要求查看与调用者凭据相关联的最新当前工作的状态：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions"

用户有三个未完成作业，分别处于不同的状态。 第一个作业创建时使用了回调 URL 和用户令牌。

{
  "recognitions": [
    {
      "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
      "created": "2016-08-17T19:15:17.926Z",
      "updated": "2016-08-17T19:15:17.926Z",
      "status": "waiting",
      "user_token": "job25"
    },
    {
      "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
      "created": "2016-08-17T19:13:23.622Z",
      "updated": "2016-08-17T19:13:24.434Z",
      "status": "processing"
    },
    {
      "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-08-17T19:11:04.298Z",
      "updated": "2016-08-17T19:11:16.003Z",
      "status": "completed"
    }
  ]
}

删除职位示例

以下示例删除具有指定标识的作业：

IBM Cloud

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"