Actor <Data>
Index
Constructors
Properties
Accessors
Methods
Constructors
constructor
Parameters
options: ConfigurationOptions = {}
Returns Actor<Data>
Properties
initialized
Whether the Actor instance was initialized. This is set by calling Actor.init.
Accessors
staticapifyClient
Default ApifyClient instance.
Returns ApifyClient
staticconfig
Default Configuration instance.
Returns Configuration
Methods
getInputOrThrow
Gets the Actor input value just like the Actor.getInput method, but throws if it is not found.
Returns Promise<T>
useState
Easily create and manage state values. All state values are automatically persisted.
Values can be modified by simply using the assignment operator.
Parameters
optionalname: string
The name of the store to use.
defaultValue: State = ...
If the store does not yet have a value in it, the value will be initialized with the
defaultValueyou provide.optionaloptions: UseStateOptions
An optional object parameter where a custom
keyValueStoreNameandconfigcan be passed in.
Returns Promise<State>
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).The result of the function is an ActorRun object that contains details about the Actor run.
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 });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).The result of the function is an ActorRun object that contains details about the Actor run.
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');Parameters
taskId: string
Allowed formats are
username/task-name,userId/task-nameor task ID.optionalinput: Dictionary
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
Gracefully exits the Actor run with the provided status message and exit code.
Parameters
optionalmessageOrOptions: string | ExitOptions
First parameter accepts either a string (a terminal status message) or an
ExitOptionsobject.options: ExitOptions = {}
Second parameter accepts an
ExitOptionsobject.
Returns Promise<void>
staticfail
Calls
Actor.exit()withoptions.exitCodeset to1.Parameters
optionalmessageOrOptions: string | ExitOptions
First parameter accepts either a string (a terminal status message) or an
ExitOptionsobject.options: ExitOptions = {}
Second parameter accepts an
ExitOptionsobject.
Returns Promise<void>
staticgetEnv
Returns a new ApifyEnv object which contains information parsed from all the Apify environment variables.
For the list of the Apify environment 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.
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.
staticgetInputOrThrow
Gets the Actor input value just like the Actor.getInput method, but throws if it is not found.
Returns Promise<T>
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.
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
Initializes the Actor, enabling support for the Apify platform dynamically based on
APIFY_IS_AT_HOMEenv var. If you are not running the code on Apify, you don't need to use it. The method will switch storage client implementation automatically, so when you run on the Apify platform, it will use its API instead of the default memory storage. It also increases the available memory ratio from 25% to 100% on the platform.Calling
Actor.exit()is required if you use theActor.init()method, since it opens websocket connection (see Actor.events for details), which needs to be terminated for the code to finish.import { gotScraping } from 'got-scraping';
await Actor.init();
const html = await gotScraping('http://www.example.com');
console.log(html);
await Actor.exit();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 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);
});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.
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!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. This can be used to get the Actor out of irrecoverable error state and continue where it left off.
Parameters
options: RebootOptions = {}
Returns Promise<void>
staticsetStatusMessage
Sets the status message for the current Actor run.
Parameters
statusMessage: string
The status message to set.
optionaloptions: SetStatusMessageOptions
Returns Promise<ActorRun>
The return value is the Run object. When run locally, this method returns empty 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.
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
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>
staticuseState
Easily create and manage state values. All state values are automatically persisted.
Values can be modified by simply using the assignment operator.
Parameters
optionalname: string
The name of the store to use.
defaultValue: State = ...
If the store does not yet have a value in it, the value will be initialized with the
defaultValueyou provide.optionaloptions: UseStateOptions
An optional object parameter where a custom
keyValueStoreNameandconfigcan be passed in.
Returns Promise<State>
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.