エラー処理 ​

詳細で役立つエラーメッセージを表示することで、ユーザーおよびカスタムコネクターのエンドユーザーのレシピ作成エクスペリエンスを向上できます。 ただし、デフォルトではカスタムコネクターのアクションとトリガーはレスポンスメッセージを表示しません。 さらに、他のケース（アクション/トリガーの入力データが特定のビジネス要件を満たさない場合など）でエラーメッセージを表示したいことがあります。 これは、次のヘルパーメソッドを使用して実現できます。

入力の検証 ​

ビジネスロジックに違反する入力に対してカスタムエラーを発生させることができます。 例として、検索アクションを使用してContactを検索する検索アクションを考えます。 ユーザーが少なくとも1つの検索条件を指定してレコードを検索するようにする必要があります。 この場合、クエリパラメーターなしでリクエストを送信する代わりに、入力値がない場合はエラーを発生させる必要があります。

error ​

これは、カスタムメッセージ付きでジョブエラーを発生させるWorkato SDK固有のメソッドです。 errorメソッドは、カスタムコネクターを使用してエラーをトリガーしたときにWorkatoプラットフォームでエンドユーザーに表示される引数を受け付けます。 これは、カスタムコネクターの使いやすさを向上させるためにさまざまな方法で使用できます。

サンプルコードスニペット ​

execute: lambda do |connection, input|
  error("Provide at least one search criteria") if input.blank?
  get("", input)
end

入力検証エラーメッセージ

レスポンスエラーの処理 ​

一部のAPIでは、リクエストのエラーを示すためにレスポンスコードを使用しません。 これらのAPIは、HTTPコード200とレスポンス本文内のエラーメッセージで応答する場合があります。

デフォルトでは、SDKフレームワークはHTTPレスポンスコードがエラーを示す場合にのみエラーを発生させます。 Sage Intacctは、レスポンスメッセージ内にエラーをネストした200のレスポンスを返すため、すべてのレスポンスを検証し、レスポンス本文にエラーが存在する場合はエラーを発生させることが重要です。

detect_on ​

これらのエラーをキャッチする方法は2つあります。 1つ目の方法は、detect_onを使用することです。 これは、エラーをキャッチするためのコネクター全体のメソッドです。すべてのアクションとトリガーに適用されます。 このメソッドは、カスタマイズできない標準メッセージ形式でエラーを発生させます。

after_response ​

もう1つの方法は、after_responseメソッドでこれらのエラーを処理することです。 このメソッドはerror()と併用して、HTTPレスポンスの内容を検証し、カスタムエラーを発生させることができます。 このメソッドは個々のアクション/トリガーに適用されます。 そのため、エラーの検出に使用する条件をリクエストごとにカスタマイズできます。 さらに、エラーメッセージを各アクション/トリガーに合わせて変更できます。

たとえば、after_responseメソッドを使用して、本文を成功したリクエスト出力として返すか、カスタムメッセージ付きでエラーを発生させるかを決定する前に、レスポンス本文の内容を確認できます。

サンプルコードスニペット ​

post("https://api.intacct.com/ia/xml/xmlgw.phtml", payload).
  format_xml("request").
  after_response do |code, body, headers|
    result = body.dig("response", 0, "operation", 0, "result", 0)
    if result.dig("status", 0, "content!") == "failure"
      error(result.dig("errormessage", 0))
    else
      result["data"]
    end
  end

after_error_response ​

after_error_responseは、HTTPレスポンスを処理するためにHTTP動詞メソッドにチェーンできるヘルパーメソッドです。特に、APIがエラーレスポンスコードで応答する場合に使用します。

このメソッドは2つの引数を受け付けます。 1つ目は、処理する正確なエラーコードを表す数値です。

次に、最初の引数と一致するHTTPレスポンスコードを受信したときに実行される条件付きパスも受け付けます。

サンプルコードスニペット ​

Airtable APIを使用したafter_error_responseの例を見てみましょう。

execute: lambda do |connection, input|
  patch("https://api.airtable.com/v0/#{connection['base_id']}/users/#{id}", payload).
    after_error_response(404) do |code, body, header, message|
      error("#{message}: #{body}")
    end
end

無効なIDで行を更新しようとすると、HTTPエラーが返されます。 使用されるエラーコードは404で、JSON本文は{"error":"NOT_FOUND"}です。

レシピジョブ詳細ページのフォーマット済みエラーメッセージ

HTTPリダイレクトの処理 ​

一部のAPIはHTTP302リダイレクトを返しますが、SDKはデフォルトではそれに従いません。 これにより、リクエスト自体が有効な場合でも、400 Bad Requestなどの予期しない失敗が発生する可能性があります。

たとえば、APIが/v1/dataを/v2/dataにリダイレクトする場合がありますが、SDKは302で停止してエラーを発生させます。

解決策 ​

リダイレクトレスポンスを処理するには、次の手順を実行します:

例:

file: get("/api/packages/#{input['package_id']}/download").
  response_format_raw.
  ignore_redirection.
  after_response do |code, body, header|
    if code == 302 && header['location'].present?
      get(header['location']).
        response_format_raw.
        after_error_response(/.*/) do |_code, body, _header, message|
          error("#{message}: #{body}")
        end
    else
      body
    end
  end

リダイレクト先ドメインの認証を条件付きでスキップ ​

Amazon S3など、一部のリダイレクト先ドメインでは認証ヘッダーが拒否される場合があります。 apply:ブロック内でcurrent_urlを使用して、条件付きでヘッダーを除外します:

apply: lambda do |connection|
  unless current_url.include?('.amazonaws.com/')
    headers(Authorization: "Bearer #{connection['api_token']}")
  end
end

ピックリストエラーの処理 ​

after_error_responseヘルパーメソッドは、カスタムコネクターの他の部分でHTTP動詞メソッドにチェーンすることもできます。 たとえば、動的なpick_listsからのカスタムエラーメッセージを処理して提供したい場合があります。 この例では、Docparserからのエラー処理について説明します。

サンプルコードスニペット ​

pick_lists: {
  parsers: lambda do
    get('https://slack.com/api/users.list').
      after_error_response(400) do |code, body, headers, message|
        error("Error loading parser pick list: #{body[/(?<=error\"\:\").*(?=\"\})/]}")
      end.
      pluck("label", "id")
  end
}

カスタムアダプターがピックリストをロードしようとすると、HTTPエラーがレシピエディターに表示されます。 この例ではAPIキーがリセットされ、その結果、リクエストで無効なAPIキーが使用されました。

レシピエディターのHTTPリクエストエラーメッセージ

オブジェクト定義エラーの処理 ​

これは、object_definitions内のdynamic fieldsコードブロックでも使用できます。

サンプルコードスニペット ​

object_definitions: {
  parsed_data: {
    fields: lambda do |connection, config_fields, object_definitions|
      get("https://api.docparser.com/v1/results/#{config_fields['parser_id']}1/schema").
      after_error_response(400) do |code, body, headers, message|
        error("Error loading parser schema: body[/(?<=error\"\:\").*(?=\"\})/]")
      end
    end
  }
}

カスタムアダプターが不明なパーサーのschemaをフェッチしようとすると、HTTPエラーがレシピエディターに表示されます。

レシピエディターのschemaエラーメッセージ