-
Qualtrics Platform -
Customer Journey Optimizer -
XM Discover -
Qualtrics Social Connect
ウェブサービスタスク
ウェブサービスタスクについて
Web サービスタスクは、API の使用経験があり、回答者がアンケートを終了したときに、Qualtrics ソフトウェア内または外部の Web サービスにさまざまなワークフローをトリガーしたい場合に便利です。たとえば、アンケートで回答者の連絡先情報を収集する場合、ウェブサービスタスクは連絡先作成API呼び出しを使用して回答者を連絡先リストに追加できます。
また、以下の Web サービス関連のページにアクセスして、サポートと背景を確認することをお奨めします。
Web サービスタスクの設定
ボディパラメータの書式設定方法に応じて、設定が若干異なります。JSON または XML 形式を使用している場合は、本文セクションに本文を入力します。URL エンコードを使用する場合は、クエリ文字列としてパラメータを URL 項目に追加することができます。
- プロジェクトまたはスタンドアロンのワークフローページで、ワークフローを作成 (または既存のワークフローを選択) します。
![[ワークフロー] タブで、[ワークフローの作成] をクリックし、イベントを受信したときに開始する](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2023/01/event-workflow-1-4.png)
- ワークフローセクションが表示されていることを確認します。
- ［ワークフローを作成］をクリックします。
- タスクをトリガするスケジュールまたはイベントを決定します。(比較を参照してください。)
- [Add task] をクリックし、[WebService] を選択します。
- 認証方法を選択します。オプションは次のとおりです。
![認証タイプを選択し、[次へ] をクリックします。](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2021/05/webservice-task-67-e1629823557711.png)
- 認証済み: 認証済み Web サービス要求を実行します。認証オプションには、Basic (パスワードとユーザ名)、API キー、および OAuth が含まれています。
- 非認証: 認証なしで Web サービス要求を実行します。
- [次へ] をクリックします。
- 認証要求を選択した場合は、一覧から権限認証情報を選択するか、ユーザアカウント追加をクリックして新しい認証情報を追加します。詳細については、権限信用証明書の追加を参照してください。
ヒント：以前に追加した認証情報や、ブランド管理者が追加した認証情報は［拡張機能］タブで選択できます。 - ［次へ］をクリックします。
- curl形式のリクエストがあれば、それをインポートしてウェブサービスを自動的にセットアップすることができます。詳細については、「Curlコマンドの使用」セクションを参照してください。
- 必要に応じて、タスクの上部に [タスクの概要] を追加します。これは、タスクの目標を説明する説明です。
- Web サービスの Request 方法を選択します。各メソッドの詳細については、「Web サービスメソッド」を参照してください。
ヒント：Qualtrics APIを使用している場合は、使用するリクエストの種類がドキュメントに記載されています。注意: Web サービスタスクでは、非 GET 要求の URL リダイレクトは許可されません。GET 要求に対して許可されるリダイレクトは 1 つのみです。 - リクエストの URL を入力します。
ヒント：拡張ドメイン設定でドメインを指定することで、ウェブサービスタスクが接続できるドメインを制限できます。
- 必要に応じて、[ヘッダーの追加] をクリックしてヘッダーを追加します。キーと値を指定します。 ヘッダーを削除するには、ヘッダーの横にあるごみ箱アイコンをクリックします。
ヒント：テキストの差し込みアイコン {a} を使用してテキストの差し込みを挿入し、アンケートの回答またはワークフロー内の以前のタスクから値を取り込みます。注意：Qualtrics APIを使用する場合は、ヘッダーからAPIトークンを含める必要があります。詳細については「Qualtrics APIリクエストのヘッダーの追加」を参照してください。注意:POST、PUT、および PATCH の要求では、キーと値のペアごとにデータ型を指定する必要があります。注意: Web サービスタスクは現在、エスケープシーケンスを含む本文のコメント/テキストをサポートしていません。
- post、put、patchを選択した場合は、本文の書式を選択する必要があります。オプションには、JSON、URL エンコード、XML、および プレーンテキスト。
ヒント：プレーンテキストはフリーテキストとしてのみ指定できます。JSON Free text オプションを使用すると、入力はエスケープされません。これは、たとえば、二重引用符や改行文字 (例: \n) を含む差し込みテキスト入力により、JSON 本文が無効になり、正しく実行されないことを意味します。代わりに、キーと値のペアオプションを使用するか、コードタスクを使用して、Web サービスタスクに挿入するテキストをクリーンアップまたはエスケープします。 - 要求の本文を指定する方法を決定します。ボディは、キーと値のペアまたはフリーテキストとして追加できます。
- キーと値のペアを選択した場合は、Key とその関連する Value を追加します。キーと値のペアを追加をクリックして、パラメータを追加します。
- データ型を選択します。
- ブール値: データに使用可能な 2 つの値のいずれかが含まれている場合は、このデータ型を選択します。
- JSON: データが JSON 形式の場合は、このデータ型を選択します。
- 数値: データが数値の場合は、このデータ型を選択します。
- 文字列: データがテキスト形式の場合は、このデータ型を選択します。
- システムデフォルト: データにネイティブデータ型を使用する場合は、このデータ型を選択します。データ型が見つからない場合、デフォルトは文字列型になります。
ヒント：データが正しくキャストされるように、他のいずれかのデータ型を選択することをお勧めします。注意: 2022 年 9 月 16 日より前に設定されたキーと値のペアのデータ型は、システムデフォルトになります。
ヒント：［データ型］フィールドは、ステップ13-14でJSONとキーと値のペアを選択した場合にのみ使用できます。 - データ型をキャストできない場合の処理を選択します。
- データ型をキャストせず、エラーとしてフラグを設定します。データ型をキャストできない場合、データ型はキャストされず、タスクは失敗します。これは、実行履歴タブで確認できます。
- データ型をシステムデフォルトにキャストします。データ型をキャストできない場合、データ型はシステムデフォルトに設定されます。
- フリーテキストを選択した場合は、選択した書式で本文パラメータを入力します。
注意: この項目を空白のままにしたり、値のないキーを含めたりしないでください。代わりに、フィールドをまったく含めないか、空の値を示す用語 “null” を入力します。項目を除外することをお奨めします。 - Web サービスをテストするには、[テストの実行] をクリックします。
ヒント：［テストを実行］をクリックすると、リクエストの結果が表示され、要求が成功したかどうかと、結果の JSON または XML (成功した場合) が通知されます。 - カスタムパスを追加をクリックして、JSON または XML パスを追加します。これらのパスを使用すると、テキストの差し込みで Web サービスの結果を使用して、ワークフロー内の他のタスク (コードタスクなど) で使用できるようになります。ウェブサービスをテストした場合、Qualtricsが自動的に結果から値を取得するため、ここに値が自動的に表示される場合があります。
ヒント：［カスタムパスを追加］をクリックしてパスを追加するか、パスの横にあるごみ箱をクリックして削除します。
- ワークフローの設定が完了したら、 [保存] をクリックします。
![認証タイプを選択し、[次へ] をクリックします。](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2021/05/webservice-task-67.png)
権限信用証明書の追加
このセクションでは、Web サービスタスクの権限認証情報を追加する方法について説明します。Basic、API Key、または OAuth 2.0 メソッドを使用して認証情報を追加できます。認証情報を追加するには、認証情報選択ウィンドウからユーザアカウント追加をクリックします。
ベーシック
基本認証では、アカウントのユーザー名とパスワードを使用してログインする必要があります。
- 認証情報に名前を付けます。これは、組織的な目的でのみ使用されます。
- 接続タイプとして基本を選択します。
- 認証に必要な [ユーザー名] を入力します。
- 認証の [パスワード] を入力します。
- [アカウントの接続] をクリックします。
APIキー
API キー認証では、静的 API トークンを使用して認証できます。
- アカウントに名前を付けます。これは、組織的な目的でのみ使用されます。
- 接続タイプとして API キーを選択します。
- 認証に使用する API トークンを入力します。
- [アカウントの接続] をクリックします。
OAuth 2.0
OAuth2.0 認証により、サードパーティプラットフォームと統合するために静的 API トークンまたは基本的なユーザ名とパスワードを使用する必要がなくなります。Web サービスタスクでは、認証コードとクライアント認証情報の 2 つの異なる OAuth2.0 認証タイプがサポートされています。
OAuth 2.0 権限を使用して、多くのサードパーティプラットフォームとシームレスに統合することができます。Qualtrics Web サービスの実装は、正式な OAuth 仕様に従います。ただし、一部の外部システムでは、設定が若干異なるため、Web サービスタスクで OAuth2.0 認証との互換性がない場合があります。
以下の統合は、OAuth2.0 を使用するために完全に検証された例です。
- Salesforce は認証コードメソッドを使用します。
- Jira (権限コードメソッドを使用)
- 権限コードメソッドを使用してズームします。
https://{dataCenter}.qualtrics.com/oauth-client-service/redirect で、{dataCenter}はアカウントに関連付けられた値を表します。アカウントのデータセンターの検索に関する詳細については、こちらのページを参照してください。OAuth 2.0 を使用して認証するには、以下の手順に従います。
- アカウントに名前を付けます。これは、独自の組織目的でのみ使用されます。
- 接続タイプとして OAuth を選択します。
- Grant タイプ、またはアクセストークンの取得方法を選択します。以下を選択できます。
- 権限コード
- クライアントのログイン認証情報
- クライアント ID とクライアントシークレットを入力します。
- トークンエンドポイントを入力します。
- 付与タイプとして権限コードを選択した場合は、Authorization エンドポイントを入力します。
- [アカウントの接続] をクリックします。
名前変更、認証情報の削除(&A)
認証情報の名前を編集するには、アカウントの横にある 3 つのドットをクリックします。認証情報を削除するには、アカウントを削除をクリックします。
Qualtrics API リクエストへのヘッダーの追加
Qualtrics APIを使用する場合は、APIトークンをヘッダーとしてウェブサービスに含める必要があります。
- Web サービスタスクを設定し、認証情報を選択して、要求を選択します。
- ヘッダセクションで、キーとして X-API-TOKEN を入力します。
- 値については、テキストの差し込みアイコン {a} をクリックします。
- 一覧から認証情報を選択します。
相互 TLS
相互 Transport Layer Security (mTLS) は、標準の API 認証メカニズム (API トークンや OAuth など) に加えて、追加のオプションのセキュリティレイヤです。相互 TLS により、API/Web サービスに接続するユーザーと API/Web サービス自体の両方で、セキュアな暗号化されたトラフィックが双方向で確保されます。mTLS を有効にすると、要求が正常に行われるように、すべての要求で正しいクライアント証明書が提示される必要があります。呼出元が無効または不足しているクライアント証明書を使用して要求を行うと、呼出しようとしている API によって要求がブロックされます。
要件
各サービスは、mTLS をサポートしているかどうか、および主要な情報を提供する形式によって異なります。要件に合致するサービスに対してのみ mTLS がサポートされることが保証されています。
- 秘密鍵を指定してください
- PKCS8 に書式設定可能な秘密鍵
- 証明書の提供
- 証明書は X.509 に書式設定可能
クアルトリクスのパブリックAPIは、上記のようにmTLSをサポートしています。
mTLSは、ワークフローで作成された認証済みWebサービスでのみサポートされています。3 つの認証方法 (Basic、API キー、および OAuth2.0) がすべてサポートされています。
mTLS の追加
- Web サービスタスクを作成します。
- 認証済を選択します。
- [次へ] をクリックします。
- ユーザアカウントを追加します。
- 接続タイプを選択し、認証情報を入力します。
- Enable mTLS を選択します。
- 秘密鍵は、接続しようとしているクライアントの一意の識別子と考えることができます。この値は PKCS8 形式である必要があります。
ヒント：キーのフォーマットが異なる場合は、別のプログラムを使用してこのフォーマットを変更できます。ヒント：クアルトリクスAPIをウェブサービスで使用する予定がある場合は、mTLSに関するAPIドキュメントを参照してください。この文書では、秘密鍵のプル方法について説明します。Qualtricsでこの値を貼り付ける場合、「秘密鍵の開始」と「秘密鍵の終了」を示すダッシュを含める必要があります。
- 公開鍵は mTLS 証明書です。この値は X.509 形式である必要があります。
ヒント：クアルトリクスAPIをウェブサービスで使用する予定がある場合は、mTLSに関するAPIドキュメントを参照してください。この文書では、証明書のプル方法について説明します。Qualtricsでこの値を貼り付ける場合、「証明書の開始」と「証明書の終了」を示すダッシュを含める必要があります。
- 終了したら、［アカウントを接続］をクリックします。
- Web サービスの設定に進みます。
Curlコマンドの使用
Curlコマンドは、HTTPリクエストを行うことができる多くの方法の1つであり、URLを通じて情報をやり取りするための貴重なツールです。タスクのセットアップ中にcurlコマンドをインポートして、異なるウェブサービスの設定を自動入力することができます。
多くのAPIドキュメントには、使用できるcurlの例が記載されていることが多い。これらのコマンドをコピーしてインポートすることで、ウェブサービスのセットアップをより迅速かつ簡単に行うことができる。
curlリクエストの例については、それぞれのAPIドキュメントの右側を見てほしい：
GETリクエストの場合、curlコマンドはcurl https://api.example.com/parameters。これほど単純でないcurlコマンドについては、一般的なパラメータをいくつか用意しておこう。
サポートされる Curl コマンド パラメータ
以下は、Qualtricsウェブサービスタスクがサポートするcurlパラメータの一部です：
| Parameter | 説明 | カールコマンド | 例 |
| 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はメッセージボディに含まれるリソースのメディアタイプを示す。 | コンテントタイプ：application/json |
| 権限 | 保護されたリソースにアクセスするための認証情報を提供する。 | 認証：ベアラートークン |
| イータグ | リソースの特定のバージョンに対する一意な識別子を提供する。 | ETag："123456" |
| コンテンツ長 | メッセージのentity-bodyのサイズを設定する。 | コンテンツ長：1024 |
| 元 | リクエストの発信元を示す。これは、Cross-Origin Resource Sharing（CORS）に役立ちます。 | 原産地：https://example.com |
サポートされていないパラメータ
上記以外のcurlパラメータはサポートされていません。以下は、Qualtricsウェブサービスタスクがサポートしていないcurlコマンドフォーマットの例です：
- -リクエストと一緒にクッキーを送信する場合は-cookie。
- —Lまたは--locationで次のリダイレクトを行う。
- –-max-timeで最大リクエスト時間を設定する。
- –-oまたは--outputは、レスポンスをファイルに保存する。
- –-insecureは安全でない接続を許可する。
- –-Aまたは--user-agentでユーザーエージェントを指定する。
Curlコマンドのインポート
- Webサービスタスクのセットアップ中に、［cURLのインポート］をクリックします。
- curlコマンドをボックスに貼り付ける。
注意：特に他のプラットフォームからcurlコマンドをコピーする場合は、curlリクエストにHTTPメソッドを含めるようにしてください。ヒント：自分の情報を記入する必要のあるリクエストの部分に注意してください。例えば、上のスクリーンショットでは、”API Key “をAPIトークンに置き換えている。Qtip:コマンドは1つの文字列で追加することもできますし、エスケープ文字( ˶ˆ꒳ˆ˵)を使って改行することもできます。その他のラインエスケープ（例えば^）はサポートしていません。サポートされているエスケープ文字を使用したcurlコマンドの例を以下に示す：
curl https://www.google.com/accounts/test ୧ -d accountType=GOOGLE ୧ -d source=Google-cURL-Example ୧ -d service=lh2 - ［インポート］をクリックします。
- ウェブサービスのフィールドは自動的に入力されます。