Actor <Data>
Index
Constructors
constructor
Type parameters
- Data: Dictionary<any> = Dictionary<any>
Parameters
options: ConfigurationOptions = {}
Returns Actor<Data>
Accessors
staticapifyClient
Default ApifyClient instance.
Returns ApifyClient
staticconfig
Default Configuration instance.
Returns Configuration
Methods
staticabort
Aborts given actor run on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable).The result of the function is an ActorRun object that contains details about the actor run.
For more information about actors, read the documentation.
Example usage:
const run = await Actor.abort(runId);Parameters
runId: string
options: AbortOptions = {}
Returns Promise<ActorRun>
staticaddWebhook
Creates an ad-hoc webhook for the current actor run, which lets you receive a notification when the actor run finished or failed. For more information about Apify actor webhooks, please see the documentation.
Note that webhooks are only supported for actors running on the Apify platform. In local environment, the function will print a warning and have no effect.
Parameters
options: WebhookOptions
Returns Promise<undefined | Webhook>
The return value is the Webhook object. For more information, see the Get webhook API endpoint.
staticcall
Runs an actor on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable), waits for the actor to finish and fetches its output.By passing the
waitSecsoption you can reduce the maximum amount of time to wait for the run to finish. If the value is less than or equal to zero, the function returns immediately after the run is started.The result of the function is an ActorRun object that contains details about the actor run and its output (if any).
If you want to run an actor task rather than an actor, please use the Actor.callTask function instead.
For more information about actors, read the documentation.
Example usage:
const run = await Actor.call('apify/hello-world', { myInput: 123 });
console.log(`Received message: ${run.output.body.message}`);Internally, the
call()function invokes the Run actor and several other API endpoints to obtain the output.Parameters
actorId: string
Allowed formats are
username/actor-name,userId/actor-nameor actor ID.optionalinput: unknown
Input for the actor. If it is an object, it will be stringified to JSON and its content type set to
application/json; charset=utf-8. Otherwise theoptions.contentTypeparameter must be provided.optionaloptions: CallOptions = {}
Returns Promise<ActorRun>
staticcallTask
Runs an actor task on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable), waits for the task to finish and fetches its output.By passing the
waitSecsoption you can reduce the maximum amount of time to wait for the run to finish. If the value is less than or equal to zero, the function returns immediately after the run is started.The result of the function is an ActorRun object that contains details about the actor run and its output (if any).
Note that an actor task is a saved input configuration and options for an actor. If you want to run an actor directly rather than an actor task, please use the Actor.call function instead.
For more information about actor tasks, read the documentation.
Example usage:
const run = await Actor.callTask('bob/some-task');
console.log(`Received message: ${run.output.body.message}`);Internally, the
callTask()function calls the Run task and several other API endpoints to obtain the output.Parameters
taskId: string
Allowed formats are
username/task-name,userId/task-nameor task ID.optionalinput: Dictionary<any>
Input overrides for the actor task. If it is an object, it will be stringified to JSON and its content type set to
application/json; charset=utf-8. Provided input will be merged with actor task input.optionaloptions: CallTaskOptions = {}
Returns Promise<ActorRun>
staticcreateProxyConfiguration
Creates a proxy configuration and returns a promise resolving to an instance of the ProxyConfiguration class that is already initialized.
Configures connection to a proxy server with the provided options. Proxy servers are used to prevent target websites from blocking your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures them to use the selected proxies for all connections.
For more details and code examples, see the ProxyConfiguration class.
// Returns initialized proxy configuration class
const proxyConfiguration = await Actor.createProxyConfiguration({
groups: ['GROUP1', 'GROUP2'] // List of Apify proxy groups
countryCode: 'US'
});
const crawler = new CheerioCrawler({
// ...
proxyConfiguration,
requestHandler({ proxyInfo }) {
const usedProxyUrl = proxyInfo.url; // Getting the proxy URL
}
})For compatibility with existing Actor Input UI (Input Schema), this function returns
undefinedwhen the following object is passed asproxyConfigurationOptions.{ useApifyProxy: false }Parameters
proxyConfigurationOptions: ProxyConfigurationOptions & { useApifyProxy?: boolean } = {}
Returns Promise<undefined | ProxyConfiguration>
staticexit
Parameters
optionalmessageOrOptions: string | ExitOptions
options: ExitOptions = {}
Returns Promise<void>
staticfail
Parameters
optionalmessageOrOptions: string | ExitOptions
options: ExitOptions = {}
Returns Promise<void>
staticgetEnv
Returns a new ApifyEnv object which contains information parsed from all the
APIFY_XXXenvironment variables.For the list of the
APIFY_XXXenvironment variables, see Actor documentation. If some of the variables are not defined or are invalid, the corresponding value in the resulting object will be null.Returns ApifyEnv
staticgetInput
Gets the actor input value from the default KeyValueStore associated with the current actor run.
This is just a convenient shortcut for
keyValueStore.getValue('INPUT'). For example, calling the following code:const input = await Actor.getInput();is equivalent to:
const store = await Actor.openKeyValueStore();
await store.getValue('INPUT');Note that the
getInput()function does not cache the value read from the key-value store. If you need to use the input multiple times in your actor, it is far more efficient to read it once and store it locally.For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.
Type parameters
- T = string | Dictionary<any> | Buffer
Returns Promise<null | T>
Returns a promise that resolves to an object, string or
Buffer, depending on the MIME content type of the record, ornullif the record is missing.
staticgetValue
Gets a value from the default KeyValueStore associated with the current actor run.
This is just a convenient shortcut for KeyValueStore.getValue. For example, calling the following code:
const value = await Actor.getValue('my-key');is equivalent to:
const store = await Actor.openKeyValueStore();
const value = await store.getValue('my-key');To store the value to the default key-value store, you can use the Actor.setValue function.
For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.
Type parameters
- T = unknown
Parameters
key: string
Unique record key.
Returns Promise<null | T>
Returns a promise that resolves to an object, string or
Buffer, depending on the MIME content type of the record, ornullif the record is missing.
staticinit
Parameters
options: InitOptions = {}
Returns Promise<void>
staticisAtHome
Returns
truewhen code is running on Apify platform andfalseotherwise (for example locally).Returns boolean
staticmain
Runs the main user function that performs the job of the actor and terminates the process when the user function finishes.
The
Actor.main()function is optional and is provided merely for your convenience. It is mainly useful when you're running your code as an actor on the Apify platform. However, if you want to use Apify SDK tools directly inside your existing projects, e.g. running in an Express server, on Google Cloud functions or AWS Lambda, it's better to avoid it since the function terminates the main process when it finishes!The
Actor.main()function performs the following actions:- When running on the Apify platform (i.e.
APIFY_IS_AT_HOMEenvironment variable is set), it sets up a connection to listen for platform events. For example, to get a notification about an imminent migration to another server. See Actor.events for details. - It checks that either
APIFY_TOKENorAPIFY_LOCAL_STORAGE_DIRenvironment variable is defined. If not, the functions setsAPIFY_LOCAL_STORAGE_DIRto./apify_storageinside the current working directory. This is to simplify running code examples. - It invokes the user function passed as the
userFuncparameter. - If the user function returned a promise, waits for it to resolve.
- If the user function throws an exception or some other error is encountered, prints error details to console so that they are stored to the log.
- Exits the Node.js process, with zero exit code on success and non-zero on errors.
The user function can be synchronous:
await Actor.main(() => {
// My synchronous function that returns immediately
console.log('Hello world from actor!');
});If the user function returns a promise, it is considered asynchronous:
import { gotScraping } from 'got-scraping';
await Actor.main(() => {
// My asynchronous function that returns a promise
return gotScraping('http://www.example.com').then((html) => {
console.log(html);
});
});To simplify your code, you can take advantage of the
async/awaitkeywords:import { gotScraping } from 'got-scraping';
await Actor.main(async () => {
// My asynchronous function
const html = await gotScraping('http://www.example.com');
console.log(html);
});Type parameters
- T
Parameters
userFunc: UserFunc<T>
User function to be executed. If it returns a promise, the promise will be awaited. The user function is called with no arguments.
optionaloptions: MainOptions
Returns Promise<T>
- When running on the Apify platform (i.e.
staticmetamorph
Transforms this actor run to an actor run of a given actor. The system stops the current container and starts the new container instead. All the default storages are preserved and the new input is stored under the
INPUT-METAMORPH-1key in the same default key-value store.Parameters
targetActorId: string
Either
username/actor-nameor actor ID of an actor to which we want to metamorph.optionalinput: unknown
Input for the actor. If it is an object, it will be stringified to JSON and its content type set to
application/json; charset=utf-8. Otherwise, theoptions.contentTypeparameter must be provided.optionaloptions: MetamorphOptions = {}
Returns Promise<void>
staticnewClient
Returns a new instance of the Apify API client. The
ApifyClientclass is provided by the apify-client NPM package, and it is automatically configured using theAPIFY_API_BASE_URL, andAPIFY_TOKENenvironment variables. You can override the token via the available options. That's useful if you want to use the client as a different Apify user than the SDK internals are using.Parameters
options: ApifyClientOptions = {}
Returns ApifyClient
staticoff
Parameters
event: EventTypeName
optionallistener: (...args: any[]) => any
Returns void
staticon
Parameters
event: EventTypeName
listener: (...args: any[]) => any
Returns void
staticopenDataset
Opens a dataset and returns a promise resolving to an instance of the Dataset class.
Datasets are used to store structured data where each object stored has the same attributes, such as online store products or real estate offers. The actual data is stored either on the local filesystem or in the cloud.
For more details and code examples, see the Dataset class.
Type parameters
- Data: Dictionary<any> = Dictionary<any>
Parameters
optionaldatasetIdOrName: null | string
ID or name of the dataset to be opened. If
nullorundefined, the function returns the default dataset associated with the actor run.optionaloptions: OpenStorageOptions = {}
Returns Promise<Dataset<Data>>
staticopenKeyValueStore
Opens a key-value store and returns a promise resolving to an instance of the KeyValueStore class.
Key-value stores are used to store records or files, along with their MIME content type. The records are stored and retrieved using a unique key. The actual data is stored either on a local filesystem or in the Apify cloud.
For more details and code examples, see the KeyValueStore class.
Parameters
optionalstoreIdOrName: null | string
ID or name of the key-value store to be opened. If
nullorundefined, the function returns the default key-value store associated with the actor run.optionaloptions: OpenStorageOptions = {}
Returns Promise<KeyValueStore>
staticopenRequestQueue
Opens a request queue and returns a promise resolving to an instance of the RequestQueue class.
RequestQueue represents a queue of URLs to crawl, which is stored either on local filesystem or in the cloud. The queue is used for deep crawling of websites, where you start with several URLs and then recursively follow links to other pages. The data structure supports both breadth-first and depth-first crawling orders.
For more details and code examples, see the RequestQueue class.
Parameters
optionalqueueIdOrName: null | string
ID or name of the request queue to be opened. If
nullorundefined, the function returns the default request queue associated with the actor run.optionaloptions: OpenStorageOptions = {}
Returns Promise<RequestQueue>
staticpushData
Stores an object or an array of objects to the default Dataset of the current actor run.
This is just a convenient shortcut for Dataset.pushData. For example, calling the following code:
await Actor.pushData({ myValue: 123 });is equivalent to:
const dataset = await Actor.openDataset();
await dataset.pushData({ myValue: 123 });For more information, see Actor.openDataset and Dataset.pushData
IMPORTANT: Make sure to use the
awaitkeyword when callingpushData(), otherwise the actor process might finish before the data are stored!Type parameters
- Data: Dictionary<any> = Dictionary<any>
Parameters
item: Data | Data[]
Object or array of objects containing data to be stored in the default dataset. The objects must be serializable to JSON and the JSON representation of each object must be smaller than 9MB.
Returns Promise<void>
staticreboot
Internally reboots this actor run. The system stops the current container and starts a new container with the same run id.
Returns Promise<void>
staticsetStatusMessage
Sets the status message for the current actor run.
Parameters
statusMessage: string
Returns Promise<ActorRun>
The return value is the Run object. For more information, see the Actor Runs API endpoints.
staticsetValue
Stores or deletes a value in the default KeyValueStore associated with the current actor run.
This is just a convenient shortcut for KeyValueStore.setValue. For example, calling the following code:
await Actor.setValue('OUTPUT', { foo: "bar" });is equivalent to:
const store = await Actor.openKeyValueStore();
await store.setValue('OUTPUT', { foo: "bar" });To get a value from the default key-value store, you can use the Actor.getValue function.
For more information, see Actor.openKeyValueStore and KeyValueStore.getValue.
Type parameters
- T
Parameters
key: string
Unique record key.
value: null | T
Record data, which can be one of the following values:
- If
null, the record in the key-value store is deleted. - If no
options.contentTypeis specified,valuecan be any JavaScript object, and it will be stringified to JSON. - If
options.contentTypeis set,valueis taken as is, and it must be aStringorBuffer. For any other value an error will be thrown.
- If
optionaloptions: RecordOptions = {}
Returns Promise<void>
staticstart
Runs an actor on the Apify platform using the current user account (determined by the
APIFY_TOKENenvironment variable), unlikeActor.call, this method just starts the run without waiting for finish.The result of the function is an ActorRun object that contains details about the actor run.
For more information about actors, read the documentation.
Example usage:
const run = await Actor.start('apify/hello-world', { myInput: 123 });Parameters
actorId: string
Allowed formats are
username/actor-name,userId/actor-nameor actor ID.optionalinput: Dictionary<any>
Input for the actor. If it is an object, it will be stringified to JSON and its content type set to
application/json; charset=utf-8. Otherwise theoptions.contentTypeparameter must be provided.optionaloptions: CallOptions = {}
Returns Promise<ActorRun>
Actorclass serves as an alternative approach to the static helpers exported from the package. It allows to pass configuration that will be used on the instance methods. Environment variables will have precedence over this configuration. See Configuration for details about what can be configured and what are the default values.