Workiva サポートセンター

動的な統合、特に自動化ワークフロー (チェーンなど) で HTTP コネクタを使用する場合は、API 呼び出しからのレスポンスを効果的に処理することが重要です。出力パラメータを使用すると、ユーザーは、レスポンスボディ、レスポンスヘッダー、ステータスコードなど、APIから返されるデータの重要な部分をキャプチャできるようになり、このデータを下流のステップで使用できるようになります。

どのような問題を解決しますか？

出力パラメータは、応答性の高いインテリジェントなワークフローの作成に不可欠です。

• ダイナミックワークフロー： 出力パラメータにより、APIが返す値に基づいて次へ何が起こるかを調整できます。例えば、トークンの抽出、レコードが存在するかどうかの確認、操作が正常かどうかの確認などです。
• 自動化： 値を自動的に取り込むことで、ユーザーはマニュアル入力やハードコーディングの手間を省くことができ、ワークフローは少ないメンテナンスで拡大縮小できます。
• 統合の合理化： コネクターが受信データに基づいて適応するため、認証サーバー、CRM、カスタムAPIなどのシステム接続がよりシームレスになります。

誰に影響しますか？

• 開発者とインテグレーター： システム間の自動化チェーンや統合を構築する人たち。
• データアナリスト： リアルタイムで正確なデータフローをダッシュボードやレポートに活用しています。
• システム管理者： 統合の保守やトラブルシューティングを行う方 - 出力パラメータに使用することで、問題を迅速に特定することができます。

出力パラメータとは何ですか？

HTTP コネクタの出力パラメータは、レスポンスヘッダー、レスポンスボディ、レスポンスコードなど、HTTP 要求の期待される出力を定義するために使用されます。これらは HTTP 要求の期待される結果を定義し、チェーン内の後続のノードまたはロジックステップで再利用できます。

出力パラメータの例：

• レスポンスヘッダ： コンテンツタイプ、サーバー、レートリミットステータスなどのメタデータ。
• レスポンス本文： API から返却される実際のコンテンツ（通常は JSON または XML 書式設定）。
• レスポンスコード： 成功(200)、クライアントエラー(400)、サーバーエラー(500)など。

例アクセストークンを取得する例

APIがこのようなトークンを返却したとします：

{ "token_type"："Bearer", "expires_in"：600, "access_token"："<access_token_string>", "スコープ"："graph:write graph_api|r 権限|w ..."}

access_token を出力パラメータとして定義し、次のステップへ渡します (別の API 呼び出しの認証など)。

なぜレスポンス本文が必要なのですか？

レスポンス本文は通常、APIが最も重要な情報を返す場所です。これらに含まれるもの：

• 新規作成されたレコードのID
• 認証トークン
• クエリ結果またはデータペイロード

レスポンス本文に使用しないと、メタデータに制限されるため、ワークフローの動的性が制限されます。 

access_token をレスポンスのドロップダウンから取得できるようになりました。

一般的なエラー処理のシナリオ

出力パラメータを使用する際に遭遇する可能性のある典型的な問題：

• エラー: 未定義の出力パラメータです。

  原因および修正： レスポンス本文の構造が変更されたか、入れ子になっています。フィールドへの正しいJSONパスを確認してください。

• エラー： 401 認証されていません

  原因および修正: トークンが見つからないか、有効期限が切れています。トークンが取得され、正しく渡されたことを確認してください。

• エラー：500 Internal Server Error 500 内部サーバーエラー

  原因 & 修正: サーバーの問題か、無効なリクエストペイロードです。レスポンス本文を確認してください。

• エラー： 無効な JSON

  原因および修正: API が不正な形式の応答を返却しています。Try-Catch ブロックを使用するか、解析前に出力を検証してください。

Bearer Token とは何ですか？

Bearer Token は OAuth 2.0 認証で使用するアクセストークンのタイプ別です。ユーザーやアプリケーションが API に使用することを許可します。HTTPリクエストのヘッダーでトークンを "負担 "するため、"Bearer "と呼ばれます。

ヘッダーの例：

作成者がベアラ<access_token>

このトークンはベーシック認証よりも安全です：

• トークンの有効期限が切れるため、トークン漏洩のリスクが軽減されます。
• スコープと権限を持つことができます。
• 認証と認可を分離します。

なぜベーシック認証を使わないのですか？

Basic Auth はリクエスト毎にユーザー名とパスワードをエンコードして送りますが、以下のような問題があります：

• 安全性が低い - クレデンシャルが再利用されたり、傍受されたりする可能性があります。
• 簡単に期限切れや使用するスコープを設定できません。
• トークン・ベースの権限コントロールに欠けています。

ベアラートークンは、トークンの有効期限、更新、きめ細かな権限をサポートしているため、最新のAPIやエンタープライズグレードのセキュリティに適しています。