ウェブサービスタスク
このページの内容
ウェブサービスタスクについて
Web サービスタスクは、API の使用経験があり、回答者がアンケートを終了したときに、クアルトリクスソフトウェア内または外部の Web サービスに対して、さまざまなワークフローをトリガーしたい場合に便利です。たとえば、アンケート調査で回答者の連絡先情報を収集する場合、Web サービスタスクで連絡先作成API コールを使用して、回答者を連絡先リストに追加することができます。
また、より詳しい情報や背景を知るために、これらのウェブサービス関連のページをご覧になることをお勧めします：
Qtip: このページにはクアルトリクスのAPIへの参照が含まれており、アクセスには特別な許可が必要な機能です。この機能へのアクセシビリティをご希望の場合は、ブランド管理者にお問い合わせください。
注意: ウェブサービスのセットアップには、高度なプログラミング知識が必要になることがよくあります。私たちのサポートチームは、ウェブサービスに情報を入れる基本的なことについては喜んでお手伝いいたしますが、プログラミングの面についてはサポートいたしかねます。
注意: Webサービスタスクは以下のコンテンツタイプにのみ対応しています：URLエンコード、XML、JSON、プレーンテキスト。
Qtip: API docからWebサービスを設定していますか？curlコマンドをインポートすれば、セットアップはもっと速くなる。
Webサービスタスクの設定
注意: Webサービスタスクで実行される呼び出しからの出力には1MBの制限があります。
Qtip: AIアシスタントを使用して、ウェブサービスタスクを設定することができます。詳しくは、タスク設定にAIアシストを使うをご覧ください。
ボディ・パラメーターをどのようにフォーマットするかによって、セットアップは若干異なります。JSONまたはXML形式を使用している場合は、Bodyセクションに本文を入力してください。URLエンコードを希望する場合は、パラメータをクエリ文字列としてURLフィールドに追加することができます。
![ワークフロー]タブで、[ワークフローを作成する]をクリックし、イベントが受信されたときに開始されます。](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2023/01/event-workflow-1-4.png)
- 認証機能：認証されたWebサービスリクエストを実行します。自分らしくいられることの認証機能には、ベーシック（パスワードとユーザー名）、APIキー、OAuthがあります。
- 非認証機能：認証機能なしでWebサービスリクエストを実行する。
Qtip:以前に追加した認証情報、またはブランド管理者が追加した認証情報は、[拡張機能]タブで選択できます。
qtip:クアルトリクスAPIを使用している場合、どのようなリクエストタイプを使用すればよいかはドキュメントに記載されています。
注意: WebServiceタスクはGETリクエスト以外のURLリダイレクトを許可しません。GET リクエストに対して許可されるリダイレクトは一つだけです。
Qtip:拡張ドメイン設定でドメインを指定することで、Webサービスタスクが接続できるドメインを制限することができます。
Qtip:テキスト差し込みアイコン{a}を使用して、ワークフロー内のアンケート回答や以前のタスクからテキストを差し込みます。
注意: クアルトリクスAPIを使用する場合は、ヘッダーにAPIトークンを含める必要があります。詳細については、クアルトリクスAPIリクエスト用のヘッダーの追加を参照してください。
Qtip:キー・バリュー・ペアとフリー・テキストの最大文字数は75,000文字です。
注意: POST、PUT、PATCHリクエストでは、各キーと値のペアのデータ型を指定する必要があります。
- ブール値：データが2つの可能な値のうちの1つを持つ場合、このデータ型を選択します。
- JSON:データがJSON形式の場合、このデータタイプを選択します。 Qtip: 入力されたデータが検証可能なJSONであることを確認してください。テキストの差し込みを使用する場合は、特殊文字が含まれないようにしてください。
- 数値：データが数値の場合、このデータタイプを選択します。
- 文字列：データがテキスト形式の場合、このデータタイプを選択します。
- システム・デフォルト：データのネイティブ・データ型を使用する場合は、このデータ型を選択します。データ型が見つからない場合は、String型がデフォルトとなる。 Qtip:あなたのデータが正しくキャストされるように、他のデータタイプを選択することをお勧めします。注意: 2022年9月16日以前に設定されたKey-Valueペアのデータ型は、System Defaultとなります。
Qtip:データタイプフィールドは、ステップ13-14でJSONとKey-valueペアを選択した場合のみ使用できます。
- データ型をキャストせず、エラーとしてフラグを立てる：データ型をキャストできない場合、データ型はキャストされず、タスクは失敗する。これは実行履歴タブで見ることができる。
- データ型をシステム・デフォルトにキャスト：データ型をキャストできない場合、データ型はシステム・デフォルトに設定されます。
注意: このフィールドを空のままにしたり、値のないキーを持たせてはいけません。その代わりに、フィールドをまったく含めないか、空の値を示す “null “を入力する。この分野は除外することをお勧めする。
Qtip:Webサービスタスクが無効なJSONボディに遭遇しても、タスクは失敗しません。代わりに、無効なJSONは文字列に変換され、新しいJSONオブジェクトの「text」プロパティとして保存される。そうすれば、タスクの処理が終わると、無効なテキストを見ることができる。
注意: 現在、Webサービスタスクはコメントをサポートしていません。
Qtip:Run testをクリックすると、リクエストの結果が表示され、成功したかどうか、成功した場合は結果のJSONまたはXMLが表示されます。
Qtip:カスタムパスを追加するにはカスタムパスを追加をクリックし、削除するにはパスの次へごみ箱をクリックします。
注意：失敗したタスクのデータを別のタスクにパイプすることはできません。テキストの差し込みはNULL値として表示されます。
Qtip:ウェブサービスのタスクには16秒のタイムアウトがあります。ウェブサービスの呼び出しに10秒以上かかる場合、ワークフローは失敗します。
タスク設定にAIアシスタントを使う
注意: 自動マッピングを使用できるのは、ブランド管理者が、[管理者]タブで組織の [AI 支援によるワークフローの設定] 権限を有効にしている場合のみです。
AIアシスタントは、一般に公開されているAPIドキュメントを読み取り、タスクを自動的に設定することで、WebサービスタスクのAPI統合を構成することができます。
Qtip: AIアシスタントが下書きを作成できない場合は、リクエストを編集してもう一度やり直してください。
Qtip: 弊社はガードレールを設置し、継続的に製品を改良していますが、人工知能は時として不正確、不完全、または時代遅れの出力を生成することがあります。クアルトリクスのAI機能からの出力を使用する前に、出力が正確であることを確認し、ユースケースに適していることを確認する必要があります。クアルトリクスのAI機能からの出力は、人間によるレビューや専門的なガイダンスに代わるものではありません。
認証クレデンシャルの追加
このセクションでは、Webサービスタスクに認証情報を追加する方法を説明します。Basic、API Key 、またはOAuth 2.0メソッドを使用してクレデンシャルを追加できます。クレデンシャルを追加するには、クレデンシャル選択ウィンドウからユーザーアカウントの追加をクリックする。
qtip:すべての接続タイプはmtLSと互換性があります。詳細を見るには、相互TLSのセクションをご覧ください。
ベーシック
ベーシック認証では、アカウントのユーザー名とパスワードでログインする必要があります。
APIキー
APIキー認証では、静的なAPIトークンを使って認証することができます。
OAuth 2.0
OAuth2.0認証は、サードパーティのプラットフォームと統合するために、静的なAPIトークンや基本的なユーザー名とパスワードを使用する必要性を取り除きます。ウェブサービスタスクは2つの異なるOAuth2.0認可タイプ、認可コードとクライアント認証情報をサポートします。
OAuth 2.0認証を使って、多くのサードパーティプラットフォームとシームレスに統合できます。クアルトリクスのウェブサービスの実装は、公式のOAuth仕様に従っています。しかし、外部システムによっては、WebサービスタスクのOAuth2.0認証との非互換性につながる、わずかに異なる設定を持つ場合があります。
以下の統合は、OAuth2.0で動作することが完全に確認されている例です：
- Salesforceの認証コードメソッドを使用します。
- 認証コードメソッドを使用して Jira。
- 認証コード方式でズーム。
QTip: OAuth接続を作成する場合、リダイレクトURLはhttps://{dataCenter}.qualtrics.com/oauth-client-service/redirectとなります。{dataCenter}はアカウントに関連付けられた値を表します。アカウントのデータセンターの検索については、こちらのページをご覧ください。
OAuth 2.0を使って認証すること：
Qtip: Google OAuth認証情報を設定するユーザーには、Token Endpointの最後に次のパラメータを含めてください：”?prompt=consent”。既存のクエリーパラメーターがある場合は、クエスチョンマークは必要ありません。
QTip:Snowflakeとの接続に問題がある場合は、クアルトリクスIPレンジがallowlistedになっていることを確認してください。
名前の変更と認証情報の削除
クレデンシャルの名前を編集するには、アカウントの次へ の 3 つの点をクリックします。資格情報を削除するには、アカウントの削除をクリックします。
Qtip:自分で追加したクレデンシャルのみ、名前の変更や削除が可能です。
警告: クレデンシャルを削除するときは注意してください！資格情報を使用するワークフローは、資格情報が削除されると動作しなくなります。
クアルトリクスAPIリクエスト用ヘッダの追加
クアルトリクスAPIを使用する場合、APIトークンをWebサービスのヘッダーとして含める必要があります。
相互TLS
相互トランスポートレイヤーセキュリティ（mTLS）は、標準的なAPI認証機能（APIトークンやOAuthなど）の上に追加する、オプションのセキュリティレイヤーです。相互TLSは、API/ウェブサービスに接続する人とAPI/ウェブサービス自体の両方向のトラフィックが安全で暗号化されていることを保証する。mTLSを有効にすると、リクエストに成功するためには、すべてのリクエストで正しいクライアント証明書を提示する必要がある。呼び出し元が無効な、あるいは見つからないクライアント証明書を使用してリクエストを行った場合、呼び出そうとしたAPIはリクエストをブロックする。
要件
mTLSをサポートしているかどうか、どのような形式で鍵情報を提供するかは、サービスごとに異なる。私たちは、私たちの要件に合致するサービスに対してのみ、MTLSをサポートすることを保証します：
- プライベート鍵を提供
- 秘密鍵はPKCS8にフォーマットすることができる。
- 証明書の提供
- 証明書はX.509にフォーマットすることができる。
mTLSは、ワークフローで作成された認証機能付きウェブサービスでのみ
サポートされます。3つの認証機能（Basic、APIキー、OAuth2.0）に対応しています。
mTLSの追加
![次へ]ウィンドウには、認証機能と非認証Webサービスの2つのオプションが表示されます。](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2022/06/mtls-2.png)
Qtip:キーのフォーマットが異なる場合は、別のプログラムを使って変更することができます。
Qtip:ウェブサービスでクアルトリクスAPIを使用する場合は、mTLSに関するAPIドキュメントをご覧ください。このドキュメントでは、秘密鍵を引き出す方法を紹介する。クアルトリクスに値を貼り付ける際には、”begin private key “と “end private key “というダッシュを入れる必要があります。
Qtip:ウェブサービスでクアルトリクスAPIを使用する場合は、mTLSに関するAPIドキュメントをご覧ください。この文書では、証明書を引き出す方法を説明する。クアルトリクスに値を貼り付ける際、”begin certificate “と “end certificate “というダッシュを入れる必要があります。
Qtip:mTLSキーの検証は、ウェブサービスを通じてAPIコールを実行するまで行えませんので、キーの入力が間違っていても、このページにエラーメッセージは表示されません。ワークフローをライブにする前に、ウェブサービスをテストしてみてください。
Curlコマンドの使用
Curlコマンドは、HTTPリクエストを行うことができる多くの方法の1つであり、URLを通じて情報をやり取りするための貴重なツールです。タスクをセットアップしている間にcurlコマンドをインポートして、異なるウェブサービスの設定を自動入力することができます。
多くのAPIのDOCには、使用可能なcurlの例が記載されていることが多い。これらのコマンドをコピーしてインポートすることで、ウェブサービスのセットアップをより迅速かつ簡単に行うことができる。
curlリクエストの例については、それぞれのAPIドキュメントの右側を見てください：
GETリクエストの場合、curlコマンドはcurl https://api.example.com/parameters. これほど単純でないcurlコマンドについては、一般的なパラメータをいくつか用意しておこう。
Qtip:既存のWebサービスタスクを編集している場合、インポートしたcurlコマンドは以前の設定を上書きします。
QTip:下記で説明する以外のcurlについて詳細を見たい場合は、IBMのドキュメントなどクアルトリクスサポート以外のリソースを読むことをお勧めします。
サポートされているCurlコマンドパラメータ
クアルトリクスのウェブサービスタスクがサポートしているcurlパラメータの一部を紹介します：
| パラメータ | 説明 | カールコマンド | 例 |
|---|---|---|---|
| URL | ウェブサービスが相互作用すべきエンドポイントまたはリソース。 | 完全なURL。 | https://datacenter.qualtrics.com/API/v3/directories/ |
| HTTPメソッド | GET、POST、PUTなどのオプションがある。 | --X <command>または--request <command> | 例 1： --X GET 例 2： --request PUT |
| ヘッダー | カスタムヘッダー | --Hまたは--header | 例 1： --header 'Accept: application/json' 例 2： --header 'Content-Type: application/json' |
| 本文 | POSTリクエストのボディ (またはペイロード)。 | --dまたは--data | --data '{ “description”：”Lists all open bugs”, “jql”：”type = Bug and resolution is empty”, “name”：”All Open Bugs” }’. |
| JSONフォーマット | ヘッダーとデータでJSONフォーマットを指定する必要がなくなる。 | --json | このcurlコマンドは、以下の3つのタグを置き換えます:  ； --data [arg] --header "Content-Type: application/json" --header "Accept: application/json" |
共通ヘッダー・パラメーター
上記で、ヘッダーを定義するためにcurlコマンドを使用できると述べた。ヘッダは HTTP コミュニケーションにおいて、リクエストに関する情報の提供や自分らしくいられることの認証制御など、様々な役割を果たします。使用する特定のヘッダーは、使用するアプリケーションやAPIの要件に依存する。
以下はヘッダーパラメータの例である：
| 名前 | 説明 | 例 |
|---|---|---|
| 承諾 | 回答のメディアフォーマットを指定する。 | Accept: application/json |
| コンテンツタイプ | リクエストにおいて、content typeはサーバーに送られるリソースのメディアタイプを指定する。回答では、content typeはメッセージボディに含まれるリソースのメディアタイプを示す。 | Content-Type: application/json |
| 権限 | 保護されたリソースにアクセスするためのアクセシビリティを提供する。 | Authorization: Bearer token |
| イータグ | リソースの特定のバージョンに対する一意な識別子を提供する。 | ETag: "123456" |
| コンテンツ長 | メッセージのentity-bodyのサイズを設定する。 | Content-Length: 1024 |
| 元 | リクエストの発信元を示す。これは、Cross-Origin Resource Sharing（CORS）に役立ちます。 | Origin: https://example.com |
サポートされていないパラメータ
上記にリストされていないcurlパラメータはサポートされていません。クアルトリクスWebサービスタスクがサポートしていないcurlコマンドフォーマットの例をいくつかご紹介します：
- --cookie リクエストと一緒にクッキーを送信します。
- --L または でリダイレクトしてください。--location
- --max-time 最大リクエスト時間を設定する。
- --o または 、回答をファイルに保存する。--output
- --insecure 安全でない接続を許可する。
- --A または でユーザーエージェントを指定します。--user-agent
Qtip:サポートされていないパラメータを使ってcurlコマンドをインポートしようとすると、使用したサポートされていないパラメータのリストがエラーメッセージとして表示されます。サポートされていないパラメータを削除して、curlコマンドのインポートを続行するオプションが与えられます。
Curlコマンドのインポート
注意: 特に他のプラットフォームからcurlコマンドをコピーする場合は、curlリクエストにHTTPメソッドを含めるようにしてください。
Qtip:あなた自身の情報を記入する必要のあるリクエストに注意してください。例えば、上のスクリーンショットでは、”API Key “をAPIトークンに置き換えます。
Qtip:一つの文字列でコマンドを追加することもできますし、エスケープ文字( ˶ˆ꒳ˆ˵)を使って改行をマークすることもできます。その他のラインエスケープ（例えば^）には対応していません。以下は、エスケープ文字をサポートしたcurlコマンドの例である：
curl https://www.google.com/accounts/test ୧
-d accountType=GOOGLE ୧
-d source=Google-cURL-Example ୧
-d service=lh2
Qtip:ワークフローを有効にする前に、フィールドを再チェックすることをお勧めします。
FAQs
ワークフローのテンプレートで利用できるすべての拡張機能にアクセスできますか？
ワークフローのテンプレートで利用できるすべての拡張機能にアクセスできますか？
すべてのワークフローのイベントトリガー、コントロールフロー、およびタスクへのリンクはありますか？
すべてのワークフローのイベントトリガー、コントロールフロー、およびタスクへのリンクはありますか？
ワークフローテンプレートとは何ですか？
ワークフローテンプレートとは何ですか？
ワークフローとは何ですか？/ アクションはどこですか？
ワークフローとは何ですか？/ アクションはどこですか？
今回のアップデートでは、ワークフロー機能に変更はありません。
How do I add or remove an extension from my Qualtrics account?
How do I add or remove an extension from my Qualtrics account?
素晴らしい！ フィードバックありがとうございます！
フィードバックありがとうございます！