1# @ohos.security.asset (关键资产存储服务) 2 3关键资产存储服务提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。 4 5> **说明：** 6> 7> 本模块首批接口从API version 11 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```typescript 12import { asset } from '@kit.AssetStoreKit'; 13``` 14 15## asset.add 16 17add(attributes: AssetMap): Promise\<void> 18 19新增一条关键资产，使用Promise方式异步返回结果。 20 21如果要设置[IS_PERSISTENT](#tag)属性，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。 22 23**系统能力：** SystemCapability.Security.Asset 24 25| 参数名 | 类型 | 必填 | 说明 | 26| ---------- | -------- | ---- | ------------------------------------------------------------ | 27| attributes | [AssetMap](#assetmap) | 是 | 待新增关键资产的属性集合，包括关键资产明文、访问控制属性、自定义数据等。 | 28 29**返回值：** 30 31| 类型 | 说明 | 32| ------------- | ----------------------- | 33| Promise\<void> | Promise对象，无返回值。 | 34 35**错误码：** 36 37以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 38 39| 错误码ID | 错误信息 | 40| -------- | ---------------------------------------------------------- | 41| 201 | The caller doesn't have the permission. | 42| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 43| 24000001 | The ASSET service is unavailable. | 44| 24000003 | The asset already exists. | 45| 24000005 | The screen lock status does not match. | 46| 24000006 | Insufficient memory. | 47| 24000007 | The asset is corrupted. | 48| 24000008 | The database operation failed. | 49| 24000009 | The cryptography operation failed. | 50| 24000010 | IPC failed. | 51| 24000011 | Calling the Bundle Manager service failed. | 52| 24000012 | Calling the OS Account service failed. | 53| 24000013 | Calling the Access Token service failed. | 54| 24000014 | The file operation failed. | 55| 24000015 | Getting the system time failed. | 56 57**示例代码：** 58 59```typescript 60import { asset } from '@kit.AssetStoreKit'; 61import { util } from '@kit.ArkTS'; 62import { BusinessError } from '@kit.BasicServicesKit'; 63 64function stringToArray(str: string): Uint8Array { 65 let textEncoder = new util.TextEncoder(); 66 return textEncoder.encodeInto(str); 67} 68 69let attr: asset.AssetMap = new Map(); 70attr.set(asset.Tag.SECRET, stringToArray('demo_pwd')); 71attr.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 72attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED); 73attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 74try { 75 asset.add(attr).then(() => { 76 console.info(`Asset added successfully.`); 77 }).catch((err: BusinessError) => { 78 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 79 }) 80} catch (error) { 81 let err = error as BusinessError; 82 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 83} 84``` 85 86## asset.addSync<sup>12+</sup> 87 88addSync(attributes: AssetMap): void 89 90新增一条关键资产，使用同步方式返回结果。 91 92如果要设置[IS_PERSISTENT](#tag)属性，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。 93 94**系统能力：** SystemCapability.Security.Asset 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ---------- | -------- | ---- | ------------------------------------------------------------ | 98| attributes | [AssetMap](#assetmap) | 是 | 待新增关键资产的属性集合，包括关键资产明文、访问控制属性、自定义数据等。 | 99 100**错误码：** 101 102以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 103 104| 错误码ID | 错误信息 | 105| -------- | ---------------------------------------------------------- | 106| 201 | The caller doesn't have the permission. | 107| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 108| 24000001 | The ASSET service is unavailable. | 109| 24000003 | The asset already exists. | 110| 24000005 | The screen lock status does not match. | 111| 24000006 | Insufficient memory. | 112| 24000007 | The asset is corrupted. | 113| 24000008 | The database operation failed. | 114| 24000009 | The cryptography operation failed. | 115| 24000010 | IPC failed. | 116| 24000011 | Calling the Bundle Manager service failed. | 117| 24000012 | Calling the OS Account service failed. | 118| 24000013 | Calling the Access Token service failed. | 119| 24000014 | The file operation failed. | 120| 24000015 | Getting the system time failed. | 121 122**示例代码：** 123 124```typescript 125import { asset } from '@kit.AssetStoreKit'; 126import { util } from '@kit.ArkTS'; 127import { BusinessError } from '@kit.BasicServicesKit'; 128 129function stringToArray(str: string): Uint8Array { 130 let textEncoder = new util.TextEncoder(); 131 return textEncoder.encodeInto(str); 132} 133 134let attr: asset.AssetMap = new Map(); 135attr.set(asset.Tag.SECRET, stringToArray('demo_pwd')); 136attr.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 137attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED); 138attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 139try { 140 asset.addSync(attr); 141} catch (error) { 142 let err = error as BusinessError; 143 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 144} 145``` 146 147## asset.remove 148 149remove(query: AssetMap): Promise\<void> 150 151删除符合条件的一条或多条关键资产，使用Promise方式异步返回结果。 152 153**系统能力：** SystemCapability.Security.Asset 154 155| 参数名 | 类型 | 必填 | 说明 | 156| ------ | -------- | ---- | ------------------------------------------------------ | 157| query | [AssetMap](#assetmap) | 是 | 待删除关键资产的搜索条件，如别名、访问控制属性、自定义数据等。 | 158 159**返回值：** 160 161| 类型 | 说明 | 162| ------------- | ----------------------- | 163| Promise\<void> | Promise对象，无返回值。 | 164 165**错误码：** 166 167以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 168 169| 错误码ID | 错误信息 | 170| -------- | ---------------------------------------------------------- | 171| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 172| 24000001 | The ASSET service is unavailable. | 173| 24000002 | The asset is not found. | 174| 24000006 | Insufficient memory. | 175| 24000007 | The asset is corrupted. | 176| 24000008 | The database operation failed. | 177| 24000010 | IPC failed. | 178| 24000011 | Calling the Bundle Manager service failed. | 179| 24000012 | Calling the OS Account service failed. | 180| 24000013 | Calling the Access Token service failed. | 181| 24000015 | Getting the system time failed. | 182 183**示例代码：** 184 185```typescript 186import { asset } from '@kit.AssetStoreKit'; 187import { util } from '@kit.ArkTS'; 188import { BusinessError } from '@kit.BasicServicesKit'; 189 190function stringToArray(str: string): Uint8Array { 191 let textEncoder = new util.TextEncoder(); 192 return textEncoder.encodeInto(str); 193} 194 195let query: asset.AssetMap = new Map(); 196query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 197try { 198 asset.remove(query).then(() => { 199 console.info(`Asset removed successfully.`); 200 }).catch((err: BusinessError) => { 201 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 202 }); 203} catch (error) { 204 let err = error as BusinessError; 205 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 206} 207``` 208 209## asset.removeSync<sup>12+</sup> 210 211removeSync(query: AssetMap): void 212 213删除符合条件的一条或多条关键资产，使用同步方式。 214 215**系统能力：** SystemCapability.Security.Asset 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------ | -------- | ---- | ------------------------------------------------------ | 219| query | [AssetMap](#assetmap) | 是 | 待删除关键资产的搜索条件，如别名、访问控制属性、自定义数据等。 | 220 221**错误码：** 222 223以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 224 225| 错误码ID | 错误信息 | 226| -------- | ---------------------------------------------------------- | 227| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 228| 24000001 | The ASSET service is unavailable. | 229| 24000002 | The asset is not found. | 230| 24000006 | Insufficient memory. | 231| 24000007 | The asset is corrupted. | 232| 24000008 | The database operation failed. | 233| 24000010 | IPC failed. | 234| 24000011 | Calling the Bundle Manager service failed. | 235| 24000012 | Calling the OS Account service failed. | 236| 24000013 | Calling the Access Token service failed. | 237| 24000015 | Getting the system time failed. | 238 239**示例代码：** 240 241```typescript 242import { asset } from '@kit.AssetStoreKit'; 243import { util } from '@kit.ArkTS'; 244import { BusinessError } from '@kit.BasicServicesKit'; 245 246function stringToArray(str: string): Uint8Array { 247 let textEncoder = new util.TextEncoder(); 248 return textEncoder.encodeInto(str); 249} 250 251let query: asset.AssetMap = new Map(); 252query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 253try { 254 asset.removeSync(query); 255} catch (error) { 256 let err = error as BusinessError; 257 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 258} 259``` 260 261## asset.update 262 263update(query: AssetMap, attributesToUpdate: AssetMap): Promise\<void> 264 265更新符合条件的一条关键资产，使用Promise方式异步返回结果。 266 267**系统能力：** SystemCapability.Security.Asset 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------------------ | -------- | ---- | ------------------------------------------------------------ | 271| query | [AssetMap](#assetmap) | 是 | 待更新关键资产的搜索条件，如关键资产别名、访问控制属性、自定义数据等。 | 272| attributesToUpdate | [AssetMap](#assetmap) | 是 | 待更新关键资产的属性集合，如关键资产明文、自定义数据等。 | 273 274**返回值：** 275 276| 类型 | 说明 | 277| ------------- | ----------------------- | 278| Promise\<void> | Promise对象，无返回值。 | 279 280**错误码：** 281 282以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 283 284| 错误码ID | 错误信息 | 285| -------- | ---------------------------------------------------------- | 286| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 287| 24000001 | The ASSET service is unavailable. | 288| 24000002 | The asset is not found. | 289| 24000005 | The screen lock status does not match. | 290| 24000006 | Insufficient memory. | 291| 24000007 | The asset is corrupted. | 292| 24000008 | The database operation failed. | 293| 24000009 | The cryptography operation failed. | 294| 24000010 | IPC failed. | 295| 24000011 | Calling the Bundle Manager service failed. | 296| 24000012 | Calling the OS Account service failed. | 297| 24000013 | Calling the Access Token service failed. | 298| 24000015 | Getting the system time failed. | 299 300**示例代码：** 301 302```typescript 303import { asset } from '@kit.AssetStoreKit'; 304import { util } from '@kit.ArkTS'; 305import { BusinessError } from '@kit.BasicServicesKit'; 306 307function stringToArray(str: string): Uint8Array { 308 let textEncoder = new util.TextEncoder(); 309 return textEncoder.encodeInto(str); 310} 311 312let query: asset.AssetMap = new Map(); 313query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 314let attrsToUpdate: asset.AssetMap = new Map(); 315attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new')); 316try { 317 asset.update(query, attrsToUpdate).then(() => { 318 console.info(`Asset updated successfully.`); 319 }).catch((err: BusinessError) => { 320 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 321 }); 322} catch (error) { 323 let err = error as BusinessError; 324 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 325} 326``` 327 328## asset.updateSync<sup>12+</sup> 329 330updateSync(query: AssetMap, attributesToUpdate: AssetMap): void 331 332更新符合条件的一条关键资产，使用同步方式返回结果。 333 334**系统能力：** SystemCapability.Security.Asset 335 336| 参数名 | 类型 | 必填 | 说明 | 337| ------------------ | -------- | ---- | ------------------------------------------------------------ | 338| query | [AssetMap](#assetmap) | 是 | 待更新关键资产的搜索条件，如关键资产别名、访问控制属性、自定义数据等。 | 339| attributesToUpdate | [AssetMap](#assetmap) | 是 | 待更新关键资产的属性集合，如关键资产明文、自定义数据等。 | 340 341**错误码：** 342 343以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 344 345| 错误码ID | 错误信息 | 346| -------- | ---------------------------------------------------------- | 347| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 348| 24000001 | The ASSET service is unavailable. | 349| 24000002 | The asset is not found. | 350| 24000005 | The screen lock status does not match. | 351| 24000006 | Insufficient memory. | 352| 24000007 | The asset is corrupted. | 353| 24000008 | The database operation failed. | 354| 24000009 | The cryptography operation failed. | 355| 24000010 | IPC failed. | 356| 24000011 | Calling the Bundle Manager service failed. | 357| 24000012 | Calling the OS Account service failed. | 358| 24000013 | Calling the Access Token service failed. | 359| 24000015 | Getting the system time failed. | 360 361**示例代码：** 362 363```typescript 364import { asset } from '@kit.AssetStoreKit'; 365import { util } from '@kit.ArkTS'; 366import { BusinessError } from '@kit.BasicServicesKit'; 367 368function stringToArray(str: string): Uint8Array { 369 let textEncoder = new util.TextEncoder(); 370 return textEncoder.encodeInto(str); 371} 372 373let query: asset.AssetMap = new Map(); 374query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 375let attrsToUpdate: asset.AssetMap = new Map(); 376attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new')); 377try { 378 asset.updateSync(query, attrsToUpdate); 379} catch (error) { 380 let err = error as BusinessError; 381 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 382} 383``` 384 385## asset.preQuery 386 387preQuery(query: AssetMap): Promise\<Uint8Array> 388 389查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用[asset.query](#assetquery)、[asset.postQuery](#assetpostquery)。使用Promise方式异步返回结果。 390 391**系统能力：** SystemCapability.Security.Asset 392 393| 参数名 | 类型 | 必填 | 说明 | 394| ------ | -------- | ---- | ------------------------------------------------------ | 395| query | [AssetMap](#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 396 397**返回值：** 398 399| 类型 | 说明 | 400| ------------------- | ----------------------------------------------------- | 401| Promise\<Uint8Array> | Promise对象，返回挑战值。<br>**说明：** 挑战值用于后续用户认证。 | 402 403**错误码：** 404 405以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 406 407| 错误码ID | 错误信息 | 408| -------- | ------------------------------------------------------------ | 409| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 410| 24000001 | The ASSET service is unavailable. | 411| 24000002 | The asset is not found. | 412| 24000005 | The screen lock status does not match. | 413| 24000006 | Insufficient memory. | 414| 24000007 | The asset is corrupted. | 415| 24000008 | The database operation failed. | 416| 24000009 | The cryptography operation failed. | 417| 24000010 | IPC failed. | 418| 24000011 | Calling the Bundle Manager service failed. | 419| 24000012 | Calling the OS Account service failed. | 420| 24000013 | Calling the Access Token service failed. | 421| 24000016 | The cache exceeds the limit. | 422| 24000017 | The capability is not supported. | 423 424**示例代码：** 425 426```typescript 427import { asset } from '@kit.AssetStoreKit'; 428import { util } from '@kit.ArkTS'; 429import { BusinessError } from '@kit.BasicServicesKit'; 430 431function stringToArray(str: string): Uint8Array { 432 let textEncoder = new util.TextEncoder(); 433 return textEncoder.encodeInto(str); 434} 435 436let query: asset.AssetMap = new Map(); 437query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 438try { 439 asset.preQuery(query).then((challenge: Uint8Array) => { 440 console.info(`Succeeded in pre-querying Asset.`); 441 }).catch ((err: BusinessError) => { 442 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 443 }); 444} catch (error) { 445 let err = error as BusinessError; 446 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 447} 448``` 449 450## asset.preQuerySync<sup>12+</sup> 451 452preQuerySync(query: AssetMap): Uint8Array 453 454查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用[asset.querySync](#assetquerysync12)、[asset.postQuerySync](#assetpostquerysync12)。使用同步方式返回结果。 455 456**系统能力：** SystemCapability.Security.Asset 457 458| 参数名 | 类型 | 必填 | 说明 | 459| ------ | -------- | ---- | ------------------------------------------------------ | 460| query | [AssetMap](#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 461 462**返回值：** 463 464| 类型 | 说明 | 465| ------------------- | ----------------------------------------------------- | 466| Uint8Array | 挑战值。<br>**说明：** 挑战值用于后续用户认证。 | 467 468**错误码：** 469 470以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 471 472| 错误码ID | 错误信息 | 473| -------- | ------------------------------------------------------------ | 474| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 475| 24000001 | The ASSET service is unavailable. | 476| 24000002 | The asset is not found. | 477| 24000005 | The screen lock status does not match. | 478| 24000006 | Insufficient memory. | 479| 24000007 | The asset is corrupted. | 480| 24000008 | The database operation failed. | 481| 24000009 | The cryptography operation failed. | 482| 24000010 | IPC failed. | 483| 24000011 | Calling the Bundle Manager service failed. | 484| 24000012 | Calling the OS Account service failed. | 485| 24000013 | Calling the Access Token service failed. | 486| 24000016 | The cache exceeds the limit. | 487| 24000017 | The capability is not supported. | 488 489**示例代码：** 490 491```typescript 492import { asset } from '@kit.AssetStoreKit'; 493import { util } from '@kit.ArkTS'; 494import { BusinessError } from '@kit.BasicServicesKit'; 495 496function stringToArray(str: string): Uint8Array { 497 let textEncoder = new util.TextEncoder(); 498 return textEncoder.encodeInto(str); 499} 500 501let query: asset.AssetMap = new Map(); 502query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 503try { 504 let challenge: Uint8Array = asset.preQuerySync(query); 505} catch (error) { 506 let err = error as BusinessError; 507 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 508} 509``` 510 511## asset.query 512 513query(query: AssetMap): Promise\<Array\<AssetMap>> 514 515查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用[asset.preQuery](#assetprequery)，在本函数后调用[asset.postQuery](#assetpostquery)，开发步骤请参考[开发指导](../../security/AssetStoreKit/asset-js-query-auth.md)。使用Promise回调异步返回结果。 516 517**系统能力：** SystemCapability.Security.Asset 518 519| 参数名 | 类型 | 必填 | 说明 | 520| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 521| query | [AssetMap](#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 522 523**返回值：** 524 525| 类型 | 说明 | 526| ------------------------ | ------------------------------------- | 527| Promise\<Array\<AssetMap>> | Promise对象，返回查询结果列表。 | 528 529**错误码：** 530 531以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 532 533| 错误码ID | 错误信息 | 534| -------- | ---------------------------------------------------------- | 535| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 536| 24000001 | The ASSET service is unavailable. | 537| 24000002 | The asset is not found. | 538| 24000004 | Access denied. | 539| 24000005 | The screen lock status does not match. | 540| 24000006 | Insufficient memory. | 541| 24000007 | The asset is corrupted. | 542| 24000008 | The database operation failed. | 543| 24000009 | The cryptography operation failed. | 544| 24000010 | IPC failed. | 545| 24000011 | Calling the Bundle Manager service failed. | 546| 24000012 | Calling the OS Account service failed. | 547| 24000013 | Calling the Access Token service failed. | 548| 24000017 | The capability is not supported. | 549 550**示例代码：** 551 552```typescript 553import { asset } from '@kit.AssetStoreKit'; 554import { util } from '@kit.ArkTS'; 555import { BusinessError } from '@kit.BasicServicesKit'; 556 557function stringToArray(str: string): Uint8Array { 558 let textEncoder = new util.TextEncoder(); 559 return textEncoder.encodeInto(str); 560} 561 562let query: asset.AssetMap = new Map(); 563query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 564try { 565 asset.query(query).then((res: Array<asset.AssetMap>) => { 566 for (let i = 0; i < res.length; i++) { 567 // parse the attribute. 568 let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number; 569 } 570 console.info(`Asset query succeeded.`); 571 }).catch ((err: BusinessError) => { 572 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 573 }); 574} catch (error) { 575 let err = error as BusinessError; 576 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 577} 578``` 579 580## asset.querySync<sup>12+</sup> 581 582querySync(query: AssetMap): Array\<AssetMap> 583 584查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用[asset.preQuerySync](#assetprequerysync12)，在本函数后调用[asset.postQuerySync](#assetpostquerysync12)，开发步骤请参考[开发指导](../../security/AssetStoreKit/asset-js-query-auth.md)。使用同步方式返回结果。 585 586**系统能力：** SystemCapability.Security.Asset 587 588| 参数名 | 类型 | 必填 | 说明 | 589| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 590| query | [AssetMap](#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 591 592**返回值：** 593 594| 类型 | 说明 | 595| ------------------------ | ------------------------------------- | 596| Array\<AssetMap> | 查询结果列表。 | 597 598**错误码：** 599 600以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 601 602| 错误码ID | 错误信息 | 603| -------- | ---------------------------------------------------------- | 604| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 605| 24000001 | The ASSET service is unavailable. | 606| 24000002 | The asset is not found. | 607| 24000004 | Access denied. | 608| 24000005 | The screen lock status does not match. | 609| 24000006 | Insufficient memory. | 610| 24000007 | The asset is corrupted. | 611| 24000008 | The database operation failed. | 612| 24000009 | The cryptography operation failed. | 613| 24000010 | IPC failed. | 614| 24000011 | Calling the Bundle Manager service failed. | 615| 24000012 | Calling the OS Account service failed. | 616| 24000013 | Calling the Access Token service failed. | 617| 24000017 | The capability is not supported. | 618 619**示例代码：** 620 621```typescript 622import { asset } from '@kit.AssetStoreKit'; 623import { util } from '@kit.ArkTS'; 624import { BusinessError } from '@kit.BasicServicesKit'; 625 626function stringToArray(str: string): Uint8Array { 627 let textEncoder = new util.TextEncoder(); 628 return textEncoder.encodeInto(str); 629} 630 631let query: asset.AssetMap = new Map(); 632query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 633try { 634 let res: Array<asset.AssetMap> = asset.querySync(query); 635 let accessibility: number; 636 for (let i = 0; i < res.length; i++) { 637 // parse the attribute. 638 if (res[i] != null) { 639 accessibility = res[i].get(asset.Tag.ACCESSIBILITY) as number; 640 } 641 } 642} catch (error) { 643 let err = error as BusinessError; 644 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 645} 646``` 647 648## asset.postQuery 649 650postQuery(handle: AssetMap): Promise\<void> 651 652查询的后置处理，用于需要用户认证的关键资产。需与[asset.preQuery](#assetprequery)函数成对出现。使用Promise方式异步返回结果。 653 654**系统能力：** SystemCapability.Security.Asset 655 656| 参数名 | 类型 | 必填 | 说明 | 657| ------ | -------- | ---- | ------------------------------------------------------------ | 658| handle | [AssetMap](#assetmap) | 是 | 待处理的查询句柄，当前包含[asset.preQuery](#assetprequery)执行成功返回的挑战值。 | 659 660**返回值：** 661 662| 类型 | 说明 | 663| ------------- | ----------------------- | 664| Promise\<void> | Promise对象，无返回值。 | 665 666**错误码：** 667 668以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 669 670| 错误码ID | 错误信息 | 671| -------- | ---------------------------------------------------------- | 672| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 673| 24000001 | The ASSET service is unavailable. | 674| 24000006 | Insufficient memory. | 675| 24000010 | IPC failed. | 676| 24000011 | Calling the Bundle Manager service failed. | 677| 24000012 | Calling the OS Account service failed. | 678| 24000013 | Calling the Access Token service failed. | 679 680**示例代码：** 681 682```typescript 683import { asset } from '@kit.AssetStoreKit'; 684import { BusinessError } from '@kit.BasicServicesKit'; 685 686let handle: asset.AssetMap = new Map(); 687// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQuery执行成功返回的挑战值 688handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32)); 689try { 690 asset.postQuery(handle).then(() => { 691 console.info(`Succeeded in post-querying Asset.`); 692 }).catch ((err: BusinessError) => { 693 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 694 }); 695} catch (error) { 696 let err = error as BusinessError; 697 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 698} 699``` 700 701## asset.postQuerySync<sup>12+</sup> 702 703postQuerySync(handle: AssetMap): void 704 705查询的后置处理，用于需要用户认证的关键资产。需与[asset.preQuerySync](#assetprequerysync12)函数成对出现。使用同步方式返回结果。 706 707**系统能力：** SystemCapability.Security.Asset 708 709| 参数名 | 类型 | 必填 | 说明 | 710| ------ | -------- | ---- | ------------------------------------------------------------ | 711| handle | [AssetMap](#assetmap) | 是 | 待处理的查询句柄，当前包含[asset.preQuerySync](#assetprequerysync12)执行成功返回的挑战值。 | 712 713**错误码：** 714 715以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 716 717| 错误码ID | 错误信息 | 718| -------- | ---------------------------------------------------------- | 719| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 720| 24000001 | The ASSET service is unavailable. | 721| 24000006 | Insufficient memory. | 722| 24000010 | IPC failed. | 723| 24000011 | Calling the Bundle Manager service failed. | 724| 24000012 | Calling the OS Account service failed. | 725| 24000013 | Calling the Access Token service failed. | 726 727**示例代码：** 728 729```typescript 730import { asset } from '@kit.AssetStoreKit'; 731import { BusinessError } from '@kit.BasicServicesKit'; 732 733let handle: asset.AssetMap = new Map(); 734// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQuerySync执行成功返回的挑战值 735handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32)); 736try { 737 asset.postQuerySync(handle) 738} catch (error) { 739 let err = error as BusinessError; 740 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 741} 742``` 743 744## TagType 745 746枚举，关键资产属性支持的数据类型。 747 748**系统能力：** SystemCapability.Security.Asset 749 750| 名称 | 值 | 说明 | 751| ------ | ---------- | ---------------------------------------- | 752| BOOL | 0x01 << 28 | 标识关键资产属性对应的数据类型是布尔 | 753| NUMBER | 0x02 << 28 | 标识关键资产属性对应的数据类型是整型 | 754| BYTES | 0x03 << 28 | 标识关键资产属性对应的数据类型是字节数组 | 755 756## Tag 757 758枚举，关键资产支持的属性名称类型，用作[AssetMap](#assetmap)的键。 759 760**系统能力：** SystemCapability.Security.Asset 761 762> **说明：** 763> 764> 以下为Tag类型的全量枚举值，每个接口可传的Tag枚举及对应的Value取值范围不同，详见[各个场景的开发指导](../../security/AssetStoreKit/asset-store-kit-overview.md)。 765 766| 名称 | 值 | 说明 | 767| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 768| SECRET | TagType.BYTES | 0x01 | 关键资产明文 | 769| ALIAS | TagType.BYTES | 0x02 | 关键资产别名，每条关键资产的唯一索引 | 770| ACCESSIBILITY | TagType.NUMBER | 0x03 | 基于锁屏状态的访问控制 | 771| REQUIRE_PASSWORD_SET | TagType.BOOL | 0x04 | 是否仅在设置了锁屏密码的情况下，可访问关键资产 | 772| AUTH_TYPE | TagType.NUMBER | 0x05 | 访问关键资产所需的用户认证类型 | 773| AUTH_VALIDITY_PERIOD | TagType.NUMBER | 0x06 | 用户认证的有效期 | 774| AUTH_CHALLENGE | TagType.BYTES | 0x07 | 用户认证的挑战值 | 775| AUTH_TOKEN | TagType.BYTES | 0x08 | 用户认证通过的授权令牌 | 776| SYNC_TYPE | TagType.NUMBER | 0x10 | 关键资产支持的同步类型 | 777| IS_PERSISTENT | TagType.BOOL | 0x11 | 在应用卸载时是否需要保留关键资产 | 778| DATA_LABEL_CRITICAL_1 | TagType.BYTES | 0x20 | 关键资产附属信息，内容由业务自定义且**有完整性保护** | 779| DATA_LABEL_CRITICAL_2 | TagType.BYTES | 0x21 | 关键资产附属信息，内容由业务自定义且**有完整性保护** | 780| DATA_LABEL_CRITICAL_3 | TagType.BYTES | 0x22 | 关键资产附属信息，内容由业务自定义且**有完整性保护** | 781| DATA_LABEL_CRITICAL_4 | TagType.BYTES | 0x23 | 关键资产附属信息，内容由业务自定义且**有完整性保护** | 782| DATA_LABEL_NORMAL_1 | TagType.BYTES | 0x30 | 关键资产附属信息，内容由业务自定义且**无完整性保护** | 783| DATA_LABEL_NORMAL_2 | TagType.BYTES | 0x31 | 关键资产附属信息，内容由业务自定义且**无完整性保护** | 784| DATA_LABEL_NORMAL_3 | TagType.BYTES | 0x32 | 关键资产附属信息，内容由业务自定义且**无完整性保护** | 785| DATA_LABEL_NORMAL_4 | TagType.BYTES | 0x33 | 关键资产附属信息，内容由业务自定义且**无完整性保护** | 786| DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | TagType.BYTES | 0x34 | 关键资产附属的本地信息，内容由业务自定义且**无完整性保护**，该项信息不会进行同步。 | 787| DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | TagType.BYTES | 0x35 | 关键资产附属的本地信息，内容由业务自定义且**无完整性保护**，该项信息不会进行同步。 | 788| DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | TagType.BYTES | 0x36 | 关键资产附属的本地信息，内容由业务自定义且**无完整性保护**，该项信息不会进行同步。 | 789| DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | TagType.BYTES | 0x37 | 关键资产附属的本地信息，内容由业务自定义且**无完整性保护**，该项信息不会进行同步。 | 790| RETURN_TYPE | TagType.NUMBER | 0x40 | 关键资产查询返回的结果类型 | 791| RETURN_LIMIT | TagType.NUMBER | 0x41 | 关键资产查询返回的结果数量 | 792| RETURN_OFFSET | TagType.NUMBER | 0x42 | 关键资产查询返回的结果偏移量<br>**说明：** 用于分批查询场景，指定从第几个开始返回 | 793| RETURN_ORDERED_BY | TagType.NUMBER | 0x43 | 关键资产查询返回的结果排序依据，仅支持按照附属信息排序<br>**说明：** 默认按照关键资产新增的顺序返回。 | 794| CONFLICT_RESOLUTION | TagType.NUMBER | 0x44 | 新增关键资产时的冲突（如：别名相同）处理策略 | 795| UPDATE_TIME<sup>12+</sup> | TagType.BYTES | 0x45 | 数据的更新时间（时间戳形式） | 796| OPERATION_TYPE<sup>12+</sup> | TagType.NUMBER | 0x46 | 附加的操作类型 | 797| REQUIRE_ATTR_ENCRYPTED<sup>13+</sup> | TagType.BOOL | 0x47 | 是否加密业务自定义附属信息 | 798 799## Value 800 801type Value = boolean | number | Uint8Array; 802 803关键资产属性的内容，用作[AssetMap](#assetmap)的值。 804 805**系统能力：** SystemCapability.Security.Asset 806 807## AssetMap 808 809type AssetMap = Map\<Tag, Value> 810 811关键资产属性的键-值对集合。 812 813**系统能力：** SystemCapability.Security.Asset 814 815## Accessibility 816 817枚举，关键资产基于锁屏状态的访问控制类型。 818 819**系统能力：** SystemCapability.Security.Asset 820 821| 名称 | 值 | 说明 | 822| --------------------- | ---- | ------------------------------------------------------------ | 823| DEVICE_POWERED_ON | 0 | 开机后可访问 | 824| DEVICE_FIRST_UNLOCKED | 1 | 首次解锁后可访问<br>**备注：** 未设置锁屏密码时，等同于开机后可访问 | 825| DEVICE_UNLOCKED | 2 | 解锁状态时可访问<br/>**备注：** 未设置锁屏密码时，等同于开机后可访问 | 826 827## AuthType 828 829枚举，关键资产支持的用户认证类型。 830 831**系统能力：** SystemCapability.Security.Asset 832 833| 名称 | 值 | 说明 | 834| ---- | ---- | ------------------------------------------------------------ | 835| NONE | 0 | 访问关键资产前无需用户认证。 | 836| ANY | 255 | 任意一种用户认证方式（PIN码、人脸、指纹等）通过后，均可访问关键资产。 | 837 838## SyncType 839 840枚举，关键资产支持的同步类型。 841 842> **说明：** 843> 844> 本字段属于能力预埋，当前不支持同步。 845 846**系统能力：** SystemCapability.Security.Asset 847 848| 名称 | 值 | 说明 | 849| ----------------------------- | ------ | ------------------------------------------------ | 850| NEVER | 0 | 不允许同步关键资产。 | 851| THIS_DEVICE | 1 << 0 | 只在本设备进行同步，如仅在本设备还原的备份场景。 | 852| TRUSTED_DEVICE | 1 << 1 | 只在可信设备间进行同步，如克隆场景。 | 853| TRUSTED_ACCOUNT<sup>12+</sup> | 1 << 2 | 只在登录可信账号的设备间进行同步，如云同步场景。 | 854 855## ReturnType 856 857枚举，关键资产查询返回的结果类型。 858 859**系统能力：** SystemCapability.Security.Asset 860 861| 名称 | 值 | 说明 | 862| ---------- | ---- | ------------------------------------------------------------ | 863| ALL | 0 | 返回关键资产明文及属性。<br/>**说明：** 查询单条关键资产明文时，需设置此类型。 | 864| ATTRIBUTES | 1 | 返回关键资产属性，不含关键资产明文。<br>**备注：** 批量查询关键资产属性时，需设置此类型。 | 865 866## ConflictResolution 867 868枚举，新增关键资产时的冲突（如：别名相同）处理策略。 869 870**系统能力：** SystemCapability.Security.Asset 871 872| 名称 | 值 | 说明 | 873| ----------- | ---- | ---------------------------- | 874| OVERWRITE | 0 | 覆盖原有的关键资产。 | 875| THROW_ERROR | 1 | 抛出异常，由业务进行后续处理。 | 876 877## OperationType<sup>12+</sup> 878 879枚举，附属的操作类型。 880 881**系统能力：** SystemCapability.Security.Asset 882 883| 名称 | 值 | 说明 | 884| ----------- | ---- | ------------------ | 885| NEED_SYNC | 0 | 需要进行同步操作。 | 886| NEED_LOGOUT | 1 | 需要进行登出操作。 | 887 888## ErrorCode 889 890表示错误码的枚举。 891 892**系统能力：** SystemCapability.Security.Asset 893 894| 名称 | 值 | 说明 | 895| -------------------------- | ----- | ---- | 896| PERMISSION_DENIED | 201 |调用方无权限。| 897| NOT_SYSTEM_APPLICATION<sup>12+</sup> | 202 |调用方不是一个系统应用。| 898| INVALID_ARGUMENT | 401 |参数错误。| 899| SERVICE_UNAVAILABLE | 24000001 |关键资产服务不可用。| 900| NOT_FOUND | 24000002 |未找到关键资产。| 901| DUPLICATED | 24000003 |关键资产已存在。| 902| ACCESS_DENIED | 24000004 |拒绝访问关键资产。| 903| STATUS_MISMATCH | 24000005 |锁屏状态不匹配。| 904| OUT_OF_MEMORY | 24000006 |系统内存不足。| 905| DATA_CORRUPTED | 24000007 |关键资产损坏。| 906| DATABASE_ERROR | 24000008 |数据库操作失败。| 907| CRYPTO_ERROR | 24000009 |算法库操作失败。| 908| IPC_ERROR | 24000010 |进程通信错误。| 909| BMS_ERROR | 24000011 |包管理服务异常。| 910| ACCOUNT_ERROR | 24000012 |账号系统异常。| 911| ACCESS_TOKEN_ERROR | 24000013 |访问控制服务异常。| 912| FILE_OPERATION_ERROR | 24000014 |文件操作失败。| 913| GET_SYSTEM_TIME_ERROR | 24000015 |获取系统时间失败。| 914| LIMIT_EXCEEDED | 24000016 |缓存数量超限。| 915| UNSUPPORTED | 24000017 |该子功能不支持。|