• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 授权持久化
2<!--Kit: Core File Kit-->
3<!--Subsystem: FileManagement-->
4<!--Owner: @lvzhenjie; @hongjin-li_admin-->
5<!--Designer: @chenxi0605; @JerryH1011-->
6<!--Tester: @leiyuqian-->
7<!--Adviser: @foryourself-->
8
9## 场景介绍
10
11应用通过Picker获取临时授权，临时授权在应用退出后或者设备重启后会清除。如果应用重启或者设备重启后需要直接访问之前已访问过的文件，则对文件进行持久化授权。
12
13## 通过Picker获取临时授权并进行授权持久化
14
15通过Picker选择文件或文件夹进行临时授权，然后应用可以按需通过文件分享接口（[ohos.fileshare](../reference/apis-core-file-kit/js-apis-fileShare.md)）进行持久化授权。
16
171.应用仅临时需要访问公共目录的数据，例如：通讯类应用需要发送用户的文件或者图片。应用调用Picker的([select](../reference/apis-core-file-kit/js-apis-file-picker.md#select-3))接口选择需要发送的文件或者图片，此时应用获取到是该文件的临时访问权限，应用重启或者设备重启后，再次访问该文件则仍需使用Picker进行文件选择。
18
192.应用如果需要长期访问某个文件或目录时，可以通过Picker选择文件或文件夹进行临时授权，然后利用persistPermission接口（[ohos.fileshare.persistPermission](../reference/apis-core-file-kit/js-apis-fileShare.md#filesharepersistpermission11)）对授权进行持久化（在授权方同意被持久化的情况下），例如：文档编辑类应用本次编辑完一个用户文件，期望在历史记录中可以直接选中打开，无需再拉起Picker进行选择授权。
20
21可使用canIUse接口，确认设备是否具有以下系统能力：SystemCapability.FileManagement.AppFileService.FolderAuthorization。
22
23```ts
24if (!canIUse('SystemCapability.FileManagement.AppFileService.FolderAuthorization')) {
25    console.error('this api is not supported on this device');
26    return;
27}
28```
29
30**需要权限**
31ohos.permission.FILE_ACCESS_PERSIST，具体参考[访问控制-申请应用权限](../security/AccessToken/determine-application-mode.md)。
32
33**示例：**
34
35```ts
36import { BusinessError } from '@kit.BasicServicesKit';
37import { picker } from '@kit.CoreFileKit';
38import { fileShare } from '@kit.CoreFileKit';
39
40async function persistPermissionExample() {
41    try {
42        let DocumentSelectOptions = new picker.DocumentSelectOptions();
43        let documentPicker = new picker.DocumentViewPicker();
44        let uris = await documentPicker.select(DocumentSelectOptions);
45        let policyInfo: fileShare.PolicyInfo = {
46            uri: uris[0],
47            operationMode: fileShare.OperationMode.READ_MODE,
48        };
49        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
50        fileShare.persistPermission(policies).then(() => {
51            console.info("persistPermission successfully");
52        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
53            console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code);
54            if (err.code == 13900001 && err.data) {
55                for (let i = 0; i < err.data.length; i++) {
56                    console.error("error code : " + JSON.stringify(err.data[i].code));
57                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
58                    console.error("error reason : " + JSON.stringify(err.data[i].message));
59                }
60            }
61        });
62    } catch (error) {
63        let err: BusinessError = error as BusinessError;
64        console.error(`persistPermission failed with err, Error code: ${err.code}, message: ${err.message}`);
65    }
66}
67```
68
69> **注意**
70>
71> 1. 持久化授权文件信息建议应用在本地存储数据，供后续按需激活持久化文件。
72> 2. 持久化授权的数据存储在系统的数据库中，应用或者设备重启后需要激活已持久化的授权才可以正常使用[激活持久化授权](#激活已经持久化的权限访问文件或目录)。
73> 3. 持久化权限接口(可以使用canIUse接口进行校验能力是否可用)，且需要申请对应的权限。
74> 4. 应用在卸载时会将之前的授权数据全部清除，重新安装后需要重新授权。
75
76**备注**：C/C++持久化授权接口说明及开发指南具体参考：[OH_FileShare_PersistPermission持久化授权接口](native-fileshare-guidelines.md)。
77
783.可以通过revokePermission接口（[ohos.fileshare.revokePermission](../reference/apis-core-file-kit/js-apis-fileShare.md#filesharerevokepermission11)）对已持久化的文件取消授权，同时更新应用存储的数据以删除最近访问数据。
79
80**需要权限**
81ohos.permission.FILE_ACCESS_PERSIST，具体参考[访问控制-申请应用权限](../security/AccessToken/determine-application-mode.md)。
82
83**示例：**
84
85```ts
86import { BusinessError } from '@kit.BasicServicesKit';
87import { picker } from '@kit.CoreFileKit';
88import { fileShare } from '@kit.CoreFileKit';
89
90async function revokePermissionExample() {
91    try {
92        let uri = "file://docs/storage/Users/username/tmp.txt";
93        let policyInfo: fileShare.PolicyInfo = {
94            uri: uri,
95            operationMode: fileShare.OperationMode.READ_MODE,
96        };
97        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
98        fileShare.revokePermission(policies).then(() => {
99            console.info("revokePermission successfully");
100        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
101            console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code);
102            if (err.code == 13900001 && err.data) {
103                for (let i = 0; i < err.data.length; i++) {
104                    console.error("error code : " + JSON.stringify(err.data[i].code));
105                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
106                    console.error("error reason : " + JSON.stringify(err.data[i].message));
107                }
108            }
109        });
110    } catch (error) {
111        let err: BusinessError = error as BusinessError;
112        console.error(`revokePermission failed with err, Error code: ${err.code}, message: ${err.message}`);
113    }
114}
115```
116
117> **注意**
118>
119> 1. 示例中的URI来源自应用存储的持久化数据中。
120> 2. 建议按照使用需求去激活对应的持久化权限，不要盲目的全量激活。
121> 3. 持久化权限接口(可以使用canIUse接口进行校验能力是否可用)，且需要申请对应的权限。
122
123**备注**：C/C++去持久化授权接口说明及开发指南具体参考：[OH_FileShare_RevokePermission去持久化授权接口](native-fileshare-guidelines.md)。
124
125## 激活已经持久化的权限访问文件或目录
126
127对于应用已经持久化的授权，应用每次启动时实际未加载到内存中，需要应用按需进行手动激活已持久化授权的权限，通过activatePermission接口（[ohos.fileshare.activatePermission](../reference/apis-core-file-kit/js-apis-fileShare.md#fileshareactivatepermission11)）对已经持久化授权的权限进行使能操作，否则已经持久化授权的权限仍存在不能使用的情况。
128
129**需要权限**
130ohos.permission.FILE_ACCESS_PERSIST，具体参考[访问控制-申请应用权限](../security/AccessToken/determine-application-mode.md)。
131
132**示例：**
133
134```ts
135import { BusinessError } from '@kit.BasicServicesKit';
136import { picker } from '@kit.CoreFileKit';
137import { fileShare } from '@kit.CoreFileKit';
138
139async function activatePermissionExample() {
140    try {
141        let uri = "file://docs/storage/Users/username/tmp.txt";
142        let policyInfo: fileShare.PolicyInfo = {
143            uri: uri,
144            operationMode: fileShare.OperationMode.READ_MODE,
145        };
146        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
147        fileShare.activatePermission(policies).then(() => {
148            console.info("activatePermission successfully");
149        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
150            console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code);
151            if (err.code == 13900001 && err.data) {
152                for (let i = 0; i < err.data.length; i++) {
153                    console.error("error code : " + JSON.stringify(err.data[i].code));
154                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
155                    console.error("error reason : " + JSON.stringify(err.data[i].message));
156                    if (err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED) {
157                        //可以选择进行持久化后再激活。
158                    }
159                }
160            }
161        });
162    } catch (error) {
163        let err: BusinessError = error as BusinessError;
164        console.error(`activatePermission failed with err, Error code: ${err.code}, message: ${err.message}`);
165    }
166}
167```
168
169> **注意**
170>
171> 1. 示例中的URI来源自应用存储的持久化数据中。
172> 2. 建议按照使用需求去激活对应的持久化权限，不要盲目的全量激活。
173> 3. 如果激活失败显示未持久化的权限可以按照示例进行持久化。
174> 4. 持久化权限接口(可以使用canIUse接口进行校验能力是否可用)，且需要申请对应的权限。
175
176**备注**：C/C++持久化授权激活接口说明及开发指南具体参考：[OH_FileShare_ActivatePermission持久化授权激活接口](native-fileshare-guidelines.md)。