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