Skip to content

Commit 394065e

Browse files
ArtificialOwlArtificialOwl
committed
fulltextsearch ocs api
1 parent 584f8da commit 394065e

File tree

2 files changed

+209
-0
lines changed

2 files changed

+209
-0
lines changed

‎developer_manual/client_apis/OCS/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,4 @@ The old documentation is still kept as it provides some additional documentation
2222
ocs-text2image-api
2323
ocs-taskprocessing-api
2424
ocs-out-of-office-api
25+
ocs-fulltextsearch-collections-api

‎developer_manual/client_apis/OCS/ocs-fulltextsearch-collections-api.rst

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
=================================
2+
OCS FullTextSearch Collection API
3+
=================================
4+
5+
.. versionadded:: 27
6+
7+
FullTextSearch includes an OCS API to index the content of your Nextcloud into an external search engine.
8+
9+
10+
Concept overview
11+
----------------
12+
13+
Because your structure might already host its own search engine, the FullTextSearch apps provide an OCS API to helps you index your users' content and maintain an up-to-date index.
14+
The OCS API will allow your script to:
15+
16+
* returns a list of not indexed, or freshly updated, document from Nextcloud,
17+
* extract content from document,
18+
* update internal index once a document have been indexed on your external search engine,
19+
20+
21+
First steps
22+
-----------
23+
24+
Installing the apps
25+
^^^^^^^^^^^^^^^^^^^
26+
27+
On top of the `fulltextsearch` app, at least one content provider needs to be installed on the Nextcloud; meaning that a minimum of 2 apps have to be installed before using this feature:
28+
29+
.. code-block:: console
30+
31+
$ ./occ app:enable fulltextsearch files_fulltextsearch
32+
33+
34+
Initializing the collection
35+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
36+
37+
Using `occ`, create a new collection that will be used to sync the content indexed on the external search engine with the current content of the Nextcloud.
38+
39+
.. code-block:: console
40+
41+
$ ./occ fulltextsearch:collection:init test
42+
43+
.. note:: `test` will be the name of the collection used in all example from this page.
44+
45+
46+
Linking a collection to a user account
47+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48+
49+
By default this API can only be used with an admin account but, for security reason, you can choose to link a non-admin account and use this account when requesting the API.
50+
51+
.. code-block:: console
52+
53+
$ ./occ fulltextsearch:collection:link test user1
54+
55+
.. warning:: Keep in mind that the linked account will have access to the content of all documents of all Nextcloud users through the API.
56+
57+
58+
Using the collection OCS API
59+
----------------------------
60+
61+
Once the collection have been initialized, the normal uses of this API implies that your script:
62+
63+
- make an OCS request to retrieve a list of document that have been created, modified and shared,
64+
- make OCS requests to get the content for the documents from the list,
65+
- index the content on your search engine and make an OCS request to confirm it,
66+
- returns to first step until the list of document is empty,
67+
68+
.. note: This process should be executed from time to time on a schedule of your choice to keep your index up to date for each freshly created, moved, deleted, modified and/or shared a new entry will be added to the list of documents
69+
70+
71+
72+
Retrieving the list of document to be (re-)indexed
73+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74+
75+
The endpoint to get this list is:
76+
77+
``/ocs/v2.php/apps/fulltextsearch/collection/<collection_name>/index``
78+
79+
.. code-block:: console
80+
81+
$ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index?format=json&length=50" -H "OCS-APIRequest: true" -u "admin:password"
82+
{
83+
"ocs": {
84+
"meta": {
85+
"status": "ok",
86+
"statuscode": 200,
87+
"message": "OK"
88+
},
89+
"data": [
90+
{
91+
"url": "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996",
92+
"status": 28
93+
}
94+
]
95+
}
96+
}
97+
98+
Details about the response:
99+
100+
- ``url`` is the link to the document,
101+
- ``status`` is a bitflag based on this list:
102+
* `1` => document has already been marked as indexed before,
103+
* `4` => meta have been modified,
104+
* `8` => content have been modified,
105+
* `16` => parts have been modified
106+
* `32` => document have been removed
107+
108+
109+
110+
111+
Get data and metadata from a document
112+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
113+
114+
The endpoint to get data about a document is:
115+
116+
``/ocs/v2.php/apps/fulltextsearch/collection/<collection_name>/document/<provider_id>/<document_id>``
117+
118+
.. code-block:: console
119+
120+
$ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996?format=json" -H "OCS-APIRequest: true" -u "admin:password"
121+
{
122+
"ocs": {
123+
"meta": {
124+
"status": "ok",
125+
"statuscode": 200,
126+
"message": "OK"
127+
},
128+
"data": {
129+
"id": "597996",
130+
"providerId": "files",
131+
"access": {
132+
"ownerId": "user1",
133+
"users": ['user2', 'user3'],
134+
"groups": ['group1'],
135+
"circles": [],
136+
"links": []
137+
},
138+
"index": {
139+
"ownerId": "user1",
140+
"providerId": "files",
141+
"collection": "test",
142+
"source": "files_local",
143+
"documentId": "597996",
144+
"lastIndex": 0,
145+
"errors": [],
146+
"errorCount": 0,
147+
"status": 28,
148+
"options": []
149+
},
150+
"title": "640-240-max.png",
151+
"link": "https://cloud.example.net/index.php/f/597996",
152+
"parts": {
153+
"comments": "<user3> This is a comment !"
154+
},
155+
"content": "VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=",
156+
"isContentEncoded": 1
157+
}
158+
}
159+
}
160+
161+
162+
.. note:: If `isContentEncoded` is set to 1, content needs to be decoded
163+
164+
.. code-block:: console
165+
166+
$ php -r "echo base64_decode('VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=');"
167+
The quick brown fox
168+
jumps over
169+
the lazy dog.
170+
171+
172+
173+
174+
Set document as indexed
175+
^^^^^^^^^^^^^^^^^^^^^^^
176+
177+
Once a document has been indexed in your external search engine, you have to notice the FullTextSearch of this action. This is done by doing a ``POST`` request on the following path:
178+
179+
``/ocs/v2.php/apps/fulltextsearch/collection/<collection_name>/document/<provider_id>/<document_id>/done``
180+
181+
182+
.. code-block:: console
183+
184+
$ curl -X POST "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996/done" -H "OCS-APIRequest: true" -u "admin:password"
185+
{
186+
"ocs": {
187+
"meta": {
188+
"status": "ok",
189+
"statuscode": 200,
190+
"message": "OK"
191+
},
192+
"data": []
193+
}
194+
}
195+
196+
Once set as indexed, the document will only returns to the list of document to be (re-)indexed if they get modified.
197+
198+
199+
Reset collection
200+
^^^^^^^^^^^^^^^^
201+
202+
If needed, an endpoint is available to reset the whole index:
203+
204+
``/ocs/v2.php/apps/fulltextsearch/collection/<collection_name>/index``
205+
206+
.. code-block:: console
207+
208+
$ curl -X DELETE -u "user1:password" "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index" -H "OCS-APIRequest: true" -k

0 commit comments

Comments
 (0)