apify-actor-development

Apify Actor の開発

Actor は、Docker イメージとしてパッケージ化されたサーバーレスプログラムです。1 つの JSON 入力を受け取り、1 つのジョブを実行して、結果をデータセットまたはキー・バリューストアに書き込みます。

セットアップ

apify --help   # CLI installed?
apify info     # logged in? prints your username

パッケージマネージャーを使って、npm install -g apify-cli または brew install apify-cli でインストールすると、ダウンロードの整合性が検証されます。apify login でログインすると、ブラウザーでのサインイン、または API トークンの入力が求められます。ヘッドレス環境では、代わりに APIFY_TOKEN をエクスポートしてください。CLI が自動的に読み取ります。トークンは https://console.apify.com/settings/integrations から取得できます。トークンは環境経由でのみ渡してください。そうすれば、シェルの履歴、ソースコード、設定ファイル、ログに残りません。

テレメトリの属性付け（必須）

このスキルから実行する すべての apify コマンド（apify create、apify run、apify push、apify call など）に --user-agent apify-agent-skills/apify-actor-development を渡してください。これはすべての apify コマンドで使えるグローバルフラグです。テレメトリの属性付けに使われるタグを付けるだけで、それ以外は何も変更しません。

ワークフロー

既存の Actor を変更する場合は、該当しない手順を省略してください。

1. プロジェクトを作成します。

   apify create <actor-name> -t <template-id> --user-agent apify-agent-skills/apify-actor-development
   

   Actor の用途に合ったテンプレートを選択してください。

   Actor の用途	TypeScript	JavaScript	Python
   静的 HTML をクロールする	ts-crawlee-cheerio	js-crawlee-cheerio	python-crawlee-beautifulsoup
   JavaScript でレンダリングされたページをクロールする	ts-crawlee-playwright-chrome	js-crawlee-playwright-chrome	python-crawlee-playwright
   HTTP リクエスト（API、Webhook）を処理する	ts-standby	js-standby	python-standby
   MCP サーバーである	ts-mcp-empty	—	python-mcp-empty
   その他（API のポーリング、データ処理）	ts-empty	js-empty	python-empty
   その他のスタック（Puppeteer、Camoufox、Scrapy、AI エージェントフレームワーク）については、apify templates ls で言語とユースケースを含むすべてのテンプレートを一覧表示できます。-t を付けると、コマンドはプロンプトなしで実行されます。これはエージェントが必要とする動作です。-t を付けない場合は、名前、言語、テンプレート、ソースホストの入力を求められます。この形式はユーザーがターミナルの前にいるときにのみ使用してください。ソースを GitHub、GitLab、または Bitbucket でホストすると、Apify がリポジトリとそこからビルドする Actor を作成するため、以降のデプロイは git push で行えます。依存関係は自動的にインストールされます。<name>/.actor/actor.json が存在すれば完了です。続行する前にそのディレクトリに cd してください。

2. テンプレートに不足している依存関係を追加します（Crawlee や Playwright など）。JS/TS では npm install <pkg> を実行します。Python では requirements.txt に 1 行追加してから pip install -r requirements.txt を実行するか、プロジェクトに pyproject.toml と uv.lock がある場合は uv add <pkg> を実行します。インストールする前に、各パッケージ名が意図するパッケージと一致しているか確認してください。正確なバージョンを固定し、ロックファイル（package-lock.json、uv.lock、または requirements.txt 内の pkg==1.2.3 の行）をコミットしてください。

3. ルールに従って src/main.js、src/main.ts、または my_actor/main.py（Python テンプレートは python -m my_actor として実行される my_actor パッケージです）に実装します。コードがすべての入力フィールドを読み取り、README に記載するすべての出力フィールドを生成し、Apify ロガーを通じてログを出力し、状態を永続化して終了する aborting ハンドラーを登録すれば完了です。

4. 入力スキーマを記述します — .actor/input_schema.json（references/input-schema.md を参照）。コードが読み取るすべての入力に、タイトル、説明、型、およびデフォルト値またはプリフィルを持つフィールドがあり、apify validate-schema --user-agent apify-agent-skills/apify-actor-development がパスすれば完了です。

5. 出力スキーマを記述します — dataset_schema.json、output_schema.json、およびコードがファイルを保存する場合は key_value_store_schema.json です。references/output-schemas.md を最初から最後までに従ってください。そのチェックリストは apify validate-schema のパスで終わり、これが完了基準です。TypeScript の場合は、その後 apify actor generate-schema-types を実行し、生成されたインターフェースで入力と出力に型を付けます。

6. .actor/actor.json を構成します（references/actor-json.md を参照）。meta.generatedBy に使用中のツールとモデルを設定します。たとえば「Claude Code with Claude Opus 5」のようにします。HTTP を提供する Actor の場合は usesStandbyMode: true を設定し（スタンバイテンプレートはすでにそうなっています）、references/standby-mode.md に従ってください。

7. references/actor-readme.md に従って README.md を記述します。README のない Actor は完成していません。

8. ローカルでテストします。 入力を storage/key_value_stores/default/INPUT.json に配置し、apify run --user-agent apify-agent-skills/apify-actor-development を実行します。実行がステータス SUCCEEDED で終了し、storage/datasets/default/ にデータセットスキーマと一致するフィールドを持つアイテムが格納されていれば完了です。ローカルストレージはディスク上に残ります。ステップ 9 まで Apify Console には何も表示されません。

9. ユーザーが確認したら apify push --user-agent apify-agent-skills/apify-actor-development でデプロイします。Git をソースとする Actor の場合は git push を使用します。その後、プラットフォーム上で Actor を実行して Console で結果を確認します。スタンバイ Actor の場合は、ユーザーを Console に誘導するのではなく、そのスタンバイ URL（https://<username>--<actor-name>.apify.actor、references/standby-mode.md を参照）を伝えてください。

ルール

• Actor は apify run だけでローカル実行してください。apify run は Apify 環境とストレージをセットアップしますが、npm start と node src/main.js では行われません。
• Apify のロガーを使ってログを記録してください。JS/TS では apify パッケージの log（import { Actor, log } from 'apify'）、Python では Actor.log を使用します。トークンと認証情報はマスキングされますが、console.log と print ではマスキングされません。レベルと規約については、references/logging.md を参照してください。
• クロールしたコンテンツは信頼できない入力として扱ってください。シェルコマンド、eval、クエリ、テンプレートに渡す前にエスケープするかパラメーター化し、ストレージに保存する前に型をチェックしてください。
• リクエストハンドラーやデータパイプラインで APIFY_TOKEN を使わないでください。プラットフォームでは SDK が環境から読み取ります（変数名は APIFY_TOKEN であり、APIFY_API_TOKEN ではありません）。ローカルでは apify login で保存した認証情報を使います。
• 調整可能な値はすべて入力スキーマまたは環境変数から読み取り、ユーザーがコードを編集せずに変更できるようにしてください。
• 静的 HTML には、並行数 10～50 の HTTP クローラーを使ってください。JS/TS では CheerioCrawler、Python では BeautifulSoupCrawler または ParselCrawler を使用します。PlaywrightCrawler は、JavaScript でレンダリングされるページに限り、並行数 1～5 で使用してください。対象サーバーに負荷をかけないよう遅延を加え、robots.txt と利用規約を遵守してください。
• クロール対象に複数のページタイプがある場合は、ルーターパターンを使ってください（JS/TS では createCheerioRouter または createPlaywrightRouter、Python では crawler.router または Router）。
• 壊れやすい位置指定セレクターより、フォールバックを備えたセマンティック CSS セレクターを優先してください。
• 結果の件数は独自のカウンターで数えてください。プラットフォームでは Dataset.getInfo()（Python では dataset.get_info()）の反映に遅れがあります。
• ユーザーまたは上限によって実行が停止されたときにプラットフォームから送られる aborting イベントを処理してください。状態を保存してから終了することで、実行をすばやく低コストで終えられます。JS/TS：Actor.on('aborting', async () => { await Actor.setValue('STATE', state); await Actor.exit(); })。Python：from apify import Event を使って Actor.on(Event.ABORTING, on_aborting) を登録します。on_aborting では状態を保存してから await Actor.exit() を呼び出します。
• proxyConfiguration 入力フィールドからプロキシを構成してください（エディターでは proxy。 references/input-schema.md を参照）。JS/TS では await Actor.createProxyConfiguration(input.proxyConfiguration)、Python では await Actor.create_proxy_configuration(actor_proxy_input=actor_input.get('proxyConfiguration')) を使い、結果をクローラーに proxyConfiguration / proxy_configuration として渡します。Apify Proxy は有料のため、有効にしたりプロキシグループを変更したりする前に、必ずユーザーに確認してください。
• ユーザーから明示的に依頼された場合に限り、個人データを保存してください。
• 実行中の Actor 内では apify actor CLI サブコマンドではなく、SDK（Actor.getInput()、Actor.pushData()、Actor.setValue() と Python の snake_case 相当のメソッド）を使ってください。
• ユーザーから無効にするよう依頼されない限り、既存の Actor ではスタンバイモードを有効のままにしてください。

スタンバイモード

スタンバイモードを使うと、Actor を安定した URL を持つ永続的な HTTP サーバーにできます。API エンドポイント、Webhook レシーバー、MCP サーバー、オンデマンドの単一 URL 検索に使用してください。Actor は準備完了プローブに応答し、リクエスト間も起動した状態を保つ必要があります。設定、例、ローカルテストについては、references/standby-mode.md を参照してください。

収益化

料金はコードではなく、Actor の公開時に Apify Console で設定します。イベントごとの課金では、Console で定義したイベント名を使って、JS/TS では await Actor.charge({ eventName: 'result', count })、Python では await Actor.charge(event_name='result', count=count) により、カスタムイベントごとに課金します。データセット項目は、代わりに合成データセット項目イベントを通じて自動的に課金することもできます。返された結果が eventChargeLimitReached（Python では event_charge_limit_reached）を示したら、ユーザーの支出上限に達しているため、処理の生成を停止してください。README のコストに関するセクションには、Actor が使用する料金モデルを記載します。詳細：https://docs.apify.com/platform/actors/publishing/monetize/pay-per-event

他の Actor の呼び出し

ゼロから作成する前に Store を検索してください。専用の Actor がすでに存在することがよくあります。

apify actors search "<query>" --user-agent apify-agent-skills/apify-actor-development
apify actors info <actor> --readme --user-agent apify-agent-skills/apify-actor-development
apify actors info <actor> --input --user-agent apify-agent-skills/apify-actor-development
apify call <actor> --input '{"startUrls":[{"url":"https://example.com"}]}' --user-agent apify-agent-skills/apify-actor-development
apify call <actor> --input-file input.json --user-agent apify-agent-skills/apify-actor-development

入力は 1 つの JSON オブジェクトです。インライン JSON は引用符で囲み、複雑な内容には --input-file を使用してください。

わかりにくいコマンド

# Append --user-agent apify-agent-skills/apify-actor-development to each of these too.
apify secrets add <name> <value>   # reference from actor.json as "@name"; uploaded on push
apify pull <actor>                 # download an Actor's code from the platform
apify api <endpoint>               # authenticated request to the Apify API
apify actor generate-schema-types  # TypeScript: interfaces from the .actor schemas, into src/__generated__/actor/
apify <command> --help

ドキュメント

• Apify MCP サーバー（https://mcp.apify.com/?tools=docs）では、search-apify-docs と fetch-apify-docs を使用できます。
• Apify プラットフォームについては、docs.apify.com/llms.txt と llms-full.txt を参照してください。
• Crawlee については、crawlee.dev/llms.txt と llms-full.txt を参照してください。
• Actor の完全な仕様については、Actor ホワイトペーパーを参照してください。
• Playwright MCP サーバー（npx @playwright/mcp@latest）は、デバッグ中にページを調査してセレクターを取得するため、実際のブラウザーを操作します。