Skip to content

Commit b68cd8e

Browse files
gippygippy
committed
feat: PR review based improvements
1 parent 48fbea1 commit b68cd8e

File tree

2 files changed

+228
-211
lines changed

2 files changed

+228
-211
lines changed

‎sources/platform/actors/development/actor_definition/output_schema/examples.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
title: Examples of output schema
3+
sidebar_label: Examples
4+
description: Quick start your output schema definition with example solutions.
5+
slug: /actors/development/actor-definition/output-schema/examples
6+
---
7+
8+
**Quick start your output schema definition with example solutions.**
9+
10+
---
11+
12+
The output schema's `template` property support various Actor types. The following examples show common use cases:
13+
14+
## Basic example of output schema
15+
16+
The following example Actor calls `Actor.setValue()` to save two files to the key-value store:
17+
18+
```javascript title="main.js"
19+
import { Actor } from 'apify';
20+
// Initialize the JavaScript SDK
21+
await Actor.init();
22+
23+
/**
24+
* Store data in key-value store
25+
*/
26+
await Actor.setValue('document-1.txt', 'my text data', { contentType: 'text/plain' });
27+
28+
await Actor.setValue(`image-1.jpeg`, imageBuffer, { contentType: 'image/jpeg' });
29+
30+
// Exit successfully
31+
await Actor.exit();
32+
```
33+
34+
To specify that the Actor is using output schema, update the `.actor/actor.json` file:
35+
36+
```json title=".actor/actor.json"
37+
{
38+
"actorSpecification": 1,
39+
"name": "Actor Name",
40+
"title": "Actor Title",
41+
"version": "1.0.0",
42+
"output": "./output_schema.json"
43+
}
44+
```
45+
46+
Then to specify that output is stored in the key-value store, update `.actor/output_schema.json`:
47+
48+
```json title=".actor/output_schema.json"
49+
{
50+
"actorOutputSchemaVersion": 1,
51+
"title": "Output schema of the Actor",
52+
"properties": {
53+
"files": {
54+
"type": "string",
55+
"title": "Files",
56+
"template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"
57+
}
58+
}
59+
}
60+
```
61+
62+
To show, that the output is stored in the default key-value store, the schema defines a property called `files`.
63+
64+
The `type` of the property must always be a `string` because the value generated from the `template` is a URL string.
65+
66+
The `title` is a human-readable name for the output, shown in the Apify Console.
67+
68+
The `template` uses a variable `{{links.apiDefaultKeyValueStoreUrl}}`, which is replaced with the URL of the default key-value store when the Actor run finishes.
69+
70+
Apify Console uses this configuration to display key-value store data
71+
72+
The **Output** tab will then display the contents of the key-value store:
73+
74+
![Output tab in Run](images/output-schema-simple-example.png)
75+
76+
The `GET Run` API endpoint response will include an `output` property.
77+
78+
```json
79+
"output": {
80+
"files": "https://api.apify.com/v2/key-value-stores/<key-value-store-id>/keys"
81+
}
82+
```
83+
84+
### Linking dataset views and key-value store collections
85+
86+
This example shows a schema definition for a basic social media scraper. The scraper downloads post data into the dataset, and video and subtitle files into the key-value store.
87+
88+
After you define `views` and `collections` in `dataset_schema.json` and `key_value_store.json`, you can use them in the output schema.
89+
90+
```json title=".actor/output_schema.json"
91+
{
92+
"actorOutputSchemaVersion": 1,
93+
"title": "Output schema of Social media scraper",
94+
"properties": {
95+
"overview": {
96+
"type": "string",
97+
"title": "Overview 🔎",
98+
"template": "{{links.apiDefaultDatasetUrl}}/items?view=overview"
99+
},
100+
"posts": {
101+
"type": "string",
102+
"title": "Posts ✉️",
103+
"template": "{{links.apiDefaultDatasetUrl}}/items?view=posts"
104+
},
105+
"author": {
106+
"type": "string",
107+
"title": "Authors 🧑‍🎤",
108+
"template": "{{links.apiDefaultDatasetUrl}}/items?view=author"
109+
},
110+
"music": {
111+
"type": "string",
112+
"title": "Music 🎶",
113+
"template": "{{links.apiDefaultDatasetUrl}}/items?view=music"
114+
},
115+
"video": {
116+
"type": "string",
117+
"title": "Video 🎞️",
118+
"template": "{{links.apiDefaultDatasetUrl}}/items?view=video"
119+
},
120+
"subtitleFiles": {
121+
"type": "string",
122+
"title": "Subtitle files",
123+
"template": "{{links.apiDefaultKeyValueStoreUrl}}/keys?collection=subtitles"
124+
},
125+
"videoFiles": {
126+
"type": "string",
127+
"title": "Video files",
128+
"template": "{{links.apiDefaultKeyValueStoreUrl}}/keys?collection=videos"
129+
}
130+
}
131+
}
132+
```
133+
134+
The schema above defines five dataset outputs and two key-value store outputs. The dataset outputs link to views, and the key-value store output link to collections, both defined in their respective schema files.
135+
136+
When a user runs the Actor in the Console, the UI will look like this:
137+
138+
![Video files in Output tab](images/output-schema-combination-example.png)
139+
140+
### Using container URL to display chat client
141+
142+
In this example, an Actor runs a web server that provides a chat interface to an LLM.
143+
The conversation history is then stored in the dataset.
144+
145+
```json title=".actor/output_schema.json"
146+
{
147+
"actorOutputSchemaVersion": 1,
148+
149+
"title": "Chat client output",
150+
"description": "Chat client provides interactive view to converse with LLM and chat history in dataset",
151+
"type": "object",
152+
153+
"properties": {
154+
"clientUrl": {
155+
"type": "string",
156+
"title": "Chat client",
157+
"template": "{{run.containerUrl}}"
158+
},
159+
"chatHistory": {
160+
"type": "string",
161+
"title": "Conversation history",
162+
"template": "{{links.apiDefaultDatasetUrl}}/items"
163+
}
164+
}
165+
}
166+
```
167+
168+
In the schema above we have two outputs.
169+
The `clientUrl` output will return a link to the web server running inside the run.
170+
The `chatHistory` links to the default dataset and contains the history of the whole conversation, with each message as a separate item.
171+
172+
When the run in the Console, the user will then see this:
173+
174+
![Chat in Output tab](images/output-schema-chat-example.png)
175+
176+
### Custom HTML as Actor run output
177+
178+
This example shows an output schema of an Actor that runs Cypress tests. When the run finishes, the Actor generates an HTML report and store it in the key-value store. You can link to this file and show it as an output:
179+
180+
```json title=".actor/output_schema.json"
181+
{
182+
"actorOutputSchemaVersion": 1,
183+
184+
"title": "Cypress test report output",
185+
"description": "Test report from Cypress",
186+
"type": "object",
187+
188+
"properties": {
189+
"reportUrl": {
190+
"type": "string",
191+
"title": "HTML Report",
192+
"template": "{{links.apiDefaultKeyValueStoreUrl}}/records/report.html"
193+
}
194+
}
195+
}
196+
```
197+
198+
The `reportUrl` in this case links directly to the key-value store record stored in the default key-value store.
199+
200+
When the run finishes, Apify Console displays the HTML report in an iframe:
201+
202+
![HTML report in Output tab](images/output-schema-record-example.png)
203+
204+
### Actor with no output
205+
206+
If your Actor produces no output (for example, an integration Actor that performs an action), users might see the empty **Output** tab and think the Actor failed. To avoid this, specify that the Actor produces no output.
207+
208+
You can specify that the Actor produces no output and define an output schema with no properties:
209+
210+
```json title=".actor/output_schema.json"
211+
{
212+
"actorOutputSchemaVersion": 1,
213+
214+
"title": "Send mail output",
215+
"description": "Send mail Actor does not generate any output.",
216+
"type": "object",
217+
"properties": {}
218+
}
219+
```
220+
221+
When the output schema contains no properties, Apify Console displays the **Log** tab instead of the **Output** tab.

0 commit comments

Comments
 (0)