ffcpe-catalog-entry-json

Catalog エントリー JSON（catalog-entry.json）

このスキルは、ワークフローで使用できるように、App Builder アクションを run-workflow カタログに登録する JSON ドキュメントの作成、レビュー、修正に使用します。カタログに関するすべての操作（一覧表示、登録、確認など）では、@adobe/aio-cli-plugin-ffcpe の aio ffcpe catalog コマンドを使用してください。curl や独自の HTTP クライアントは提案しないでください。

ファイル名と配置（App Builder プロジェクト）

ベストプラクティス： カタログエントリファイルはカスタムアクションごとに 1 つ作成し、<action-name>.entry.json という名前で、そのアクションの Web ソースおよびワーカーソースと同じディレクトリに配置します。

actions/<action-name>/
  <action-name>.web.ts
  <action-name>.worker.ts
  <action-name>.entry.json

• <action-name> は、実用上可能な範囲で、OpenWhisk アクションのベース名および mountFfcpeNodeRoutes／マニフェストの命名と一致させてください。
• ファイルの内容は、カタログの完全なペイロード（handlerType: "custom-action"、inputs／outputs、customActionConfig、検出フィールド）にします。スタブやポインターファイルにはしないでください。
• このパスを aio ffcpe catalog validate --file … および register --file … に渡します。リポジトリルートの catalog-entry.json は単発のサンプルには問題ありませんが、複数のアクションがあるアプリでは、アクションと同じ場所にある <action-name>.entry.json を優先してください。

Web／ワーカーのスキャフォールディング構成については、ffcpe-custom-node-sdk のスキル ffcpe-app-builder-actions を参照してください。

Adobe I/O CLI と FFCPE プラグインのインストール

1. Node.js — サポート対象の LTS バージョンを使用してください（このプラグインには Node 18+ が必要です）。

2. Adobe I/O CLI（aio） — グローバルにインストールして、実行できることを確認します。

   npm install -g @adobe/aio-cli
   aio --version
   

3. このプラグイン（@adobe/aio-cli-plugin-ffcpe） — aio にプラグインとしてインストールします。次のいずれかを1 つ使用してください。

   aio plugins:install @adobe/aio-cli-plugin-ffcpe
   

   または、Git URL（フォーク、機能ブランチ、社内ミラー）からインストールします。

   aio plugins:install https://github.com/adobe/aio-cli-plugin-ffcpe
   

adobe/aio-cli-plugin-ffcpe を使用しない場合は、URL を組織のリポジトリに置き換えてください。

4. 確認 — ffcpe トピックが使用可能であることを確認します（古い資料では、同じ機能を Workflow Builder と呼んでいる場合があります）。

   aio ffcpe catalog --help
   

5. カタログ呼び出しの認証 — CLI の他の Adobe I/O コマンドで使用するセッションと同じセッションを使用します。

   aio login
   aio console org select
   

インストール後に aio ffcpe が見つからない場合は、aio plugins を実行し、@adobe/aio-cli-plugin-ffcpe が一覧にあることを確認してください。必要に応じて、aio plugins:install で再インストールします。

orgId と認証

• カタログ JSON の本文に orgId を含めないでください。 API は x-gw-ims-org-id または Bearer アクセストークン（IMS プロファイル／JWT）から設定します。
• 登録には解決可能な組織が必要です。解決できない場合、API は 401 と orgId is required を返します。
• 複合キー： (orgId, actionType, version)。異なる組織は同じ actionType を実装できます。また、1 つの組織で複数のバージョン（例：1.0.0 と 2.0.0）を提供できます。組織固有のオーバーライドを提供する場合は、組み込みの actionType を再利用できます。

必須の構造（カスタムアクション）

• handlerType: "custom-action"。
• customActionConfig: 必須です。有効な HTTPS の submitEndpoint と statusEndpoint を指定します。ポーリングの設定は任意です。pollIntervalMs（デフォルトは通常 3000）、maxPollAttempts（例：100）、timeoutMs（例：300000）。
• version: 有効なセマンティックバージョン（例：1.0.0）。
• inputs／outputs: それぞれに少なくとも 1 つのポートが必要です。ポートの name は、それぞれの配列内で一意でなければなりません。
• parameters: 各 name は parameters 内で一意でなければなりません（配列は空でもかまいません）。

API は従来の名前（inputPorts、outputPorts、enabled、appBuilderConfig）を受け付ける場合がありますが、inputs、outputs、disabled、workflowEnabled、customActionConfig を優先してください。

エージェントとディスカバリー（登録に必須）

これらのフィールドは、エージェントがアクションを提案し、連鎖させるのに役立ちます。各フィールドに少なくとも1つ登録してください。あとでPUTを使って調整できます。

フィールド	記入内容	最小数
relatedActions	連鎖または補完するアクションのactionType値	1
usage.commonPatterns	このアクションがワークフローに適する状況	1
usage.bestPractices	より良い結果を得るためのヒント	1

画像向けの例：

"relatedActions": ["input-images", "remove-background", "image-analysis"],
"usage": {
  "commonPatterns": [
    "Chain after background removal for product descriptions",
    "Use for accessibility captions"
  ],
  "bestPractices": [
    "Use clear prompts; high-res input improves results",
    "Specify output format expectations"
  ]
}

動画向けの例：

"relatedActions": ["input-videos", "video-transcribe", "preview-videos"],
"usage": {
  "commonPatterns": [
    "Process video clips for analysis",
    "Generate subtitles from video"
  ],
  "bestPractices": [
    "Ensure supported video formats",
    "Clear audio improves transcription quality"
  ]
}

**aio ffcpe catalog listを使って有効なactionType値を確認します（Adobe組み込みアクションも含めるには--include-coreを追加します）。生のAPI形式の出力には--json**を使います。

カタログエントリー全体の例

**aio app deploy**の出力にあるHTTPS App Builder／Runtime API URLを使います。プレースホルダーは、デプロイしたWebアクションのベースURLとルートのサフィックスに置き換えてください。

デプロイ後のエンドポイントの導出：

# Deploy prints:
https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web

# Catalog:
submitEndpoint → …/my-action-web/submit
statusEndpoint → …/my-action-web/status

**/api/v1/web/**を使います（/apis/v1/ではありません）。Runtimeのホスト名の名前空間は小文字です。

{
  "actionType": "image-to-text",
  "version": "1.0.0",
  "name": "Image to Text",
  "description": "Analyzes images and returns text descriptions.",
  "category": "custom",
  "disabled": false,
  "workflowEnabled": true,
  "aliases": [],
  "tags": ["ai", "image", "text"],

  "inputs": [
    {
      "name": "image",
      "type": "image",
      "required": true,
      "mimeTypes": ["image/jpeg", "image/png", "image/gif", "image/webp"],
      "description": "One or more images to analyze"
    }
  ],

  "outputs": [
    {
      "name": "text",
      "type": "text",
      "mimeTypes": ["text/plain"],
      "description": "Text description of the image(s)"
    }
  ],

  "parameters": [
    {
      "name": "prompt",
      "type": "string",
      "required": false,
      "defaultValue": "Describe what is happening in these images.",
      "description": "Custom prompt for image analysis"
    }
  ],

  "relatedActions": ["input-images", "remove-background", "image-analysis"],
  "usage": {
    "commonPatterns": [
      "Chain after background removal for product descriptions",
      "Use for accessibility captions"
    ],
    "bestPractices": [
      "Use clear prompts; high-res input improves results",
      "Specify output format expectations"
    ]
  },

  "handlerType": "custom-action",
  "customActionConfig": {
    "submitEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/submit",
    "statusEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/status",
    "pollIntervalMs": 3000,
    "maxPollAttempts": 100,
    "timeoutMs": 300000,
    "authentication": { "type": "ims_service_token" }
  }
}

customActionConfig.authentication

App BuilderとmountFfcpeNodeRoutesのデフォルト： **ims_service_tokenを使います。SDKはauthenticate: nullを渡さない限り、/submitと/statusでIMSインバウンド認証を有効にします。カタログでnone**を宣言していてもWebアクションでIMSが必要な場合、ワークフロー実行の呼び出しは失敗し、手動のcurlではMissing required header(s): Authorization, x-api-keyが返されます。

**noneを使うのは、Webアクションで認証を明示的に無効にしていて（mountFfcpeNodeRoutes**にauthenticate: nullを指定）、セキュリティレビューで許可されている場合に限ります。

JSON	用途
{ "type": "ims_service_token" }	推奨されるデフォルト。 ワークフロー実行がIMSサービストークンを取得し、**x-api-key: run-workflow-serviceとAuthorizationを付けてエンドポイントを呼び出します。デフォルトのmountFfcpeNodeRoutes**認証に一致します。
{ "type": "none" }	認証なし — Webアクションで**authenticate: null**を渡す場合に限ります
{ "type": "api-key", "headerName": "X-API-Key", "secretName": "MY_API_KEY" }	APIキーのヘッダー。secretNameは環境変数またはシークレットを参照します
{ "type": "bearer", "secretName": "MY_BEARER_TOKEN" }	環境変数またはシークレットから取得するBearerトークン

カタログの管理（Adobe I/O CLI）

生のHTTPではなく、必ず**aio ffcpe catalog …（このプラグイン）を使ってください。前提条件：aio login、aio console org selectを実行し、このプラグインをインストールしておく必要があります。オプション：対応するコマンドでは--base-url／AIO_FFCPE_CATALOG_BASE_URL、--org-id、--api-key、--json**を指定できます。

目的	コマンド
新しいアクションを登録	aio ffcpe catalog register --file ./actions/<action-name>/<action-name>.entry.json（オプションで**--strict**）
1つのアクションを確認	aio ffcpe catalog inspect <actionType>（オプションで**--version <semver>**）
アクションを一覧表示	aio ffcpe catalog list（フィルター：--workflow-enabled、--category、--include-tags、--exclude-tags、--include-core、--compact、--json）
全体を置き換え	aio ffcpe catalog update <actionType> --file ./actions/<action-name>/<action-name>.entry.json（オプションで**--version、--strict**）
無効化（デフォルトでUIに非表示）	aio ffcpe catalog disable <actionType>
再度有効化	aio ffcpe catalog enable <actionType>
削除	aio ffcpe catalog delete <actionType>（特定のsemverを削除するにはオプションで**--version**を指定します。省略すると、そのタイプのすべてのカスタムバージョンが削除されます）
ファイルのみを検証	aio ffcpe catalog validate --file ./actions/<action-name>/<action-name>.entry.json

正確なフラグの一覧は、**aio ffcpe catalog <command> --help**を実行して確認してください。

ワークフロー JSON：actionSource とポート

組み込みカタログエントリとカスタムカタログエントリが同じ actionType を共有する場合、actionSource によって実装を選択します。

値	動作
省略または "built-in"	組み込みを優先し、次にカタログを使用します（後方互換性があります）。
"custom"	組織のカスタムカタログエントリのみを使用し、組み込みは無視されます。カスタムエントリが存在しない場合は失敗します。組織は認証情報から特定されるため、この動作を使用するワークフローに orgId を含めないでください。

カスタムの remove-background を強制するアクションノードの例：

{
  "actionId": "rb-001",
  "actionType": "remove-background",
  "actionSource": "custom",
  "parameters": {}
}

接続： sourcePort / targetPort は、カタログ（および上流／下流ノード）の outputs[].name と inputs[].name に一致する必要があります。ポート名の不一致は、実行時エラーの一般的な原因です。

最小パターン： input-images の outputs ポートを、カスタムアクションの入力ポート名（例：image）に接続します。連結したフロー（例：入力 → remove-background → image-to-text）では、各 connections[] エントリが、送信元の actionId と sourcePort を、宛先の actionId と targetPort に接続します。

検証ルール（登録時）

1. actionType は、特定の version において組織ごとに一意である必要があります。組織のオーバーライドでは、組み込みと同じ値を使用できます。
2. actionType はケバブケース（小文字、数字、ハイフン）である必要があります。
3. これらの登録では、handlerType は "custom-action" である必要があります。
4. handlerType が custom-action の場合、customActionConfig が必要です。
5. submitEndpoint と statusEndpoint は、有効な HTTPS URL である必要があります。
6. inputs： ポートが 1 つ以上必要です。
7. outputs： ポートが 1 つ以上必要です。
8. ポートの name は、inputs 内および outputs 内でそれぞれ一意である必要があります。
9. パラメーターの name は、parameters 内で一意である必要があります。
10. orgId は JSON 本文ではなく、認証情報に基づいて API によって適用されます。呼び出し側は、組織を特定できる認証情報を送信する必要があります。
11. relatedActions： 1 つ以上のエントリが必要です。
12. usage.commonPatterns： 1 つ以上のエントリが必要です。
13. usage.bestPractices： 1 つ以上のエントリが必要です。

エージェントのワークフロー

1. actionType、version、エンドポイント、ポート、パラメーター、認証を確認します。
2. relatedActions と usage に具体的で正確な文字列を入力します（カタログ一覧を使用して実在する actionType ID を選びます）。
3. 最終的な JSON をフェンス付きの json ブロックで出力し、orgId は省略します。
4. aio ffcpe catalog validate --file … を実行してから、aio ffcpe catalog register --file … を実行するよう提案します（どちらも同じ JSON ファイルを使用します）。

トラブルシューティング

orgId is required (401)

• CLI リクエストから組織を特定できませんでした。
• aio console org select を実行して再試行するか、オーバーライドが必要な場合は aio ffcpe catalog コマンドに --org-id を渡してください。

relatedActions / usage.commonPatterns / usage.bestPractices が必要です

• それぞれに少なくとも 1 つの項目を追加してください（上記の エージェントと検出 を参照）。
• 有効な relatedActions の対象を選ぶには、aio ffcpe catalog list（組み込み ID が必要な場合は --include-core も指定）を使用してください。

アクションタイプはすでに存在します

• 組織／バージョンのコンテキストにおいて、その actionType を使用する登録がすでに存在します。
• aio ffcpe catalog update <actionType> --file … を使用するか、別の actionType を選択してください。

エンドポイント URL が無効です

• submitEndpoint / statusEndpoint は、有効な HTTPS URL である必要があります（通常は Runtime web action の URL です）。
• aio app deploy から web action base URL をコピーし、末尾に /submit と /status を追加してください。
• /apis/v1/ ではなく、/api/v1/web/<package>/<web-action> を使用してください。

認証の不一致（Missing required header(s): Authorization, x-api-key）

• デフォルトの mountFfcpeNodeRoutes は IMS のインバウンド認証を有効にします。
• web action が authenticate: null を渡す場合を除き、カタログでは none ではなく "authentication": { "type": "ims_service_token" } を宣言する必要があります。
• .entry.json の認証を修正した後、aio ffcpe catalog update <actionType> --file … を実行してください。

アクションは登録されているが、ワークフローが失敗する

• App Builder アプリがデプロイされ、想定される送信／ステータスのコントラクトを実装していることを確認してください。
• カタログのポート名が、アプリとワークフロー接続で想定される名前と一致している必要があります。
• 組み込みの実装とカスタム実装の両方が存在する場合は、**actionSource**を確認してください。