apify-actorization

Apify の Actor 化

Actor 化では、既存のソフトウェアを Apify プラットフォームと互換性のある再利用可能なサーバーレスアプリケーションに変換します。Actor は Docker イメージとしてパッケージ化されたプログラムで、明確に定義された JSON 入力を受け取り、処理を実行し、必要に応じて構造化された JSON 出力を生成します。

初期化、インストール、デプロイの前に、既存のファイルを確認し、その状態を保持してください。対象のアカウント／Actor、ソースコードのライセンス、アップロード済みのファイル／シークレット、ネットワークの接続先、支出／課金の上限を確認してください。ローカルでの変換を許可したからといって、クラウドへのアップロード、Store への公開、収益化が許可されたことにはなりません。レビュー済みの SDK／CLI／ベースイメージのバージョンを固定し、そのバージョンに照らしてスキーマを検証してください。

クイックスタート

1. プロジェクトのルートで apify init を実行します
2. SDK のライフサイクルでコードをラップします（以下の言語別セクションを参照してください）
3. .actor/input_schema.json を設定します
4. apify run --input '{"key": "value"}' でテストします
5. apify push でデプロイします

このスキルを使用する場面

• 既存のプロジェクトを Apify プラットフォームで実行できるように変換する場合
• プロジェクトに Apify SDK の統合を追加する場合
• CLI ツールやスクリプトを Actor としてラップする場合
• Crawlee プロジェクトを Apify に移行する場合

前提条件

apify CLI がインストールされていることを確認します。

apify --help

インストールされていない場合：

brew install apify-cli

# Or: npm install -g apify-cli
# Or install from an official release package that your OS package manager verifies

CLI にログインしていることを確認します。

apify info  # Should return your username

ログインしていない場合は、APIFY_TOKEN 環境変数が定義されているか確認します。定義されていない場合は、https://console.apify.com/settings/integrations でトークンを生成し、トークンそのものをコマンド履歴に残さずにシェルまたはシークレットマネージャーに追加するようユーザーに依頼し、次を実行します。

apify login

Actor 化チェックリスト

進捗を追跡するため、このチェックリストをコピーしてください。

• ステップ 1：プロジェクトを分析する（言語、エントリーポイント、入力、出力）
• ステップ 2：apify init を実行して Actor の構成を作成する
• ステップ 3：言語別の SDK 統合を適用する
• ステップ 4：.actor/input_schema.json を設定する
• ステップ 5：.actor/output_schema.json を設定する（該当する場合）
• ステップ 6：.actor/actor.json のメタデータを更新する
• ステップ 7：apify run でローカルテストを実施する
• ステップ 8：apify push でデプロイする

ステップ 1：プロジェクトを分析する

変更を加える前に、プロジェクトを把握してください。

1. 言語を特定する - JavaScript/TypeScript、Python、その他
2. エントリーポイントを探す - 実行を開始するメインファイル
3. 入力を特定する - コマンドライン引数、環境変数、設定ファイル
4. 出力を特定する - ファイル、コンソール出力、API レスポンス
5. 状態を確認する - 実行間でデータを保持する必要があるか

ステップ 2：Actor の構成を初期化する

プロジェクトのルートで次を実行します。

apify init

次のファイルが作成されます。

• .actor/actor.json - Actor の設定とメタデータ
• .actor/input_schema.json - Apify Console 用の入力定義
• Dockerfile（存在しない場合）- コンテナーイメージの定義

ステップ 3：言語別の変更を適用する

プロジェクトの言語に応じて選択してください。

• JavaScript/TypeScript：js-ts-actorization.md を参照してください
• Python：python-actorization.md を参照してください
• その他の言語（CLI ベース）：cli-actorization.md を参照してください

クイックリファレンス

言語	インストール	コードのラップ
JS/TS	npm install apify	await Actor.init() ... await Actor.exit()
Python	pip install apify	async with Actor:
その他	ラッパースクリプトで CLI を使用	apify actor:get-input / apify actor:push-data

ステップ 4～6：スキーマを設定する

schemas-and-output.md で、次の項目の詳細な設定を確認してください。

• 入力スキーマ（.actor/input_schema.json）
• 出力スキーマ（.actor/output_schema.json）
• Actor の設定（.actor/actor.json）
• 状態管理（リクエストキュー、キーバリューストア）

@apify/json_schemas npm パッケージに照らしてスキーマを検証してください。

ステップ 7：ローカルでテストする

インライン入力を使ってアクターを実行します（JS/TS および Python アクターの場合）。

apify run --input '{"startUrl": "https://example.com", "maxItems": 10}'

または、入力ファイルを使用します。

apify run --input-file ./test-input.json

選択した言語で文書化されているローカル CLI の手順を使用してください。ストレージのパージに関するデフォルト設定を確認し、無関係なローカルデータは保持してください。SDK やテストの直接実行も適切な場合があります。ローカル実行でも、設定によってはネットワークリクエストが発生したり、クラウドストレージが使用されたりすることがあります。合成フィクスチャとテストアカウントを使用してください。

ステップ 8：デプロイする

apify push

これにより、Apify プラットフォーム上でアクターがアップロードされ、ビルドされます。

収益化（任意）

デプロイ後、Apify Store でアクターを収益化できます。推奨モデルは Pay Per Event（PPE） です。

• スクレイピングした結果／アイテムごと
• 処理したページごと
• 実行した API 呼び出しごと

Apify Console の Actor > Monetization で PPE を設定します。コード内で await Actor.charge('result') を使ってイベントに課金します。

その他の選択肢：現在サポートされているその他の Store モデル、または無料実行。無料の Actor が自動的にオープンソースになるわけではありません。ライセンスとソースコードの公開は別のものです。

デプロイ前チェックリスト

• .actor/actor.json が存在し、正しい名前と説明が設定されている
• .actor/actor.json が @apify/json_schemas（actor.schema.json）に対して検証されている
• .actor/input_schema.json で必須の入力がすべて定義されている
• .actor/input_schema.json が @apify/json_schemas（input.schema.json）に対して検証されている
• .actor/output_schema.json で出力構造が定義されている（該当する場合）
• .actor/output_schema.json が @apify/json_schemas（output.schema.json）に対して検証されている
• Dockerfile が存在し、正常にビルドできる
• メインコードが Actor.init() / Actor.exit() で囲まれている（JS/TS）
• メインコードが async with Actor: で囲まれている（Python）
• 入力が Actor.getInput() / Actor.get_input() 経由で読み込まれている
• 出力に Actor.pushData() またはキーバリューストアが使用されている
• apify run がテスト入力で正常に実行される
• actor.json の meta セクションに generatedBy が設定されている

Apify MCP ツール

MCP サーバーが設定されている場合は、ドキュメントの参照に以下のツールを使用してください。

• search-apify-docs - ドキュメントを検索する
• fetch-apify-docs - ドキュメントのページ全体を取得する

それ以外の場合は、MCP サーバーの URL を使用してください：https://mcp.apify.com/?tools=docs。

リソース

• Actorization Academy - 詳細なガイド
• Apify SDK for JavaScript - SDK の完全なリファレンス
• Apify SDK for Python - SDK の完全なリファレンス
• Apify CLI Reference - CLI コマンド
• Actor Specification - 完全な仕様

制限事項

• 上記で説明した範囲にタスクが明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を停止して確認してください。