Skip to content

actors.md

Latest commit

 

History

History
168 lines (138 loc) · 9.67 KB

actors.md

File metadata and controls

168 lines (138 loc) · 9.67 KB
Raw

Actors, versions & environment variables

Access the Actor collection with client.actors() and a single Actor with client.actor(id), where id is an Actor ID or username~name (a / in the id is accepted and normalized).

ActorCollectionClient

Method Description
list(ActorListOptions) List the account's Actors. Completes with PaginationList<Actor>.
iterate(ActorListOptions, Long chunkSize) Lazy Flow.Publisher<Actor> over all matches; the options' limit caps the total yielded (null/unset or non-positive = all), chunkSize sets the page size (null = server default).
create(Object) Create a new Actor from a JSON-serializable definition. Completes with Actor.

ActorListOptions adds my(Boolean) (only Actors owned by the current user) and sortBy(String) (e.g. createdAt, stats.lastRunStartedAt) on top of the standard offset/limit/desc.

PaginationList<Actor> mine = client.actors().list(new ActorListOptions().my(true).limit(5L)).join();
for (Actor actor : mine.getItems()) {
  System.out.println(actor.getName());
}

Create an Actor with a SOURCE_FILES version (sourceType is one of SOURCE_FILES, GIT_REPO, TARBALL, GITHUB_GIST, SOURCE_CODE; a source-file format is TEXT or BASE64):

Actor created = client.actors().create(Map.of(
    "name", "my-actor",
    "isPublic", false,
    "versions", List.of(Map.of(
        "versionNumber", "0.0",
        "sourceType", "SOURCE_FILES",
        "buildTag", "latest",
        "sourceFiles", List.of(
            Map.of("name", "Dockerfile", "format", "TEXT",
                   "content", "FROM apify/actor-node:20\nCOPY . ./\nCMD node main.js"),
            Map.of("name", "main.js", "format", "TEXT",
                   "content", "console.log('hi');")))))).join();

ActorClient

Method Description
get() Fetch the Actor. Completes with Optional<Actor>.
update(Object) Update the Actor with the given fields. Completes with Actor.
delete() Delete the Actor.
start(Object input, ActorStartOptions) Start a run, returning immediately. Completes with ActorRun.
call(Object input, ActorStartOptions, Long waitSecs) Start a run and poll until it finishes (null waits indefinitely); does not stream the run's log. Completes with ActorRun.
call(Object input, ActorCallOptions, Long waitSecs) As above, additionally streaming the run's log for the duration of the wait by default (matching the reference client's call defaulting options.log to 'default'). Use ActorCallOptions.disableLogStreaming() to opt out, or logOptions(StreamedLogOptions) for a custom destination.
validateInput(Object input) / validateInput(Object input, ValidateInputOptions) Validate an input against the Actor's input schema. Completes with boolean. ValidateInputOptions fields (optional): build (String), contentType (String).
build(String versionNumber, ActorBuildOptions) Build a version. Completes with Build.
defaultBuild(Long waitForFinish) Resolve the default build. Completes with BuildClient.
lastRun(String status) / lastRun(LastRunOptions) A RunClient for the last run.
builds() / runs() / versions() Nested collection clients.
webhooks() Read-only nested webhook collection (NestedWebhookCollectionClient, list + iterate, no create).
version(String) An ActorVersionClient.

ActorStartOptions fields (all optional): build(String) (the tag or number of the build to run, e.g. latest, 0.1.2), memoryMbytes(Long) (memory in megabytes allocated for the run), timeoutSecs(Long) (run timeout in seconds; 0 means no timeout), waitForFinish(Long) (maximum seconds to wait server-side for the run to finish, max 60), maxItems(Long) (maximum dataset items to charge, pay-per-result Actors), maxTotalChargeUsd(Double) (maximum total charge in USD, pay-per-event Actors), contentType(String) (content type of the input body, defaults to application/json), restartOnError(Boolean) (restart the run if it fails), forcePermissionLevel(String) (override the Actor's permission level for this run: LIMITED_PERMISSIONS/FULL_PERMISSIONS), and webhooks(List<Object>) — ad-hoc webhook definitions (each a JSON-serializable Map, as in Webhooks) that the client base64-encodes on the wire.

ActorCallOptions (for the log-streaming call overload) mirrors ActorStartOptions field for field, but omits waitForFinish: that field asks the API to hold the HTTP response open server-side while the run finishes, which is redundant with (and wastes a request slot next to) call's own client-side waitSecs polling. It adds disableLogStreaming() (matching the reference client's log: null) and logOptions(StreamedLogOptions) (a custom destination/prefix, matching a custom Log instance) — see Streamed log redirection.

lastRun(String status) filters only by status; lastRun(LastRunOptions) also accepts an origin filter. LastRunOptions has fluent setters status(String) (e.g. SUCCEEDED, RUNNING) and origin(String) (e.g. API, WEB, SCHEDULER); leave a setter uncalled to omit that filter.

Optional<ActorRun> last =
    client.actor("apify/hello-world").lastRun(new LastRunOptions().status("SUCCEEDED").origin("API")).get().join();
ActorRun run = client.actor("apify/hello-world")
    .call(Map.of("greeting", "hi"), new ActorStartOptions().memoryMbytes(512L), 120L)
    .join();
System.out.println(run.getStatus());

Actor fields: getId(), getUserId(), getName(), getUsername(), getTitle(), getDescription(), isPublic(), getCreatedAt(), getModifiedAt(), getStats() (ActorStats — getTotalBuilds()/getTotalRuns()/getTotalUsers()/getTotalUsers7Days()/ getTotalUsers30Days()/getTotalUsers90Days()/getTotalMetamorphs() as Long, getLastRunStartedAt() as Instant), getVersions() (List<ActorVersion>), getPricingInfos() (List<JsonNode>; shape depends on pricing model), getDefaultRunOptions() (ActorDefaultRunOptions — getBuild(), getTimeoutSecs()/getMemoryMbytes() as Long, getRestartOnError() as Boolean), getTaggedBuilds() (JsonNode; dynamic tag-name keys), getIsDeprecated() (Boolean), getDeploymentKey(), getSeoTitle(), getSeoDescription(), getCategories() (List<String>), getActorStandby() (ActorStandby, from com.apify.client.actor, nullable — see Tasks for its field list; only on Actor does it additionally expose getIsEnabled()), getActorPermissionLevel() (e.g. "OWNER"), plus getExtra() for any unmodelled fields.

ActorVersionClient and ActorVersionCollectionClient

client.actor(id).versions() lists/creates versions; client.actor(id).version(v) reads, updates and deletes a single version and exposes its environment variables.

ActorVersionCollectionClient — client.actor(id).versions()

Method Description
list(ListOptions) List the Actor's versions. Completes with PaginationList<ActorVersion>. The endpoint takes no query parameters; options (offset/limit/desc) is accepted only for signature consistency with every other list(ListOptions) and has no effect — pass null.
iterate(ListOptions) Lazy Flow.Publisher<ActorVersion> over all versions; limit caps the total (null/unset or non-positive = all), applied client-side after the single fetch. offset has no effect and there is no page size to tune.
create(Object version) Create a version. Completes with ActorVersion.

ActorVersionClient — client.actor(id).version(v)

Method Description
get() Fetch the version. Completes with Optional<ActorVersion>.
update(Object) Update the version. Completes with ActorVersion.
delete() Delete the version.
envVars() An ActorEnvVarCollectionClient for the version's environment variables.
envVar(String name) An ActorEnvVarClient for a single environment variable. 
ActorVersion version = client.actor("me/my-actor").version("0.0").get().join().orElseThrow();
System.out.println(version.getSourceType());

ActorVersion fields: getVersionNumber(), getSourceType(), plus getExtra() for any unmodelled fields.

ActorEnvVarClient and ActorEnvVarCollectionClient

Attach environment variables to a version. ActorEnvVar has a (name, value) constructor plus fluent setters setName, setValue, setIsSecret(Boolean) (when secret, the value is stored encrypted), and matching getters getName(), getValue(), getIsSecret().

ActorEnvVarCollectionClient — client.actor(id).version(v).envVars()

Method Description
list() List the version's environment variables. Completes with PaginationList<ActorEnvVar>.
iterate() Flow.Publisher<ActorEnvVar> over the variables. The env-var collection is not paginated (all variables are returned at once), so this iterates a single fetched page; provided for API consistency.
create(ActorEnvVar) Create an environment variable. Completes with ActorEnvVar.

ActorEnvVarClient — client.actor(id).version(v).envVar(name)

Method Description
get() Fetch the environment variable. Completes with Optional<ActorEnvVar>.
update(ActorEnvVar) Update the environment variable. Completes with ActorEnvVar.
delete() Delete the environment variable. 
client.actor("me/my-actor").version("0.0").envVars()
    .create(new ActorEnvVar("API_KEY", "secret").setIsSecret(true))
    .join();
Optional<ActorEnvVar> ev = client.actor("me/my-actor").version("0.0").envVar("API_KEY").get().join();