本文為您介紹如何使用POP API，在客戶端自行操作訓練業務專屬熱詞，而無需依賴控制臺的設置。
操作概覽
您可通過POP API執行如下操作：
創建詞表：
CreateAsrVocab獲取詞表：
GetAsrVocab更新詞表：
UpdateAsrVocab刪除詞表 ：
DeleteAsrVocab列舉所有詞表：
ListAsrVocab
調用限制
默認最多創建10個詞表。
每個詞表最多添加500個詞，每個詞語最長10個字。
業務專屬熱詞必須為
UTF-8編碼，不能包含標點、特殊字符。業務專屬詞對應的權重取值范圍為[-6,5]之間的整數。
說明取值大于0增大該詞語被識別的概率，小于0減小該詞語被識別的概率。
取值為-6：表示盡量不要識別出該詞語。
取值為2：常用值。
如果效果不明顯可以適當增加權重，但是當權重較大時可能會引起負面效果，導致其他詞語識別不準確。
創建詞表
一個詞表就是一類業務專屬熱詞的組合。
請求參數：
提交創建詞表的請求時，需要設置請求參數到請求的Body中，如下表所示。
名稱 | 類型 | 是否必選 | 說明 |
Name | String | 是 | 詞表名稱。 |
WordWeights | String | 是 | 詞表里的詞和對應的權重，為JSON的Map格式字符串。例如： key為String類型的熱詞，value為Int類型的熱詞對應的權重。 |
Description | String | 否 | 詞表描述信息。 |
返回數據：
返回數據為JSON格式的字符串。
{
"VocabId": "0074ac87db754e0fbd3465c60d86****",
"RequestId": "77C00AE4-A646-4A41-B6FF-F06C19FA****"
}返回HTTP狀態：200表示成功，更多狀態碼請查閱錯誤碼。
返回JSON格式字符串參數：
名稱
類型
說明
RequestId
String
請求ID。
VocabId
String
詞表ID，作為后續詞表的獲取、更新、刪除使用。
獲取詞表
根據詞表的ID獲取對應的詞表信息。
請求參數：
提交獲取詞表的請求時，需要設置請求參數到請求的Body中，如下表所示。
名稱 | 類型 | 是否必選 | 說明 |
Id | String | 是 | 詞表ID（創建詞表時獲取的VocabId）。 |
返回數據：
返回數據為JSON格式的字符串。
{
"RequestId": "A590423E-FEBC-4AA0-A520-4DA77292****",
"Vocab": {
"Name": "測試詞表",
"Md5": "58c732d3b31eb564c275371d46fc****",
"Description": "測試詞表描述",
"CreateTime": "2018-11-26 17:19:40",
"UpdateTime": "2018-11-26 17:19:40",
"Id": "6118b2a057d1440bb253382a7617****",
"WordWeights": {
"西瓜": 3,
"蘋果": 3
},
"Size": 323
}
}返回HTTP狀態：200表示成功，更多狀態碼請查閱錯誤碼。
返回JSON格式字符串參數：
名稱
類型
說明
RequestId
String
請求ID。
Vocab
Vocab對象
詞表對象。
其中，Vocab對象的參數描述如下表所示。
名稱
類型
說明
Id
String
詞表ID（與創建詞表時獲取的VocabId相同）。
Name
String
詞表名稱。
Description
String
詞表描述信息。
Size
Int
詞表編譯后的大小。
Md5
String
詞表編譯后的md5值。
CreateTime
String
詞表創建時間。
UpdateTime
String
詞表更新時間。
WordWeights
Map
詞表中的業務專屬熱詞和對應的權重。
更新詞表
根據詞表的ID可以更新對應的詞表信息，包括詞表名稱、詞表描述信息、詞表的詞和權重。
請求參數：
提交更新詞表的請求時，需要設置請求參數到請求的Body中，如下表所示。
名稱 | 類型 | 是否必選 | 說明 |
Id | String | 是 | 詞表Id（創建詞表時獲取的VocabId）。 |
Name | String | 是 | 更新后的詞表名稱。 |
WordWeights | String | 是 | 更新后的詞表里業務專屬熱詞和對應的權重，為JSON的Map格式字符串。 |
Description | String | 否 | 更新后的詞表描述信息。 |
返回數據：
返回數據為JSON格式的字符串。
{
"RequestId": "829E373C-9E23-4DEF-A979-002F140B****"
}返回HTTP狀態：200表示成功，更多狀態碼請查閱錯誤碼。
返回JSON格式字符串參數：
名稱
類型
說明
RequestId
String
請求ID。
刪除詞表
根據詞表的ID刪除對應的詞表。
請求參數：
提交刪除詞表請求時，需要設置請求參數到請求的Body中，如下表所示。
名稱 | 類型 | 是否必選 | 說明 |
Id | String | 是 | 詞表Id（創建詞表時獲取的VocabId）。 |
返回數據：
返回數據為JSON格式的字符串。
{
"RequestId": "75CCBD40-BC19-4227-9140-0F42806B****"
}返回HTTP狀態：200表示成功，更多狀態碼請查閱錯誤碼。
返回JSON格式字符串參數：
名稱
類型
說明
RequestId
String
請求ID。
列舉詞表
列舉指定頁的詞表信息。
為了防止響應Body過大，獲取的詞表信息不包含具體的專屬熱詞和對應的權重信息。
請求參數：
提交列舉詞表請求時，需要設置請求參數到請求的Body中，如下表所示。
名稱 | 類型 | 是否必選 | 說明 |
PageNumber | Int | 否 | 頁號，默認值為1，取值大于0。 |
PageSize | Int | 否 | 每頁包含的詞表數量，默認值為10，取值范圍為[10,100]。 |
服務端根據詞表的修改時間降序排列，如果詞表過多，一次獲取全部的詞表，導致HTTP響應體過大，可能會被中間的網關或者代理節點攔截。因此采用分頁的方式，每次請求獲取指定的一頁詞表。PageSize指定了每頁的詞表數量，不足一頁按一頁處理，PageNumber指定了要獲取第幾頁的詞表。
返回數據：
返回數據為JSON格式的字符串。
{
"Page": {
"PageNumber": 1,
"PageSize": 10,
"TotalItems": 5,
"TotalPages": 1,
"Content": [{
"Name": "測試詞表_1",
"Md5": "eafaaf1d73b17c9d35c64d600e07****",
"Description": "測試詞表描述_1",
"CreateTime": "2018-11-26 17:51:41",
"UpdateTime": "2018-11-26 17:51:41",
"Id": "266df2819a9d4d96a07c5c5d39b6****",
"Size": 323
}, {
"Name": "測試詞表_2",
"Md5": "f32c10fd8569cb3712576a0ea988****",
"Description": "測試詞表描述_2",
"CreateTime": "2018-11-26 17:51:41",
"UpdateTime": "2018-11-26 17:51:41",
"Id": "0fa718759c034f67bb3e394d2fd9****",
"Size": 323
}]
},
"RequestId": "CB7B4AB4-5C16-4617-8B91-519A130E****"
}
錯誤碼
在提交創建詞表、獲取詞表、更新詞表、刪除詞表、列舉詞表的請求時，獲取的HTTP響應狀態碼如果不是200，則表示請求失敗。失敗信息以JSON格式字符串包含在HTTP響應的Body中，具體的錯誤碼如下表所示。
錯誤碼 | 說明 | 解決方案 |
SLP.PAGE_NUMBER_INVALID | 調用列舉接口時設置了無效的頁號。 | 請檢查列舉的頁號是否在有效取值范圍：[1, ∞)。 |
SLP.PAGE_SIZE_INVALID | 調用列舉接口時設置了無效的頁大小。 | 請檢查列舉的頁大小是否在有效取值范圍：[10, 100]。 |
SLP.NOT_FOUND | 詞表ID不存在。 | 請檢查使用的詞表ID是否正確。 |
SLP.PARAMETER_ERROR | 請求參數設置錯誤。 | 請參考返回的具體錯誤消息提示，檢查參數設置。 |
SLP.EXCEED_LIMIT | 創建詞表數量超過上限。 | 請確認現有的詞表數量限制，默認每個用戶允許創建10個業務專屬熱詞表。 |
SLP.ASR_VOCAB_ERROR | 其他錯誤。 | 與詞表相關的其他錯誤，請參考錯誤消息提示。 |
以創建詞表超出數量限制的錯誤響應為例：
{
"RequestId": "848C33E3-5A74-4BF8-9BE6-B78576C6****",
"HostId": "nls-slp.cn-shanghai.aliyuncs.com",
"Code": "SLP.EXCEED_LIMIT",
"Message": "Vocab count has reached the limit! (max: 10)"
}示例代碼
示例使用了阿里云Java SDK的CommonRequest提交請求，采用的是RPC風格的POP API調用方式。
阿里云SDK的詳細介紹請參見安裝及使用Java SDK。
Java SDK CommonRequest的使用方法請參見使用CommonRequest進行調用。
您只需要依賴阿里云Java SDK核心庫與阿里開源庫fastjson。阿里云Java SDK的核心庫版本支持3.5.0及以上（如果版本在4.0.0及以上，需要增加其對應的第三方依賴，根據錯誤提示補充即可）。
<dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <version>3.7.1</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.83</version> </dependency>調用接口前，需配置環境變量，通過環境變量讀取訪問憑證。智能語音交互的AccessKey ID和AccessKey Secret的環境變量名：ALIYUN_AK_ID和ALIYUN_AK_SECRET。
import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AsrVocabPopApiDemo {
/**
* 地域信息
* 常量內容，固定值。
*/
private static final String REGION_ID = "cn-shanghai";
private static final String DOMAIN = "nls-slp.cn-shanghai.aliyuncs.com";
private static final ProtocolType PROTOCOL_TYPE = ProtocolType.HTTPS;
/**
* POP API信息
* 常量內容，固定值。
*/
private static final String API_VERSION = "2018-11-20";
private static final String ACTION_CREATE_ASR = "CreateAsrVocab";
private static final String ACTION_GET_ASR_VOCAB = "GetAsrVocab";
private static final String ACTION_LIST_ASR_VOCAB = "ListAsrVocab";
private static final String ACTION_UPDATE_ASR_VOCAB = "UpdateAsrVocab";
private static final String ACTION_DELETE_ASR_VOCAB = "DeleteAsrVocab";
/**
* 參數設置key
* 常量內容，固定值。
*/
private static final String KEY_VOCAB_ID = "VocabId";
private static final String KEY_ID = "Id";
private static final String KEY_NAME = "Name";
private static final String KEY_DESCRIPTION = "Description";
private static final String KEY_WORD_WEIGHTS = "WordWeights";
private static final String KEY_VOCAB = "Vocab";
private static final String KEY_PAGE = "Page";
private static final String KEY_PAGE_NUMBER = "PageNumber";
private static final String KEY_PAGE_SIZE = "PageSize";
// 阿里云鑒權client
private static IAcsClient client;
static class Vocab {
public String Id;
public String Name;
public String Description;
public int Size;
public String Md5;
public String CreateTime;
public String UpdateTime;
public Map<String, Integer> WordWeights = new HashMap<String, Integer>();
}
static class Page {
class VocabContent {
public String Id;
public String Name;
public String Description;
public int Size;
public String Md5;
public String CreateTime;
public String UpdateTime;
}
public int PageNumber;
public int PageSize;
public int TotalItems;
public int TotalPages;
public List<VocabContent> Content = new ArrayList<VocabContent>();
}
public AsrVocabPopApiDemo(String akId, String akSecret) {
DefaultProfile profile = DefaultProfile.getProfile(REGION_ID, akId, akSecret);
client = new DefaultAcsClient(profile);
}
private CommonRequest newRequest(String action) {
CommonRequest request = new CommonRequest();
request.setDomain(DOMAIN);
request.setProtocol(PROTOCOL_TYPE);
request.setVersion(API_VERSION);
request.setMethod(MethodType.POST);
request.setAction(action);
return request;
}
/**
* 創建詞表
*
* @param name 詞表名稱，必填。
* @param description 詞表描述信息，可選。
* @param wordWeights 詞表里的詞和對應的權重，JSON的Map格式，必填。
*
* @return String 創建的詞表Id。
*/
String createAsrVocab(String name, String description, String wordWeights) {
CommonRequest request = newRequest(ACTION_CREATE_ASR);
request.putBodyParameter(KEY_NAME, name);
request.putBodyParameter(KEY_DESCRIPTION, description);
request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
CommonResponse response = null;
try {
response = client.getCommonResponse(request);
} catch (ClientException e) {
e.printStackTrace();
}
if (response.getHttpStatus() != 200) {
System.out.println(response.getData());
System.out.println("創建詞表失敗，HTTP錯誤碼：" + response.getHttpStatus());
return null;
}
JSONObject result = JSONObject.parseObject(response.getData());
String vocabId = result.getString(KEY_VOCAB_ID);
return vocabId;
}
/**
* 獲取詞表
*
* @param vocabId 詞表Id。
*
* @return Vocab 獲取的詞表對象。
*/
Vocab getAsrVocab(String vocabId) {
CommonRequest request = newRequest(ACTION_GET_ASR_VOCAB);
request.putBodyParameter(KEY_ID, vocabId);
CommonResponse response = null;
try {
response = client.getCommonResponse(request);
} catch (ClientException e) {
e.printStackTrace();
}
if (response.getHttpStatus() != 200) {
System.out.println(response.getData());
System.out.println("獲取詞表失敗，HTTP錯誤碼：" + response.getHttpStatus());
return null;
}
JSONObject result = JSONObject.parseObject(response.getData());
String vocabJson = result.getString(KEY_VOCAB);
Vocab vocab = JSONObject.parseObject(vocabJson, Vocab.class);
return vocab;
}
/**
* 更新詞表
*
* @param vocabId 待更新的詞表Id。
* @param name 更新后的詞表名稱。
* @param description 更新后的詞表描述。
* @param wordWeights 更新后的熱詞和權重。
*
* @return boolean 更新詞表是否成功。
*/
boolean updateAsrVocab(String vocabId, String name, String description, String wordWeights) {
CommonRequest request = newRequest(ACTION_UPDATE_ASR_VOCAB);
request.putBodyParameter(KEY_ID, vocabId);
request.putBodyParameter(KEY_NAME, name);
request.putBodyParameter(KEY_DESCRIPTION, description);
request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
CommonResponse response = null;
try {
response = client.getCommonResponse(request);
} catch (ClientException e) {
e.printStackTrace();
}
if (response.getHttpStatus() != 200) {
System.out.println(response.getData());
System.out.println("更新詞表失敗，HTTP錯誤碼：" + response.getHttpStatus());
return false;
}
return true;
}
/**
* 刪除詞表
*
* @param vocabId 詞表Id。
*
* @return boolean 刪除詞表是否成功。
* */
boolean deleteAsrVocab(String vocabId) {
CommonRequest request = newRequest(ACTION_DELETE_ASR_VOCAB);
request.putBodyParameter(KEY_ID, vocabId);
CommonResponse response = null;
try {
response = client.getCommonResponse(request);
} catch (ClientException e) {
e.printStackTrace();
}
if (response.getHttpStatus() != 200) {
System.out.println(response.getData());
System.out.println("刪除詞表失敗, HTTP錯誤碼：" + response.getHttpStatus());
return false;
}
return true;
}
/**
* 列舉詞表
* 如果不指定獲取的頁號，默認獲取第1頁。
* 如果不指定每頁的詞表數量，默認每頁10個詞表。
*
* @return Page 所有詞表信息。
*/
Page listAsrVocab() {
CommonRequest request = newRequest(ACTION_LIST_ASR_VOCAB);
request.putBodyParameter(KEY_PAGE_NUMBER, 1);
request.putBodyParameter(KEY_PAGE_SIZE, 10);
CommonResponse response = null;
try {
response = client.getCommonResponse(request);
} catch (ClientException e) {
e.printStackTrace();
}
if (response.getHttpStatus() != 200) {
System.out.println(response.getData());
System.out.println("列舉詞表失敗，HTTP錯誤碼：" + response.getHttpStatus());
return null;
}
JSONObject result = JSONObject.parseObject(response.getData());
String pageJson = result.getString(KEY_PAGE);
Page page = JSONObject.parseObject(pageJson, Page.class);
return page;
}
public static void main(String[] args) {
if (args.length < 2) {
System.err.println("FileASRDemo need params: <AccessKey Id> <AccessKey Secret>");
return;
}
String accessKeyId = System.getenv().get("ALIYUN_AK_ID");
String accessKeySecret = System.getenv().get("ALIYUN_AK_SECRET");
AsrVocabPopApiDemo demo = new AsrVocabPopApiDemo(accessKeyId, accessKeySecret);
// 詞表ID
String vocabId = null;
/**
* 創建詞表
*/
String name = "測試詞表";
String description = "測試詞表描述";
String wordWeights = "{\"蘋果\": 3, \"西瓜\": 3}";
vocabId = demo.createAsrVocab(name, description, wordWeights);
if (vocabId != null) {
System.out.println("創建詞表成功，詞表Id：" + vocabId);
}
else {
System.out.println("創建詞表失敗！");
return;
}
/**
* 獲取詞表
*/
Vocab vocab = demo.getAsrVocab(vocabId);
if (vocab != null) {
System.out.println("獲取詞表成功：" + JSONObject.toJSONString(vocab));
}
else {
System.out.println("獲取詞表失敗！");
}
/**
* 更新詞表
*/
name = "測試詞表2";
description = "測試詞表描述2";
wordWeights = "{\"蘋果\": 2, \"西瓜\": 2}";
boolean isUpdated = demo.updateAsrVocab(vocabId, name, description, wordWeights);
if (isUpdated) {
System.out.println("更新詞表成功：" + JSONObject.toJSONString(demo.getAsrVocab(vocabId)));
}
else {
System.out.println("更新詞表失敗！");
}
/**
* 刪除詞表
*/
boolean isDeleted = demo.deleteAsrVocab(vocabId);
if (isDeleted) {
System.out.println("刪除詞表成功！");
}
else {
System.out.println("刪除詞表失敗！");
}
/**
* 列舉所有詞表
*/
// 創建多個詞表
for (int i = 0; i < 10; i++) {
name = "測試詞表_" + String.valueOf(i);
description = "測試詞表描述_" + String.valueOf(i);
JSONObject jsonObject = new JSONObject();
jsonObject.put("蘋果", 2);
jsonObject.put("西瓜", 2);
wordWeights = jsonObject.toJSONString();
demo.createAsrVocab(name, description, wordWeights);
}
// 列舉創建的詞表
Page page = demo.listAsrVocab();
if (page != null) {
System.out.println("列舉詞表成功：" + JSONObject.toJSONString(page));
}
else {
System.out.println("列舉詞表失敗！");
return;
}
// 刪除所有的詞表
for (int i = 0; i < page.Content.size(); i++) {
demo.deleteAsrVocab(page.Content.get(i).Id);
}
page = demo.listAsrVocab();
if (page != null) {
System.out.println("刪除所有詞表：" + JSONObject.toJSONString(page));
}
}
}