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