1# @ohos.account.distributedAccount (分布式账号管理)(系统接口)
2
3本模块提供管理分布式账号的一些基础功能，主要包括查询和更新账号登录状态。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.account.distributedAccount (分布式账号管理)](js-apis-distributed-account.md)。
9
10## 导入模块
11
12```ts
13import { distributedAccount } from '@kit.BasicServicesKit';
14```
15
16## DistributedAccountAbility
17
18提供查询和更新分布式账号登录状态方法(需要先获取分布式账号的单实例对象)。
19
20### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
21
22getOsAccountDistributedInfoByLocalId(localId: number, callback: AsyncCallback&lt;DistributedInfo&gt;): void
23
24获取指定系统账号的分布式信息。使用callback异步回调。
25
26**系统接口：** 此接口为系统接口。
27
28**系统能力：** SystemCapability.Account.OsAccount
29
30**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
31
32**参数：**
33
34  | 参数名 | 类型 | 必填 | 说明 |
35  | -------- | -------- | -------- | -------- |
36  | localId | number | 是 | 系统账号ID。 |
37  | callback | AsyncCallback&lt;[DistributedInfo](js-apis-distributed-account.md#distributedinfo)&gt; | 是 | 回调参数。当获取分布式账号信息成功，err为undefined，data为获取到的分布式账号信息对象；否则为错误对象。 |
38
39**错误码：**
40
41| 错误码ID | 错误信息|
42| -------- | ------------------- |
43| 201 | Permission denied.|
44| 202 | Not system application.|
45| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
46| 12300001 | System service exception. |
47| 12300003 | Account not found. |
48
49**示例：**
50
51```ts
52import { BusinessError } from '@kit.BasicServicesKit';
53
54const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
55try {
56  accountAbility.getOsAccountDistributedInfoByLocalId(100,
57    (err: BusinessError, data: distributedAccount.DistributedInfo) => {
58      if (err) {
59        console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
60      } else {
61        console.log('distributed information: ' + JSON.stringify(data));
62      }
63    });
64} catch (err) {
65  console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
66}
67```
68
69### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
70
71getOsAccountDistributedInfoByLocalId(localId: number): Promise&lt;DistributedInfo&gt;
72
73获取指定系统账号的分布式信息。使用Promise异步回调。
74
75**系统接口：** 此接口为系统接口。
76
77**系统能力：** SystemCapability.Account.OsAccount
78
79**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
80
81**返回值：**
82
83  | 类型 | 说明 |
84  | -------- | -------- |
85  | Promise&lt;[DistributedInfo](js-apis-distributed-account.md#distributedinfo)&gt; | Promise对象，返回分布式账号信息对象。 |
86
87**错误码：**
88
89| 错误码ID | 错误信息|
90| -------- | ------------------- |
91| 201 | Permission denied.|
92| 202 | Not system application.|
93| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
94| 12300001 | System service exception. |
95| 12300003 | Account not found. |
96
97**示例：**
98
99```ts
100import { BusinessError } from '@kit.BasicServicesKit';
101
102const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
103try {
104  accountAbility.getOsAccountDistributedInfoByLocalId(100).then((
105    data: distributedAccount.DistributedInfo) => {
106    console.log('distributed information: ' + JSON.stringify(data));
107  }).catch((err: BusinessError) => {
108    console.log('getOsAccountDistributedInfoByLocalId exception: '  + JSON.stringify(err));
109  });
110} catch (err) {
111  console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
112}
113```
114
115### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
116
117setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
118
119设置指定系统账号的分布式信息。使用callback异步回调。
120
121**系统接口：** 此接口为系统接口。
122
123**系统能力：** SystemCapability.Account.OsAccount
124
125**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
126
127**参数：**
128
129  | 参数名 | 类型 | 必填 | 说明 |
130  | -------- | -------- | -------- | -------- |
131  | localId | number | 是 | 系统账号ID。 |
132  | accountInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | 是 | 分布式账号信息。 |
133  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置指定系统账号的分布式信息成功时，err为undefined，否则为错误对象。 |
134
135**错误码：**
136
137| 错误码ID | 错误信息|
138| -------- | ------------------- |
139| 201 | Permission denied.|
140| 202 | Not system application.|
141| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
142| 12300001 | System service exception. |
143| 12300002 | Invalid distributedInfo. |
144| 12300003 | Account identified by localId or by distributedInfo not found. |
145| 12300008 | Restricted OS account. |
146
147**示例：**
148
149```ts
150import { BusinessError } from '@kit.BasicServicesKit';
151
152const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
153let accountInfo: distributedAccount.DistributedInfo =
154  {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
155try {
156  accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo, (err: BusinessError) => {
157    if (err) {
158      console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
159    } else {
160      console.log('setOsAccountDistributedInfoByLocalId successfully');
161    }
162  });
163} catch (err) {
164    console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
165}
166```
167
168### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
169
170setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo): Promise&lt;void&gt;
171
172设置指定系统账号的分布式信息。使用Promise异步回调。
173
174**系统接口：** 此接口为系统接口。
175
176**系统能力：** SystemCapability.Account.OsAccount
177
178**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
179
180**参数：**
181
182  | 参数名 | 类型 | 必填 | 说明 |
183  | -------- | -------- | -------- | -------- |
184  | localId | number | 是 | 系统账号ID。 |
185  | distributedInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | 是 | 分布式账户信息。 |
186
187**返回值：**
188
189  | 类型 | 说明 |
190  | -------- | -------- |
191  | Promise&lt;void&gt; | Promise对象，无返回结果的Promise对象。 |
192
193**错误码：**
194
195| 错误码ID | 错误信息|
196| -------- | ------------------- |
197| 201 | Permission denied.|
198| 202 | Not system application.|
199| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
200| 12300001 | System service exception. |
201| 12300002 | Invalid distributedInfo. |
202| 12300003 | Account identified by localId or by distributedInfo not found. |
203| 12300008 | Restricted OS account. |
204
205**示例：**
206
207```ts
208import { BusinessError } from '@kit.BasicServicesKit';
209
210const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
211let accountInfo: distributedAccount.DistributedInfo =
212  {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
213try {
214  accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo).then(() => {
215      console.log('setOsAccountDistributedInfoByLocalId successfully');
216  }).catch((err: BusinessError) => {
217      console.log('setOsAccountDistributedInfoByLocalId exception: '  + JSON.stringify(err));
218  });
219} catch (err) {
220    console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
221}
222```
223