AIROでカスタムコネクターを構築 ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

AIROを使用すると、Workato内またはClaude Code、Claude Desktop、CursorなどのMCPクライアントを通じてカスタムコネクターを構築できます。必要なAPIとコネクターの動作を説明すると、AIROがコネクション、アクション、トリガー、スキーマ用のConnector SDKコードを作成して検証し、レビューと確定に回します。

基盤となるSDKの概念と構文については、Connector SDKドキュメントを参照してください。

機能の提供状況

  • AIRO MCPを使用したカスタムコネクターの構築は、AIROが有効になっているすべてのワークスペースで、前提条件を満たす場合に利用できます。

  • Workato内でAIROを使用してカスタムコネクターを構築できるのは、一部の顧客に限られます。お使いのワークスペースでこの機能を有効にするには、Customer Success Representativeに連絡してください。

前提条件 ​

カスタムコネクターを構築する前に、次の項目を満たしていることを確認してください。

  • ワークスペースでAIROが有効になっていること。
  • カスタムコネクターを作成、編集、公開するためのConnector SDK権限。 MCPクライアントのコネクションはOAuth 2.0に対してWorkatoアカウントの権限を使用し、APIトークンで認証するコネクションは、ワークスペース所有者のユーザーとして、その権限でアクションを実行します。リリース済みコネクターを選択してレシピを構築するには、Connector SDKのUse in recipes権限も必要です。 Connector SDK権限を参照してください。
  • 認証、エンドポイント、リクエストとレスポンスの例、ページネーション、エラー動作を含むターゲットAPIドキュメント。 MCPクライアントは、あなたが提供しなかったドキュメントをインターネット検索で探します。検索結果は古くなっていたり別バージョンを対象としていたりする可能性があるため、必ずAPIの公式ドキュメントと照合してください。
  • APIがレコードを作成、更新、または削除できる場合の非本番アカウントまたは安全なテストデータ。

パスワード、トークン、クライアントシークレット、その他の資格情報をプロンプトに貼り付けたり、コネクターソースにハードコードしたりしないでください。機密値をコネクションフィールドとして定義し、実際の値をWorkatoコネクションに保存します。

作業を開始する前に、AIRO MCPコネクションが意図したワークスペースとEnvironmentを指していることを確認し、MCPクライアントがAIRO MCPツールをプロンプトなしで承認する設定になっているかどうかを確認してください。

例:気象アラートコネクターの構築 ​

この例では、無料のNational Weather Service API用のコネクターを作成します。このAPIではAPIキーは必要ありませんが、アプリケーションを識別し、連絡先情報を提供するUser-Agentヘッダーが必要です。

完成したコネクターには、次の要素が含まれます。

  • 連絡先メール用のコネクション項目。
  • 州または地域のアクティブなアラートを取得するアクション。
  • 新しく発行されたアクティブなアラート用のポーリングトリガー。
  • リリース前に確認できる保存済みバージョン。

AIROは、同じリクエストに対して異なる有効な実装を生成できます。そのため、コネクターが同等の動作を提供する場合でも、生成されたコード、項目名、説明はこのガイドの例と異なることがあります。

コネクターと最初のアクションの作成 ​

AIROを開き、コネクターと、最初に構築する動作について説明します。表示タイトルとAPIドキュメントを含めます。

  • Workato内: プラットフォーム上のどこからでもAIROを呼び出します。 AIROはConnector SDKエディターを開き、作業を続行できるようにします。 AIROはまだWeb上でAPIドキュメントを検索できないため、ドキュメントは自分で提供してください。 APIドキュメントをPDF、MD、またはTXTファイルとしてアップロードするか、10,000行未満であればチャットに貼り付けてください。サポートされるファイルタイプとサイズを参照してください。
  • MCPクライアント内: AIRO MCPサーバーをクライアントに接続し、プロンプトにAPIドキュメントへのリンクを含めます。例: <https://www.weather.gov/documentation/services-web-api>。

Connector SDKエディターには、コネクターコードの横にAIROチャットパネルが表示されるため、構築しながら各変更内容を元のコードと見比べることができます。

text
National Weather Service API向けに、National Weather Service Alertsという名前のカスタムコネクターを作成します。National Weather Service APIのドキュメントを使用してください。コネクターのSDKの`title`を`National Weather Service Alerts`に設定してください。州または準州の有効な気象警報を取得するアクションを追加してください。

AIROは、指定したワークスペース内にただちにコネクターを作成します。 AIROはAPIドキュメントを使用してコネクションとアクションを生成し、その結果を検証します。

コネクターの命名

ワークスペースで作成されたコネクターレコードと、SDKソース内のtitleキーは別々のものです。ユーザーがレシピでコネクターを選択するときに目的の表示名が表示されるように、SDKのtitleを明示的に設定します。

コネクタータイトルはワークスペース内で一意である必要があります。タイトルがすでに使用されている場合は、別のタイトルを選択するか、(Custom)などの修飾子を追加します。

このAPI向けに生成されるコネクションとリクエストロジックには、問い合わせ先フィールド、User-Agentヘッダー、およびアクティブアラート用エンドポイントを含める必要があります。

生成されたコネクションとアクションのコードを表示
ruby
connection: {
  fields: [
    {
      name: 'contact_email',
      label: 'Contact email',
      optional: false,
      hint: 'Used in the User-Agent header required by the National Weather Service API.'
    }
  ],
  authorization: { type: 'no_auth' },
  base_uri: lambda do |_connection|
    'https://api.weather.gov/'
  end
},

test: lambda do |connection|
  get('alerts/active').
    headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
    params(area: 'CA')
end,

actions: {
  get_active_alerts: {
    title: 'Get active alerts',
    input_fields: lambda do
      [
        {
          name: 'area',
          label: 'State or territory code',
          optional: false,
          hint: 'Two-letter code, for example CA or NY.'
        }
      ]
    end,
    execute: lambda do |connection, input|
      response = get('alerts/active').
        headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
        params(area: input['area']).
        after_error_response(/.*/) do |_code, body, _header, message|
          error("#{message}: #{body}")
        end

      { alerts: response['features'].map { |feature| feature['properties'] } }
    end,

    output_fields: lambda do
      [
        {
          name: 'alerts',
          type: 'array',
          of: 'object',
          properties: [
            { name: 'id' },
            { name: 'event' },
            { name: 'headline' },
            { name: 'severity' },
            { name: 'sent', type: 'date_time' },
            { name: 'expires', type: 'date_time' }
          ]
        }
      ]
    end
  }
}

気象アラートは、汎用的な作成、取得、更新、削除のパターンには適合しません。たとえばget_active_alertsのようなオブジェクト固有のアクションにすると、コネクターを理解して使用しやすくなります。

生成されたコードをレビューし、その変更をバージョンとして保存します。

  • Workato内: AIROは、各変更をエディター内の差分として表示し、変更された各ブロックにAcceptとRejectを表示します。それぞれの変更を個別に承認または却下するか、Accept allまたはReject allをクリックしてすべてまとめて処理します。チャット内のApply updatesをクリックして反映することもできます。その後、Saveをクリックしてバージョンを作成します。
  • MCPクライアント内: AIROにコネクターを保存するよう依頼します。 AIROはコネクター全体を検証し、そのコネクターの保存履歴に基づいて保存されたバージョン番号を返します。

Connector SDKエディターで差分が4つ表示されており、それぞれにAcceptボタンとRejectボタンがあり、下部にAccept allとReject allのコントロールがある変更された各ブロックを個別に承認または却下するか、全体を一度に処理します

text
Save this connector.

ポーリングトリガーを追加する ​

次に、ポーリングトリガーでコネクターを拡張します。 AIROは、現在構築中のコネクターを継続して操作するため、プロンプトでコネクター名を繰り返す必要はありません。

text
Add a trigger for new active alerts in a state or territory.

AIROは既存のコネクターにトリガーを追加し、更新されたSDKコードを検証します。

生成されたトリガーコードを表示
ruby
triggers: {
  new_active_alert: {
    title: 'New active alert',
    input_fields: lambda do
      [
        {
          name: 'area',
          label: 'State or territory code',
          optional: false,
          hint: 'Two-letter code, for example CA or NY.'
        },
        {
          name: 'since',
          label: 'When first started, this recipe should pick up alerts from',
          type: 'timestamp',
          optional: true,
          sticky: true
        }
      ]
    end,
    poll: lambda do |connection, input, closure|
      closure = {} unless closure.present?

      sent_since = (closure['cursor'] || input['since'] || Time.now).to_time.utc.iso8601

      response = get('alerts/active').
        headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
        params(area: input['area']).
        after_error_response(/.*/) do |_code, body, _header, message|
          error("#{message}: #{body}")
        end

      alerts = response['features'].
        map { |feature| feature['properties'] }.
        select { |alert| alert['sent'].to_time.utc.iso8601 > sent_since }

      closure['cursor'] = alerts.
        map { |alert| alert['sent'].to_time.utc.iso8601 }.
        max || sent_since

      {
        events: alerts,
        next_poll: closure,
        can_poll_more: false
      }
    end,
    dedup: lambda do |record|
      "#{record['id']}@#{record['sent']}"
    end,
    output_fields: lambda do
      [
        { name: 'id' },
        { name: 'event' },
        { name: 'headline' },
        { name: 'severity' },
        { name: 'sent', type: 'date_time' },
        { name: 'expires', type: 'date_time' }
      ]
    end
  }
}

生成されたトリガー全体をレビューし、特にカーソル処理、タイムスタンプの比較、ページネーション、および重複排除ロジックを確認してください。その後、同じ手順で変更を適用して保存します。

リリース前にレビューおよびテストする ​

AIROは、保存前に生成されたコードをConnector SDKフレームワークと照らし合わせてチェックし、Rubyの構文エラーも検査します。リリース前に、実装全体をレビューし、Workatoでテストしてください。検証に成功しても、API固有のレビューやランタイムテストの代わりにはなりません。

リリース前に、次の確認を完了します。

  1. 実装全体をレビューします。 まずAIROが返すサマリーで概要を把握し、その後Tools > Connector SDKからコネクターを開いて、コード全体を確認します。理解できないブロックがあれば、AIROに説明を依頼します。
  2. 実装をAPIドキュメントと比較します。 ベースURL、パス、認証、ヘッダー、フィールド名、リクエストパラメーター、レスポンス構造、ページネーション、レート制限、エラーレスポンスを確認します。
  3. Workatoでテストコネクションを作成します。 この例では、連絡先メールを指定し、コネクションテストが成功することを確認します。
  4. ユーザーから見た入力フィールドを確認します。 Test codeタブでは、レシピ内に表示されるのと同じ形でアクションの入力フィールドがレンダリングされます。ラベル、必須項目、選択リストが意図どおりに動作していることを、リリース前に確認します。
  5. 安全な入力でアクションを実行します。 SDKのTest codeタブを使用してアクションを実行します。たとえば、CAのアクティブなアラートをリクエストし、返されたフィールドが宣言済みの出力スキーマと一致することを確認します。 コンソールタブにはコネクターコード内のputs文からの出力が表示され、ネットワークアクティビティにはアクションが送信したリクエストが表示されます。アクションとトリガーをテストするを参照してください。
  6. トリガーをテストします。 初期since動作、カーソル更新、順序、ページネーション、重複排除を確認します。ランタイムテストにより、コードレビューだけでは明らかにならないスキップされたイベントや繰り返し発生するイベントを検出できます。
  7. ターゲットEnvironmentを確認します。 既存のレシピが使用する可能性のある変更をリリースする前に、DevelopmentまたはテストEnvironmentでテストします。

リリース前に、重点的なレビューをAIROに依頼することもできます。

text
Review the current connector for release readiness without changing it. Compare the connection, action, and trigger with the National Weather Service API documentation. Check the authentication, request paths and parameters, input and output schemas, response mapping, pagination, cursor behavior, deduplication, and error handling. Explain any risks you find and recommend changes.

コネクターをリリースする ​

Connector SDKエディターから、またはMCPクライアントからコネクターをリリースします。

  • Workato内: Release latest versionをクリックします。最新バージョンをリリースするを参照してください。
  • MCPクライアント内: AIROにコネクターをリリースするよう依頼します。
text
Save and release these changes.

リリースはすべてのレシピに即時反映

リリースすると保存済みバージョンがただちにアクティブバージョンになり、そのコネクターを使用するすべてのレシピで使用が開始されます。

MCPクライアントからコネクターをリリースする前に、AIROは未リリースの変更内容をレビューします。 AIROは、適用される内容のサマリーとともにこの警告を表示し、確認を求めます。このコネクターにはまだリリース済みバージョンがないため、AIROは変更サマリーではなく、初回リリースであることを報告します。以前に承認した内容にかかわらず、各リリースには個別の明示的な確認が必要です。独自のリリースノートを指定することも、AIROに差分から提案させることもできます。

AIROは、次のいずれかの結果を報告します。

  • リリース済み。 コネクターは新しいバージョンになりました。
  • すでに最新。 保存済みバージョンはすでに有効であったため、何も変更されませんでした。
  • 保存済みだが未リリース。 保存は成功しましたが、その後のリリース手順が失敗しました。
  • 拒否。 検証結果により保存がブロックされたため、何も保持されませんでした。

拒否または未リリースの結果は、有効なバージョンが変更されなかったことを意味します。報告された問題を解決して、もう一度依頼します。

コネクターのリリース後に次のことを確認します。

  • 想定されるバージョンがアクティブであること。
  • コネクターがSDKのtitleフィールドの値で表示されること。
  • コネクターが目的のEnvironmentのレシピで利用可能であること。

後続のリリース前に変更内容を確認する ​

コネクターをリリースした後に編集する場合は、いつでもAIROに変更内容を確認できます。

text
What changed in this connector since the last release?

AIROは、破壊的変更、追加項目、変更項目にグループ化されたサマリーを返すため、コネクター全体ではなく更新内容に絞ってレビューできます。

以前のコネクター状態を復元 ​

Connector SDKエディターでAIROが行う各変更ごとに、チャットにConnector stateマーカーとView update detailsボタンが追加されます。 View update detailsボタン: その特定の更新でAIROが変更した内容のみを表示します。 Connector stateをクリックするとView previous connector state画面が開き、その記録された状態と現在のコードとの差分が表示されます。

AIROチャットパネル内のConnector state記録マーカーと、その横のRestoreボタンConnector stateをクリックして、その状態と現在のコードを比較するか、Restoreをクリックして直接その状態に戻します

Restoreをクリックすると、チャット内のConnector stateマーカーの横、またはView previous connector state画面から、その状態にコネクターを戻すことができます。 AIROが確認を求め、承諾すると、その状態以降に行われたすべての変更を破棄します。

以前のコネクター状態画面で、以前と現在のコネクターコードを比較しており、元の状態に戻すかどうかを確認するダイアログが表示されている記録された状態と現在のコードを比較し、Restoreをクリックして確認します

コネクターステートとコネクターバージョン

コネクター状態は、コネクターバージョンと同じではありません。 新しいコネクターバージョンが作成されるのは、Saveをクリックしたときだけです。

効果的なプロンプトを作成する ​

優れたプロンプトには、目標、信頼できる情報源、関連するコネクターコンテキスト、重要な制約、検証する具体的な結果が含まれます。

有用なパターンは次のとおりです。

目標 + ターゲットコネクターまたはAPI + 従うべきドキュメントまたは既存コード + 要件と制約 + 受け入れチェック

大きなコネクターを、レビュー可能な変更に分割します。最初にコネクションと1つのアクションを構築してテストし、保存してから、トリガーまたはより複雑なアクションを追加します。これにより、検証結果と動作上の問題を分離しやすくなります。

新しいコネクターを構築する ​

ターゲットAPI、コネクタータイトル、認証、最初の操作を指定します。"気象データ用のコネクターを構築して"のような曖昧なプロンプトでは、4つすべてが省略されています。

text
Build a custom connector named National Weather Service Alerts for the National Weather Service API. Use <https://www.weather.gov/documentation/services-web-api> as the source of truth. Set the SDK `title` to `National Weather Service Alerts`. The API doesn't use an API key but requires a User-Agent with contact information. Add an action that retrieves active alerts for a two-letter state or territory code.

APIで認証が必要な場合は、認証タイプ、必要なスコープ、トークン更新動作、コネクションをテストするための安全なエンドポイントも含めます。

既存のコネクターを編集する ​

コネクターID、変更するコンポーネント、従うべき既存パターン、期待される結果を指定します。 Tools > Connector SDKからコネクターを開き、Source codeタブのAIROチャットパネルを使用します。 AIROは、提案された変更をエディター内の差分として表示します。差分を確認し、変更された各ブロックを承認または却下してから、Saveをクリックしてバージョンを作成します。

text
connector 4821で既存のget-ticketアクションを確認し、同じオブジェクトスキーマとエラーハンドリングパターンに従うupdate-ticketアクションを追加してください。関係のないアクションは変更しないでください。編集内容を検証し、変更されたブロックを正確にサマリーしてください。

対象とするコネクターを指定する際は、数値のコネクターIDを使用してください。コネクターのレコード名とSDKのtitleは異なる場合があるため、名前だけではAIROが正しいコネクターを特定できないことがあります。別のコネクターに切り替える前に、作業内容を保存してください。

失敗した保存を修正する ​

コネクターID、エラーテキスト全文、影響を受けるコンポーネント、直近の変更を含めます。

text
connector 4821で、ポーリングトリガーが最後の編集後に次のバリデーションエラーを返します:[paste the error]。トリガー全体を確認し、原因を説明し、最小限で安全な修正を行い、コネクターを検証してください。

制限事項 ​

  • AIROはカスタムコネクターを削除できません。使用していないコネクターは、手動で削除してください。まず、そのコネクターを使用しているアクティブなレシピをすべて停止する必要があります。カスタムコネクターを削除するを参照してください。
  • 保存時には、最新の編集だけでなくコネクター全体が検証されます。ソース内の他の場所にある検出結果により、それらを解決するまで保存がブロックされる場合があります。

トラブルシューティング ​

AIROが誤った場所でコネクターを作成または開いた ​

作業中のワークスペースとEnvironment、またはAIRO MCPコネクションに関連付けられているワークスペースとEnvironmentを確認してください。他のものを作成または保存する前に、目的のターゲットに再接続します。

操作が拒否される ​

AIROが操作するWorkatoアカウントに、必要なConnector SDKの権限が付与されていることを確認してください。 AIROは、そのアカウントに付与された権限を超えて操作することはできません。

自分が導入していない検出結果により保存が失敗する ​

保存時にはソース全体が検証されます。現在のすべての検出結果を一覧表示し、変更したブロックの外にあるものを特定するようAIROに依頼します。保存する前に検出結果を解決します。コードを一時的にコメントアウトする場合は、コネクターを保存またはリリースする前に機能への影響をレビューしてください。

サイズが原因で保存が拒否される ​

繰り返し使われているスキーマまたはロジックを特定し、ソースを削減するようAIROに依頼します。繰り返し使われているフィールドスキーマをobject_definitionsに移動することが、通常は最も大きな削減になります。

AIROが名前でコネクターを見つけられない ​

数値のコネクターIDを使用します。別のコネクターがリクエストしたタイトルをすでに使用している場合は、一意のタイトルを選択します。

パスが正しく見えるのにコネクションテストが失敗する ​

base_uriとリクエストパスの結合方法を確認します。 /で始まるリクエストパスは、base_uri内のパスセグメントを置き換えます。たとえば、https://host/api/v2/を/usersと組み合わせると、/api/v2/配下ではなくホストルートから解決されます。ベースパスを維持するには、base_uriの末尾に/を使用し、相対リクエストパスの先頭の/を省略します。 base_uriの設定を参照してください。

リリースでバージョンがすでに最新であると報告される ​

最新の保存済みバージョンがすでに有効なバージョンだったため、リリースでは何も変更されませんでした。これは、AIROから、またはWorkato内から、同じ保存済みバージョンを新しい編集を保存せずにもう一度リリースした場合に発生する想定どおりの動作です。

コネクターは保存されたが、レシピではまだ古い動作が使用されている ​

保存済みバージョンは、リリースされるまでアクティブになりません。 AIROに前回のリリース以降の変更内容を確認するか、Workatoでコネクターを開いて、最新の保存済みバージョンと有効なリリース済みバージョンを比較します。

最終更新日: