一次性 APPKEY

APPKEY 的安全处理

APPKEY 是应用程序使用 AmiVoice API 时的"服务认证密钥字符串"，如果泄露可能会被滥用。如果将 APPKEY 嵌入应用程序中，恶意第三方可能会从应用程序中提取 APPKEY。通常，请不要将您自己拥有的 APPKEY 发送到应用程序用户的机器上。相反，请使用具有有效期限的一次性 APPKEY，以便即使泄露也能将影响范围降到最低。

备注

一次性 APPKEY 与 My Page 上列出的 APPKEY 具有相同的功能，是一个"服务认证密钥字符串"，但不同之处在于它根据"发行日期和有效时间"设置了"有效期限日期"。此外，还可以对连接源的 IP 地址进行限制。
一次性 APPKEY 的发行数量没有上限。

警告

特别是对于 Web 应用程序，请避免在 HTML 或 JavaScript 中写入 APPKEY，因为网站用户可能会看到它。
如果无法避免将 APPKEY 嵌入应用程序中，请对 APPKEY 进行混淆或加密。混淆或加密可以使从应用程序中提取 APPKEY 变得更加困难。
APPKEY 无法更改。要更改它，需要取消会员资格并创建新帐户。
无限期发行的一次性 APPKEY 与 My Page 上的 APPKEY 一样，无法更改或禁用，因此在发行时请充分考虑后再使用。

使用一次性 APPKEY

使用一次性 APPKEY 时，可以考虑以下实现方法：

通过某种方式对应用程序用户进行身份验证
身份验证成功后，在服务器端发行设置了有效期限的一次性 APPKEY 并发送给应用程序
应用程序使用一次性 APPKEY 来使用 AmiVoice API

以下说明如何使用一次性 APPKEY 发行 API。

请求

要使用一次性 APPKEY 发行 API，需要设置 serviceId(查询参数名为 sid)和服务密码(spw)。请设置 My Page 中"连接信息"的"共同连接信息"中列出的[serviceId]和[服务密码]。

备注

服务密码与用于登录 My Page 的密码不同。

有效时间(查询参数名为 epi)可以任意设置。如果将数值设置为 epi，则以毫秒为单位。有关其他设置方法，请参阅参考。如果省略 epi，则默认值设置为 30000(30 秒)。请考虑从发行一次性 APPKEY 到实际发送 AmiVoice API 请求之间的预期时间来进行设置。可以在 ipa 中指定可以使用 APPKEY 的 IP 地址。

让我们使用 curl 命令来发行一次性 APPKEY。

示例1

仅限 IP 地址 203.0.113.253 的访问，并将有效期限设置为发行后 30 秒。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.253

示例2

如果要按范围指定允许的 IP 地址，可以使用 CIDR 指定。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

示例3

IP 地址或其范围可以用逗号分隔多个指定。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

响应

响应是纯文本，返回一次性 APPKEY。可以直接将其设置为请求参数的 authorization key。

错误时的处理方法

使用一次性 APPKEY 连接认证失败的情况

由于延迟(过期)导致的认证错误

如果接收 authorization key 的认证请求的时间超过了一次性 APPKEY 设置的有效期限日期，语音识别服务将返回以下错误，请重新获取一次性 APPKEY 并重试。

HTTP 接口的错误响应

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 接口的错误响应

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

s 响应中包含的 20XX/XX/XX XX:XX:XX.000 是一次性 APPKEY 的有效期限日期，-21s 是超过有效期限的延迟时间。

即使在 s 命令响应数据包中没有发生错误，如果在发送第一个 p 数据包之前经过的时间超过了有效期限日期，则在发送第一个 p 数据包后立即返回以下错误响应。

p can't feed audio data to recognizer server

在成功开始发送 p 数据包后，不会在中途过期。

由于非法 ID 导致的认证错误

即使在一次性 APPKEY 发行 API 中指定的 serviceId 和 service 密码不正确，也会发行一次性 APPKEY。在 AmiVoice API 请求时，如果指定了使用错误的 serviceId 和密码创建的非法一次性 APPKEY，将返回以下认证错误。

HTTP 接口的错误响应

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 接口的错误响应

s can't verify service authorization

在这种情况下，请确认在请求一次性 APPKEY 发行时指定的 serviceId (sid)和 service 密码(spw)是否为正确值。

有关一次性 APPKEY 发行 API 的详细信息，请参阅参考中的一次性 APPKEY 发行 API。

在异步 HTTP 接口中使用一次性 APPKEY 时

在异步 HTTP 接口中使用一次性 APPKEY 时，请将有效期限设置得足够长。通常，开始语音识别需要几分钟的时间。此外，在繁忙时，极少数情况下可能会暂停然后重新开始，即使在识别过程中也可能需要认证。

APPKEY 的安全处理​

使用一次性 APPKEY​

请求​

响应​

错误时的处理方法​

使用一次性 APPKEY 连接认证失败的情况​

由于延迟(过期)导致的认证错误​

由于非法 ID 导致的认证错误​

在异步 HTTP 接口中使用一次性 APPKEY 时​