make-api-shell-connection-workflow

Make API シェル＋接続ワークフロー

特定のワークフローファミリーでは、このスキルを使用します。

• 正しい Make アプリと、そのアプリ固有の API 呼び出しモジュールを見つけます
• StartSubscenario、1 つのアプリ API 呼び出しモジュール、ReturnData で構成される再利用可能なシェルシナリオを再利用または作成します
• そのシェルに適した既存の接続を再利用するか、必要な接続リクエストを作成します
• 認証が完了したら、選択した接続をシェルに設定します
• シナリオを実行し、メール、CRM、チケットなどのシステム向けの汎用 SaaS データ取得トランスポートとして使用します

このスキルは、主にプロビジョニングとシェル構築を対象としています。ビジネスデータの取得は第 2 フェーズとして扱います。このフェーズは、接続の準備が整い、現在のワークスペースメタデータに照らしてシェルの検証が完了してから開始します。

ここで説明する汎用シェルは、ビジネスロジックではなく、API トランスポートのラッパーです。メール、CRM、チケット管理、サポート、マーケティング、タスク管理など、Make が対応するあらゆる SaaS アプリで再利用可能な API エンドポイントとして動作する必要があります。

既知の Make モジュール ID：Make Code モジュールは "module": "code:ExecuteCode" です。

クイックルーティング

現在のタスクに合ったファイルを読みます。

タスク	リファレンス
アプリ、モジュール、接続タイプのレイヤーを見つける	検出とシェル
認証情報リクエストを作成、確認、または解決する	接続リクエスト
接続後のデータ取得方法を選択して実行する	データ取得の実行
シェル実行後にプロバイダーの認証エラーやスコープエラーを修正する	データ取得の実行
例をサニタイズして、共有可能な公開バージョンを準備する	サニタイズと共有
汎用ブループリントテンプレートから開始する	シェルのサンプルブループリント
プロバイダーに Make アプリがない場合：noAuth／API キー／Basic 認証／OAuth 2.0 を使った汎用 HTTP シェル	HTTP フォールバックシェル

新規エージェントの操作手順

新規エージェントが「未読メールを取得して」「未対応の CRM リードを取得して」「Jira チケットを取得して」などのリクエストを受けた場合、既定の操作手順は次のとおりです。

1. プロバイダーの特定先を確定します。
   • メール：Gmail、Outlook、その他
   • CRM：HubSpot、Salesforce、その他
   • チケット管理：Jira、Zendesk、Linear、その他
2. リクエストが曖昧な場合は、対象のアカウント、メールボックス、ワークスペース、プロジェクト、またはキューを確定します。
3. 使用中の Make ゾーン、組織、チームを確定します。
4. プロバイダーアプリを確実に特定します。GET /api/v2/imt/apps は search、limit、scoredSearch を無視し、常に約 4,000 件のアプリカタログ全体を返すため、サーバー側の検索に頼らないでください。代わりに、まず厳選された主要アプリのカタログをローカルで検索します（ヘルパー環境では、search_apps(query=...) がこれを行います）。そこで一致するものがなかった場合に限り、カタログ全体を一度取得し、クライアント側で name と label を大文字と小文字を区別せずに絞り込みます。クエリ内のすべての単語をスコアに反映します。完全一致するフレーズがない場合、候補として扱うには最初のクエリ単語が一致している必要があり、最も高い順位の結果が推奨アプリです。
   • 自動選択できるのは、Make 検証済みアプリと組織独自のカスタム／SDK アプリのみです。コミュニティアプリ（communityApp-*）は照合対象外です。カスタムアプリ（カタログのプレフィックスが app#*）は使用できます。正式な確認方法として、GET /api/v2/imt/apps-meta には、その組織で利用可能な検証済みアプリとカスタムアプリがすべて表示されます（カスタムアプリ名は app# プレフィックスなしで表示されます）。組み込みユーティリティの疑似アプリ（builtin、util、gateway、regexp）は SaaS プロバイダーではないため、検索結果に表示してはいけません。プロバイダーがコミュニティアプリとしてしか存在しない場合は、「アプリなし」と判断し、代わりに汎用 HTTP フォールバックシェルを構築します。詳しくはHTTP フォールバックシェルを参照してください。
5. GET /api/v2/imt/apps/{appName}/{version} で選択したアプリを調べ、API 呼び出しモジュールの正確なスラッグと、両方の接続タイプ層を記録します。
6. 既存の適切な接続を再利用するのは、詳細と稼働状況を確認してからにします：GET /api/v2/connections/{connectionId} に続けて POST /api/v2/connections/{connectionId}/test を実行します。
7. 既存のシェルを再利用するのは、既存の適切な接続を再利用する場合に限ります。新しい接続を作成する必要がある場合は、古いシェルを新たに認証したアカウントに付け替えるのではなく、その新しい接続用の新しいシェルを作成します。
8. 適切な接続が存在しない場合に限り、認証情報のリクエストを作成します。
9. 接続についての判断が確定した後、上記の再利用ルールに従ってシェルを作成または更新し、シェルが実行可能であることを確認します。
10. まず API 呼び出しシェルを通じて、可能な限り範囲を絞った取得リクエストを実行します。
11. 最初のシェル実行で正常な経路が確認できてから、一覧／検索 → 詳細 → 正規化へと処理を広げます。
12. そのプロバイダー用の Make アプリが存在しない場合でも、諦めずに http:MakeRequest を使用して汎用 HTTP フォールバックシェルを構築します。詳しくはHTTP フォールバックシェルを参照してください。

エージェントは、この手順を踏まずに「ユーザーが SaaS データを求めている」から「新しい接続を作成する」、または「直接 SDK を呼び出す」へ飛躍してはいけません。

入力の確認ゲート

プロビジョニングまたは取得の前に、次の入力を明示的に確定してください。

• プロバイダーの特定先
• 複数のアカウントまたはメールボックスが考えられる場合は、対象アカウントの識別情報
• 現在のトークンの所有者と異なる可能性がある場合は、認証情報リクエストの送信先
• Make ゾーン、組織、チーム

いずれかの項目が不足していて、安全に特定できない場合は処理を中止し、その不足している項目だけを尋ねてください。

基本ルール

1. API 呼び出しモジュール名を推測しないでください。現在の Make メタデータから特定してください。
2. Gmail、Outlook、HubSpot などのアプリ例は説明用であり、普遍的なデフォルトとして扱わないでください。
3. 次の 2 つの型レイヤーを分けてください。
   • シナリオ／モジュールの接続パラメーター型
   • 接続一覧または認証情報リクエストの型
4. 作成する前に、再利用を優先してください。
   • 新しい認証情報リクエストより、既存の適切な接続を優先する
   • 既存の適切な接続を再利用する場合に限り、既存のシェルシナリオを再利用する
   • 新たに認可された接続には、新たに作成したシェルを割り当てる
5. このワークフロー群では、業務データの取得に Make の標準検索／一覧／取得モジュールを使わないでください。常に Make アプリの API 呼び出しシェルを通じて取得してください。
6. 既存の稼働中シナリオに書き込む場合や、接続マッピングを置き換える場合は、事前に確認を求めてください。
7. 公開例はサニタイズしてください。実名、ユーザー ID、チーム ID、組織 ID、テナント固有のホスト、または単一の非公開ワークスペースだけで普遍的なルールが証明されるかのような主張を含めないでください。
8. 例ではクリーンなベース URL 変数を使用してください。公開例では、デフォルトを https://us1.make.com とし、プレースホルダーは汎用的なものにしてください。現在のユーザーが明示的にそのゾーンを提示または指定しない限り、公開例で we.make.com に言及しないでください。有効なゾーンは eu1、eu2、us1、us2、we です。ユーザーがカスタムゾーンまたは BASE_URL を指定した場合は、それを受け入れてください。
9. 次の 4 つのフェーズを明確に分けてください。
   • プロバイダーとアプリの解決
   • 接続のプロビジョニング
   • シェルのプロビジョニング
   • 取得の実行と出力の正規化
10. 汎用の 3 モジュール構成がすべてのアプリで自動的に有効化できるとは想定しないでください。有効化の前に、ミドルモジュールのメタデータを、アクティブなワークスペース内にある同じアプリとバージョンの実際のブループリントまたはモジュールエクスポートと照合してください。
11. ExpectDataAny を使用する scenario-service:ReturnData を含む汎用 API シェル契約では、最後のマッパーでアプリモジュールのレスポンスボディを data: {{MIDDLE_API_MODULE_ID.body}} として返す必要があります。
12. このスキルの汎用サンプルブループリントでは、ミドルの API 呼び出しモジュール ID は 3 なので、サンプルのマッパーは data: {{3.body}} です。実際のブループリントでモジュール ID が異なる場合は、実際のミドルモジュール ID を使用してください。たとえば、Make UI のエクスポートでは StartSubscenario が 2、API 呼び出しモジュールが 5、ReturnData が 4 の場合、正しいマッパーは data: {{5.body}} です。
13. バンドル全体のほうが適切に見えるという理由だけで、このシェル契約のデフォルトを {{MIDDLE_API_MODULE_ID}} や {{MIDDLE_API_MODULE_ID.data}} に置き換えないでください。シェルが返すのは Make モジュールのバンドル全体ではなく、API レスポンスボディです。
14. 検証のため、実際の実行バンドルも引き続き確認してください。ただし、それを使って body に意図したペイロードまたはエラーオブジェクトが含まれていることを確認し、汎用シェル契約を再定義しないでください。
15. チームスコープの呼び出しを行う前に、アクティブなワークスペースのゾーンを特定してください。GET /api/v2/users/me と GET /api/v2/imt/apps/... は複数のゾーンで成功する場合がありますが、誤ったゾーンで GET /api/v2/connections?teamId=... やシナリオエンドポイントを呼び出すと、403 Permission denied で失敗することがあります。
16. REST の /api/v2/connections エンドポイントでは、type=... または type[]=... で絞り込んでください。MCP ツールで accountName という用語が使われているからといって、accountName=... などのクエリパラメーターが有効になると想定しないでください。
17. ユーザーに OAuth シークレット、API キー、パスワードをそのままチャットに貼り付けるよう求めないでください。新しい接続を作成する必要がある場合は、必ず認証情報リクエストを使用してください。リクエスト先に応じて方法を選択してください。現在の Make ユーザーには、セルフサービスのエンドポイント（actions/create、actions/create-by-credentials）が幅広いプランで利用できます。異なるユーザーに認証情報をリクエストする場合（requests/v2）に限り、license.credentialRequests によって制限される Enterprise／Partner 機能です（接続リクエスト の「まずリクエスト先に応じてリクエスト方法を選択する」を参照）。どのリクエスト方法も使えない場合は、シナリオエディターで接続を作成するよう案内してください。いずれの方法でも、認証情報を貼り付ける形式（Bearer プレフィックス付きか、キーのみか）を正確に伝えてください。ユーザーが知っていると決めつけないでください。
18. ユーザーの依頼が曖昧な場合は、まず具体的なプロバイダーとアカウントを確認してください。すでに明確な場合は、再度確認しないでください。
19. モジュール 2 のリクエストメソッドが PUT、PATCH、DELETE の場合は、実行前に明示的に警告してください。これらのメソッドは受動的な取得ではなく、稼働中の SaaS に対する変更操作として扱ってください。
20. シナリオの実行に StartSubscenario.metadata.interface だけで十分だと想定しないでください。オンデマンドシェルの作成または更新後、シナリオレベルのインターフェースを /api/v2/scenarios/{scenarioId}/interface で明示的に設定し、最初の実行前に検証してください。
21. このシェル群の標準的な実行方法として /api/v2/scenarios/{scenarioId}/run を使用してください。業務ペイロードはシナリオインターフェースと完全に一致するキーを使い、data の下に渡してください。検証実行では responsive: true を優先してください。
22. クエリパラメーターを、シェルの第一級の入力として qs という名前で公開してください。Gmail の検索オプション、Drive の fields、Drive の q、Graph の $select、ページネーション、supportsAllDrives など、プロバイダー API のクエリパラメーターには qs を使用してください。呼び出し元が path にクエリ文字列を指定した場合は、シェルを実行する前にそれを qs に正規化してください。
23. Make UI のエクスポートと Make のシナリオ作成／更新 API の間でブループリントを移動する場合は、構造を意識して正規化してください。UI／エクスポートのアーティファクトではフローが subflows[0].flow に格納されていることがありますが、シナリオ作成／更新のペイロードではトップレベルの flow が必要です。正規化せずに生の UI エクスポートを作成／更新 API に送信しないでください。
24. シェルの再利用はプロバイダーファミリー単位ではなく、アプリ単位です。同じベンダースイートに属しているというだけで、あるアプリモジュールを使って構築したシェルを別のアプリモジュールに付け替えないでください。
25. 既存の接続、または既存の接続を参照するシェルを再利用する前に、Make の接続検証 API POST /api/v2/connections/{connectionId}/test を呼び出してください。verified: true を含むレスポンスが、接続の有効性を示す証明になります。古い認証情報リクエストのステータスがあっても、検証済みの接続の有効性は否定されません。有効性は、プロバイダーがすべてのパス、メソッド、スコープを認可する証明にはなりません。プロバイダーによる認可が証明されるのは、意図した操作でシェル実行が成功した場合に限られます。プロバイダーの認証またはスコープに関するエラーが発生した場合は、認可修復プレイブックを使用してください。
26. ユーザーの認可後に処理を再開する場合は、保存済みの認証情報リクエストの requestId を再利用してください。リクエストを確認してから、接続を一覧表示して検証してください。同じアプリ／アカウントについて、有効なリクエストの処理中に新しい認証情報リクエストを作成しないでください。
27. 将来の日時を示す expire タイムスタンプは有効として扱ってください。無効とみなすのは、期限切れ、接続の取り消し、検証の失敗、またはプロバイダーの認証エラーがある場合に限ります。

アプリのバインディングと接続ファミリーの対応表

シェルのパターンは汎用的ですが、実際の各シェルは、検出された1つのMakeアプリモジュールにバインドされます。

「Google」や「Microsoft」を、互換性のある単一の接続ファミリーとして扱わないでください。Makeでは、アプリのファミリーが製品の用途ごとに分かれていることがよくあります。

一般的な例：

ビジネス用途	API呼び出しモジュールの例	シナリオ／モジュールの接続パラメーター型	一般的な接続の一覧表示またはリクエスト型
Gmail	google-email:makeAnApiCall	account:google-email	google-email または google-restricted などのワークスペース固有のバリエーション
Google Calendar／Sheets／Drive系アプリ	メタデータから検出されたアプリ固有のGoogleモジュール	一般的には account:google	一般的には google
Outlook／Microsoftメール	microsoft-email:makeApiCall	account:azure	azure

これに基づくルール：

• 検出されたアプリ、モジュールのスラッグ、バージョン、接続ファミリーが引き続き一致する場合に限り、シェルを再利用してください。
• アカウントの識別情報とスコープがリクエストされた操作に引き続き適合する場合に限り、接続を再利用してください。
• 別のアカウントまたは接続ファミリー用に新しい接続を認証した場合は、既存のシェルの接続先を黙って切り替えるのではなく、その接続用に新しいシェルを作成してください。

判断に迷った場合は、ベンダー名から互換性を推測せず、正確なアプリメタデータと既存の接続の詳細を確認してください。

標準的なシェル構成

再利用可能なシェルは、次の3つのモジュールだけで構成されます。

1. scenario-service:StartSubscenario
2. メタデータから検出された、アプリ固有のMake API呼び出しモジュール1つ
3. scenario-service:ReturnData

StartSubscenarioを通じて、次のシェル入力を公開します。

• path
• method
• header
• qs
• body

検出された中央のモジュールだけを、シェルのアプリ固有の部分として使用します。

汎用シェルの契約

このシェルは、汎用APIエンドポイントのラッパーです。

次を受け取ります。

• path
• method
• header
• qs
• body

これらの値を、アプリ固有のMake API呼び出しモジュールに渡します。

デフォルトの取得には GET を使用してください。PUT、PATCH、DELETE は書き込み／破壊的なメソッドとして扱い、実行前にユーザーの明示的な確認を必須としてください。

返すものは、次の1つだけです。

• アプリ固有のMake API呼び出しモジュールからのレスポンス本文

したがって、シェルの契約は次のとおりです。

{
  "data": "{{MIDDLE_API_MODULE_ID.body}}"
}

このスキルの汎用的な例示ブループリントでは、MIDDLE_API_MODULE_ID は 3 なので、例の値は {{3.body}} です。実際のMakeエクスポートでは、必ずモジュールIDを確認し、実際のAPI呼び出しモジュールIDを使用してください。

この契約はSaaSプロバイダー全般に共通です。中央のモジュールがGmail、Outlook、HubSpot、Jira、または別のプロバイダー固有のMake API呼び出しモジュールのどれに接続していても適用されます。

シェルは、次のものを返そうとしてはいけません。

• Makeバンドル全体 {{3}}
• {{3.data}} のような、推測したネストされたフィールド
• 本文と混在したトランスポートメタデータ

シェルはトランスポートだけを担います。ビジネス上の解釈は後で行います。

2段階の運用モデル

フェーズA：プロビジョニング

まず、次の手順を完了します。

1. プロバイダーと正確なMakeアプリを特定する
2. 正確なアプリのバージョンとモジュールのスラッグを検出する
3. 接続タイプの両方の階層を特定する
4. 正しいアカウントの識別情報とスコープに適した既存の接続を探す
5. POST /api/v2/connections/{connectionId}/test で候補となる接続を検証する
6. 検証済みの接続に対して、すでに契約に適合する既存のシナリオシェルがあるか確認する
7. 再利用に失敗した場合に限り、認証情報リクエストを作成するか、既存のものを解決する
8. 新しい接続を作成した場合は新しいシェルを作成し、既存の接続を再利用する場合に限り既存のシェルを更新する
9. 選択した接続でシェルが実行されることを検証する

フェーズAの完了時に得られる成果物：

• 接続の準備が整ったAPI呼び出し用シナリオシェル

フェーズ B：取得

フェーズ A が成功した後にのみ、以下を実行します。

1. API 呼び出しシェルを通じて取得呼び出しを設定します
2. 範囲を絞った検証クエリまたはルックアップを実行します
3. 実際の出力バンドルの形状を確認します
4. ReturnData は汎用シェルの契約として固定し、必要な場合は下流の正規化のみを更新します
5. 再実行し、ユーザー向けペイロードを検証します

認証情報のリクエストが成功したからといって、取得の段階がすでに解決済みだと見なさないでください。

重要：

• このワークフローファミリーでは、汎用の 3 モジュール API シェルのみを取得のトランスポートとして使用します
• シェルの契約は data: {{MIDDLE_API_MODULE_ID.body}} に固定してください。MIDDLE_API_MODULE_ID はブループリント内の実際のアプリ API 呼び出しモジュール ID です
• フォールバックや最適化として、ネイティブの取得／検索／一覧表示モジュールに切り替えないでください
• 既存の接続の期限切れまたは無効が原因で認証に失敗した場合、その接続をその場で再認証しようとしないでください。認証情報リクエストの手順を経て、新しい接続用に新しいシェルを作成してください

インターフェースと実行のルール

オンデマンドのシェルでは、インターフェースの設定を独立したデプロイ手順として扱います。

1. シナリオのブループリントを作成または更新します
2. /api/v2/scenarios/{scenarioId}/interface を明示的に設定します
3. 初回実行の前にインターフェースの形状を検証します
4. その後でのみ /api/v2/scenarios/{scenarioId}/run を呼び出します

次の形状の実行ペイロードを使用してください。

{
  "data": {
    "path": "...",
    "method": "GET",
    "header": [],
    "qs": [],
    "body": null
  },
  "responsive": true
}

data の下にあるキー名は、シナリオのインターフェースと完全に一致させる必要があります。インターフェースが明示的に設定されていない場合、StartSubscenario モジュール自体にインターフェースのメタデータが含まれていても、run が呼び出しを拒否することがあります。

本文処理の互換性ルール

汎用シェルの契約は安定させたまま、すべてのプロバイダーモジュールが空または null の本文を同じように許容するとは限らない点に注意してください。

安全性が確認されているパターン：

• 書き込み可能なシェルでは、body を公開してマッピングできます
• 読み取り中心のシェルでは、プロバイダーモジュールが GET または DELETE で空のペイロードを適切にシリアライズできない場合、Module 2 の body マッパー自体を省略する必要があることがあります

プロバイダー固有の Make API 呼び出しモジュールで、body が存在するものの空の場合にのみ失敗するなら、次のいずれかのパターンを優先してください。

• body マッパーのない読み取りシェル
• body マッパーのある書き込みシェル
• 読み取りパスと書き込みパスでプロバイダーの挙動が異なる場合は、個別のシェルを 2 つ作成する

このために ReturnData を変更しないでください。これは Module 2 のリクエスト形状の互換性に関する問題であり、シェル出力の契約に関する問題ではありません。

応答の動作

このスキルを使用する場合：

• 最初に、検出したアプリ、バージョン、API 呼び出しモジュールの正確な名前、接続タイプの 2 つのレイヤーを要約します
• プロバイダーの特定方法（ユーザーの説明、既存の Make アーティファクト、Make アプリカタログの検索）を明記します
• シェルを再利用するのか、新たに作成するのかを明記します
• 接続を再利用するのか、新たにリクエストするのかを明記します
• 現在のフェーズ（設定または取得）を明記します
• 取得を開始する際は、API 呼び出しの計画（一覧表示／検索のパス、後続の詳細取得パス、正規化計画）を明記します
• 新しい接続を作成した場合、その接続用の新しいシェルを作成したことを明記します
• リクエストがメール、CRM、チケットなどの業務上の依頼から始まった場合、業務上の対象と、選択した正確な API パスのパターンを明記します
• 仮定には明示的にラベルを付けます
• 書き込み操作のプロンプトは簡潔かつ具体的にします
• Module 2 が PUT、PATCH、または DELETE を実行しようとしている場合は、実行を止めて警告します
• 有効化に失敗した場合、または ReturnData が不適切に見える場合は、フローが完了したと扱わず、失敗した正確なフェーズを報告します
• 公開共有する場合は、例をプレースホルダーと中立的なラベルに書き換えてから仕上げます

関連スキル

• make-scenario-building：このシェルパターンを超える、より広範なシナリオアーキテクチャについて
• make-module-configuring：モジュール設定、マッピング、Webhook、キー、データストアの詳細について
• make-mcp-reference：Make MCP の接続方法、スコープ、タイムアウトの動作について