Skip to content

Commit 6668899

Browse files
author
Jens Kürten
committed
add docs
1 parent f98126d commit 6668899

File tree

2 files changed

+140
-0
lines changed

2 files changed

+140
-0
lines changed

‎docs/reference/service.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Functions Access Service
2+
3+
The Functions Access Service provides access to backend services like number generators and file uplads. These services are available through the `service` parameter that is passed to all Functions.
4+
5+
The Access Service is ratelimited to `100 req/min` per token. Functions recieve a fresh token for every call.
6+
7+
```python
8+
from csfunctions import Service
9+
10+
def my_function(metadata, event, service: Service):
11+
...
12+
13+
```
14+
15+
## Number Generation
16+
17+
18+
You can use the `service.generator` to generate unique numbers, for example for part numbers or document IDs.
19+
20+
### Methods
21+
22+
- `get_number(name: str) -> int`
23+
Retrieve one number from the given generator.
24+
- `get_numbers(name: str, count: int) -> list[int]`
25+
Retrieve multiple numbers from the given generator in one request.
26+
Maximum for `count` is 100.
27+
28+
**Example:**
29+
30+
```python
31+
new_number = service.generator.get_number("external_part_number")
32+
# Returns an integer, e.g. 123
33+
```
34+
35+
To generate multiple numbers at once:
36+
37+
```python
38+
numbers = service.generator.get_numbers("external_part_number", count=5)
39+
# Returns a list of integers
40+
```
41+
42+
## File Uploads
43+
44+
45+
46+
The `service.file_upload` object allows you to upload new files to the CIM Database Cloud or overwrite existing ones.
47+
48+
49+
50+
### Upload a new file
51+
52+
```python
53+
service.upload_new_file(
54+
self,
55+
parent_object_id: str,
56+
filename: str,
57+
stream: BinaryIO,
58+
persno: str | None = None,
59+
check_access: bool = True,
60+
filesize: int | None = None,
61+
) -> str:
62+
```
63+
Creates a new file attached to the parent object and uploads content from the provided stream. Returns the new file object ID.
64+
65+
| Parameter | Type | Description |
66+
| ------------------ | ------------- | --------------------------------------------------------------------------------------------- |
67+
| `parent_object_id` | `str` | The ID of the parent object to which the new file will be attached. |
68+
| `filename` | `str` | The name of the new file to be uploaded. |
69+
| `stream` | `BinaryIO` | A binary stream containing the file data to upload. |
70+
| `persno` | `str \| None` | The user/person number uploading the file (defaults to the user that triggered the Function). |
71+
| `check_access` | `bool` | Whether to check access permissions before uploading. Defaults to `True`. |
72+
| `filesize` | `int \| None` | Size of the file in bytes (required only if the stream is not seekable). |
73+
74+
**Exceptions:**
75+
76+
- `csfunctions.service.Unauthorized`: If access check fails.
77+
- `csfunctions.service.NotFound`: If the parent object does not exist.
78+
79+
80+
!!! info
81+
Uploading new files performs 3 requests to the Functions Access Service, which count towards the ratelimit of `100 req/min` per token.
82+
83+
**Example:**
84+
85+
```python
86+
with open("myfile.pdf", "rb") as f:
87+
file_object_id = service.file_upload.upload_new_file(
88+
parent_object_id="123456",
89+
filename="myfile.pdf",
90+
stream=f
91+
)
92+
```
93+
94+
### Overwrite an existing file
95+
96+
```python
97+
service.file_upload.upload_file_content(
98+
file_object_id: str,
99+
stream: BinaryIO,
100+
persno: str | None = None,
101+
check_access: bool = True,
102+
filesize: int | None = None,
103+
delete_derived_files: bool = True,
104+
) -> None:
105+
```
106+
Uploads new content to an existing file object, overwriting its previous contents.
107+
108+
| Parameter | Type | Description |
109+
| ---------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
110+
| `file_object_id` | `str` | The ID of the file object to upload to (must already exist). |
111+
| `stream` | `BinaryIO` | A binary stream containing the file data to upload. |
112+
| `persno` | `str \| None` | The user/person number uploading the file (defaults to the user that triggered the Function). |
113+
| `check_access` | `bool` | Whether to check access permissions before uploading. Defaults to `True`. |
114+
| `filesize` | `int \| None` | Size of the file in bytes (required only if the stream is not seekable). |
115+
| `delete_derived_files` | `bool` | Whether to delete derived files (e.g. converted pdfs) after upload and trigger a new conversion. Defaults to `True`. |
116+
117+
!!! warning
118+
Overwriting files is only possible if the file is not locked!
119+
120+
**Exceptions:**
121+
122+
- `csfunctions.service.Unauthorized`: If access check fails.
123+
- `csfunctions.service.Conflict`: If the file is already locked.
124+
- `csfunctions.service.NotFound`: If the file object does not exist.
125+
- `csfunctions.service.RateLimitExceeded`: If the services rate limit is exceeded.
126+
127+
!!! info
128+
Uploading new files performs 2 requests to the Functions Access Service, which count towards the ratelimit of `100 req/min` per token.
129+
130+
**Example:**
131+
132+
```python
133+
file = doc.files[0]
134+
with open("updated_file.pdf", "rb") as f:
135+
service.file_upload.upload_file_content(
136+
file_object_id=file.cdb_object_id,
137+
stream=f
138+
)
139+
```

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ nav:
5050
- reference/events.md
5151
- reference/objects.md
5252
- reference/actions.md
53+
- reference/service.md
5354
- development_server.md
5455
- Python runtime: reference/runtime.md
5556
- Releases: release_notes.md

0 commit comments

Comments
 (0)