**引入全新的主机体验 AWS WAF**

现在，您可以使用更新的体验访问控制台中任意位置的 AWS WAF 功能。有关更多详细信息，请参阅[使用控制台](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 验证码 API 规范 JavaScript
<a name="waf-js-captcha-api-specification"></a>

本节列出了验证码的方法和属 JavaScript APIs性的规范。使用验证码在您的客户端 JavaScript APIs 应用程序中运行自定义的验证码拼图。

此 API 建立在智能威胁的基础上 APIs，您可以使用智能威胁来配置和管理 AWS WAF 令牌的获取和使用。请参阅 [智能威胁 API 规范](waf-js-challenge-api-specification.md)。

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
向最终用户展示 AWS WAF 验证码拼图，成功后，使用验证码验证更新客户端令牌。这仅在集成了验证码时可用。使用此调用和智能威胁 APIs 来管理令牌检索并在您的`fetch`通话中提供令牌。请访问以下网址查看智能威胁APIs [智能威胁 API 规范](waf-js-challenge-api-specification.md)。  
与 AWS WAF 发送的 CAPTCHA 插页式广告不同，通过这种方法渲染的 CAPTCHA 拼图会立即显示拼图，而无需初始标题屏幕。    
**`container`**  
页面上目标容器元素的 `Element` 对象。这通常是通过调用 `document.getElementById()` 或 `document.querySelector()` 来检索的。  
是否必需：是  
类型：`Element`  
**配置**  
一个包含验证码配置设置的对象，如下所示 ****：    
**`apiKey`**   
启用客户端域权限的加密 API 密钥。使用 AWS WAF 控制台为您的客户端域生成 API 密钥。一个密钥最多可用于五个域。有关信息，请参阅[管理 JS CAPTCHA API 的 API 密钥](waf-js-captcha-api-key.md)。  
是否必需：是  
类型：`string`  
**`onSuccess: (wafToken: string) => void;`**   
当最终用户成功完成验证码拼图时，使用有效 AWS WAF 令牌调用。在发送到使用保护包（Web ACL）保护的端点的 AWS WAF 请求中使用令牌。该令牌提供了最近成功完成拼图的证明和时间戳。  
是否必需：是  
**`onError?: (error: CaptchaError) => void;`**   
在验证码操作期间发生错误时，使用错误对象调用。  
必需：否  
**`CaptchaError` 类定义**：`onError` 处理程序使用以下类定义提供错误类型。  

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`：返回的错误类型。
+ `statusCode`：HTTP 状态码（如果有）。如果错误是由于 HTTP 错误造成的，则 `network_error` 将使用此选项。  
**`onLoad?: () => void;`**   
在加载新的验证码拼图时调用。  
必需：否  
**`onPuzzleTimeout?: () => void;`**   
在验证码拼图过期前未完成时调用。  
必需：否  
**`onPuzzleCorrect?: () => void;`**   
当有人为验证码拼图提供正确答案时调用。  
必需：否  
**`onPuzzleIncorrect?: () => void;`**   
当有人为验证码拼图提供不正确答案时调用。  
必需：否  
**`defaultLocale`**   
用于验证码拼图的默认语言环境。验证码拼图的书面说明有阿拉伯语 (ar-SA)、简体中文 (zh-CN)、荷兰语 (nl-NL)、英语 (en-US)、法语 (fr-FR)、德语 (de-DE)、意大利语 (it-IT)、日语 (ja-JP)、巴西葡萄牙语 (pt-BR)、西班牙语 (es-ES) 和土耳其语 (tr-TR)。除了中文和日语（默认为英语）外，所有书面语言都支持音频指令。要更改默认语言，请提供国际语言和区域代码，例如 `ar-SA`。  
默认：最终用户浏览器中当前使用的语言  
必需：否  
类型：`string`  
**`disableLanguageSelector`**   
如果设置为 `true`，则验证码拼图会隐藏语言选择器。  
默认值：`false`  
必需：否  
类型：`boolean`  
**`dynamicWidth`**   
如果设置为 `true`，则验证码拼图会更改宽度以与浏览器窗口宽度兼容。  
默认值：`false`  
必需：否  
类型：`boolean`  
**`skipTitle`**   
如果设置为 `true`，则验证码拼图不会显示拼图标题**完成拼图**。  
默认值：`false`  
必需：否  
类型：`boolean`