Skip to main content
Loading...
Skip to article
  • Qualtrics Platform
    Qualtrics Platform
  • Customer Journey Optimizer
    Customer Journey Optimizer
  • XM Discover
    XM Discover
  • Qualtrics Social Connect
    Qualtrics Social Connect

ウェブサービスタスク


Was this helpful?


This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!


ウェブサービスタスクについて

Web サービスタスクは、API の使用経験があり、回答者がアンケートを終了したときに、Qualtrics ソフトウェア内または外部の Web サービスにさまざまなワークフローをトリガーしたい場合に便利です。たとえば、アンケートで回答者の連絡先情報を収集する場合、ウェブサービスタスクは連絡先作成API呼び出しを使用して回答者を連絡先リストに追加できます。

また、以下の Web サービス関連のページにアクセスして、サポートと背景を確認することをお奨めします。

ヒント:このページには、アクセスに特別な権限を必要とするクアルトリクスのAPIへの参照が含まれています。この機能へのアクセス権の取得に関心がある場合は、ブランド管理者に連絡して詳細を確認してください。
注意:Web サービスの設定には、高度なプログラミング知識が必要になることがよくあります。サポートチームは、Web サービスに情報を入れるという基本的なサポートを喜んで行っていますが、プログラミングに関するサポートを提供することはできません。
注意: Web サービスタスクでは、URL エンコード、XML、JSON、およびプレーンテキストのコンテンツタイプのみがサポートされます。
Qtip: APIドキュメントからウェブサービスをセットアップしていますか?curlコマンドをインポートすれば、セットアップはもっと速くなる。

Web サービスタスクの設定

注意: Web サービスタスクで実行中の呼び出しからの出力の上限は 1MB です。

ボディパラメータの書式設定方法に応じて、設定が若干異なります。JSON または XML 形式を使用している場合は、本文セクションに本文を入力します。URL エンコードを使用する場合は、クエリ文字列としてパラメータを URL 項目に追加することができます。

  1. プロジェクトまたはスタンドアロンのワークフローページで、ワークフローを作成 (または既存のワークフローを選択) します。
    [ワークフロー] タブで、[ワークフローの作成] をクリックし、イベントを受信したときに開始する
  2. ワークフローセクションが表示されていることを確認します。
  3. ワークフローを作成]をクリックします。
  4. タスクをトリガするスケジュールまたはイベントを決定します。(比較を参照してください。)
  5. [Add task] をクリックし、[WebService] を選択します。
    Web サービスイベント
  6. 認証方法を選択します。オプションは次のとおりです。
    認証タイプを選択し、[次へ] をクリックします。

    • 認証済み: 認証済み Web サービス要求を実行します。認証オプションには、Basic (パスワードとユーザ名)、API キー、および OAuth が含まれています。
    • 非認証: 認証なしで Web サービス要求を実行します。
  7. [次へ] をクリックします。
  8. 認証要求を選択した場合は、一覧から権限認証情報を選択するか、ユーザアカウント追加をクリックして新しい認証情報を追加します。詳細については、権限信用証明書の追加を参照してください。
    ユーザアカウントの追加、または既存のアカウントの選択

    ヒント:以前に追加した認証情報や、ブランド管理者が追加した認証情報は[拡張機能]タブで選択できます。
  9. 次へ]をクリックします。
  10. curl形式のリクエストがあれば、それをインポートしてウェブサービスを自動的にセットアップすることができます。詳細については、「Curlコマンドの使用」セクションを参照してください。
    curlコマンドをインポートしてヘッドスターを獲得するボタン; タスクサマリーフィールド
  11. 必要に応じて、タスクの上部に [タスクの概要] を追加します。これは、タスクの目標を説明する説明です。
  12. Web サービスの Request 方法を選択します。各メソッドの詳細については、「Web サービスメソッド」を参照してください。
    要求の選択と URL の入力

    ヒント:Qualtrics APIを使用している場合は、使用するリクエストの種類がドキュメントに記載されています。
    注意: Web サービスタスクでは、非 GET 要求の URL リダイレクトは許可されません。GET 要求に対して許可されるリダイレクトは 1 つのみです。
  13. リクエストの URL を入力します。
  14. 必要に応じて、[ヘッダーの追加] をクリックしてヘッダーを追加します。キーと値を指定します。 ヘッダーを削除するには、ヘッダーの横にあるごみ箱アイコンをクリックします。
    ヒント:テキストの差し込みアイコン {a} を使用してテキストの差し込みを挿入し、アンケートの回答またはワークフロー内の以前のタスクから値を取り込みます。
    注意:Qualtrics APIを使用する場合は、ヘッダーからAPIトークンを含める必要があります。詳細については「Qualtrics APIリクエストのヘッダーの追加」を参照してください。
    注意:POSTPUT、および PATCH の要求では、キーと値のペアごとにデータ型を指定する必要があります。
    注意: Web サービスタスクは現在、エスケープシーケンスを含む本文のコメント/テキストをサポートしていません。
  15. post、put、patchを選択した場合は、本文の書式を選択する必要があります。オプションには、JSONURL エンコードXML、および プレーンテキスト。
    本文パラメータを Web サービスに追加し、キー値ペアを本文要求に追加する

    ヒント:プレーンテキストはフリーテキストとしてのみ指定できます。JSON Free text オプションを使用すると、入力はエスケープされません。これは、たとえば、二重引用符や改行文字 (例: \n) を含む差し込みテキスト入力により、JSON 本文が無効になり、正しく実行されないことを意味します。代わりに、キーと値のペアオプションを使用するか、コードタスクを使用して、Web サービスタスクに挿入するテキストをクリーンアップまたはエスケープします。
  16. 要求の本文を指定する方法を決定します。ボディは、キーと値のペアまたはフリーテキストとして追加できます。
  17. キーと値のペアを選択した場合は、Key とその関連する Value を追加します。キーと値のペアを追加をクリックして、パラメータを追加します。
  18. データ型を選択します。
    • ブール値: データに使用可能な 2 つの値のいずれかが含まれている場合は、このデータ型を選択します。
    • JSON: データが JSON 形式の場合は、このデータ型を選択します。
    • 数値: データが数値の場合は、このデータ型を選択します。
    • 文字列: データがテキスト形式の場合は、このデータ型を選択します。
    • システムデフォルト: データにネイティブデータ型を使用する場合は、このデータ型を選択します。データ型が見つからない場合、デフォルトは文字列型になります。
      ヒント:データが正しくキャストされるように、他のいずれかのデータ型を選択することをお勧めします。
      注意: 2022 年 9 月 16 日より前に設定されたキーと値のペアのデータ型は、システムデフォルトになります。
    ヒント:データ型]フィールドは、ステップ13-14でJSONキーと値のペアを選択した場合にのみ使用できます。
  19. データ型をキャストできない場合の処理を選択します。
    • データ型をキャストせず、エラーとしてフラグを設定します。データ型をキャストできない場合、データ型はキャストされず、タスクは失敗します。これは、実行履歴タブで確認できます。
    • データ型をシステムデフォルトにキャストします。データ型をキャストできない場合、データ型はシステムデフォルトに設定されます。
  20. フリーテキストを選択した場合は、選択した書式で本文パラメータを入力します。
    本文がフリーテキストに設定されているため、キーと値のペアの代わりに、大きなテキスト項目が存在します。

    注意: この項目を空白のままにしたり、値のないキーを含めたりしないでください。代わりに、フィールドをまったく含めないか、空の値を示す用語 “null” を入力します。項目を除外することをお奨めします。
  21. Web サービスをテストするには、[テストの実行] をクリックします。
    実行テストボタン。JSON パスを追加するセクションの差し込みテキスト

    ヒント:[テストを実行]をクリックすると、リクエストの結果が表示され、要求が成功したかどうかと、結果の JSON または XML (成功した場合) が通知されます。
  22. カスタムパスを追加をクリックして、JSON または XML パスを追加します。これらのパスを使用すると、テキストの差し込みで Web サービスの結果を使用して、ワークフロー内の他のタスク (コードタスクなど) で使用できるようになります。ウェブサービスをテストした場合、Qualtricsが自動的に結果から値を取得するため、ここに値が自動的に表示される場合があります。
    ヒント:カスタムパスを追加]をクリックしてパスを追加するか、パスの横にあるごみ箱をクリックして削除します。
  23. ワークフローの設定が完了したら、 [保存] をクリックします。
ヒント:ウェブサービスタスクのタイムアウトは16秒です。Web サービスの呼び出しに 10 秒以上かかる場合、ワークフローは失敗します。

権限信用証明書の追加

このセクションでは、Web サービスタスクの権限認証情報を追加する方法について説明します。Basic、API Key、または OAuth 2.0 メソッドを使用して認証情報を追加できます。認証情報を追加するには、認証情報選択ウィンドウからユーザアカウント追加をクリックします。

ヒント:すべての接続タイプは、mTLSと互換性があります。詳細については、「相互 TLS」セクションを参照してください。

ベーシック

基本認証では、アカウントのユーザー名とパスワードを使用してログインする必要があります。

新しい Basic 認証アカウントの追加

  1. 認証情報に名前を付けます。これは、組織的な目的でのみ使用されます。
  2. 接続タイプとして基本を選択します。
  3. 認証に必要な [ユーザー名] を入力します。
  4. 認証の [パスワード] を入力します。
  5. [アカウントの接続] をクリックします。

APIキー

API キー認証では、静的 API トークンを使用して認証できます。

新しい API アカウントの追加

  1. アカウントに名前を付けます。これは、組織的な目的でのみ使用されます。
  2. 接続タイプとして API キーを選択します。
  3. 認証に使用する API トークンを入力します。
  4. [アカウントの接続] をクリックします。

OAuth 2.0

OAuth2.0 認証により、サードパーティプラットフォームと統合するために静的 API トークンまたは基本的なユーザ名とパスワードを使用する必要がなくなります。Web サービスタスクでは、認証コードとクライアント認証情報の 2 つの異なる OAuth2.0 認証タイプがサポートされています。

OAuth 2.0 権限を使用して、多くのサードパーティプラットフォームとシームレスに統合することができます。Qualtrics Web サービスの実装は、正式な OAuth 仕様に従います。ただし、一部の外部システムでは、設定が若干異なるため、Web サービスタスクで OAuth2.0 認証との互換性がない場合があります。

以下の統合は、OAuth2.0 を使用するために完全に検証された例です。

  • Salesforce は認証コードメソッドを使用します。
  • Jira (権限コードメソッドを使用)
  • 権限コードメソッドを使用してズームします。
ヒント:OAuth接続を作成するときのリダイレクト URL は https://{dataCenter}.qualtrics.com/oauth-client-service/redirect で、{dataCenter}はアカウントに関連付けられた値を表します。アカウントのデータセンターの検索に関する詳細については、こちらのページを参照してください

OAuth 2.0 を使用して認証するには、以下の手順に従います。

新しい oauth アカウントの追加

  1. アカウントに名前を付けます。これは、独自の組織目的でのみ使用されます。
  2. 接続タイプとして OAuth を選択します。
  3. Grant タイプ、またはアクセストークンの取得方法を選択します。以下を選択できます。
    • 権限コード
    • クライアントのログイン認証情報
  4. クライアント IDクライアントシークレットを入力します。
  5. トークンエンドポイントを入力します。
  6. 付与タイプとして権限コードを選択した場合は、Authorization エンドポイントを入力します。
  7. [アカウントの接続] をクリックします。
ヒント:Google OAuth認証情報を設定するユーザーは、トークンエンドポイントの末尾に以下のパラメータを含めます。「?prompt=consent。”  既存のクエリパラメータがある場合は、疑問符は必要ありません。
ヒント:Snowflakeとの接続に問題がある場合は、クアルトリクスのIP範囲が許可リストに登録されていることを確認してください。

名前変更、認証情報の削除(&A)

認証情報の名前を編集するには、アカウントの横にある 3 つのドットをクリックします。認証情報を削除するには、アカウントを削除をクリックします。
アカウントの横にある[名前変更]と[削除]ボタン

ヒント:自分が追加した認証情報のみ、名前を変更または削除できます。
警告: 認証情報を削除する際は注意してください認証情報を使用するワークフローは、認証情報が削除されると動作を停止します。

Qualtrics API リクエストへのヘッダーの追加

Qualtrics APIを使用する場合は、APIトークンをヘッダーとしてウェブサービスに含める必要があります。

  1. Web サービスタスクを設定し、認証情報を選択して、要求を選択します。
    ヘッダとしての API トークンの追加
  2. ヘッダセクションで、キーとして X-API-TOKEN を入力します。
  3. 値については、テキストの差し込みアイコン {a} をクリックします。
  4. 一覧から認証情報を選択します。
    トークンヘッダの API トークンフィールドの選択

相互 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 の追加

  1. Web サービスタスクを作成します
    Web サービスタスクの選択
  2. 認証済を選択します。
    次のウィンドウに、認証済み Web サービスと未認証の Web サービスの 2 つのオプションが表示されます。
  3. [次へ] をクリックします。
  4. ユーザアカウントを追加します。
    ウィンドウの次のページの左上にユーザアカウントを追加するためのボタン。

    ヒント:ブランド管理者は拡張機能]ページを使用してアカウントに接続できます。
    管理ページの拡張タブでの Web サービス拡張の表示
  5. 接続タイプを選択し、認証情報を入力します。
    Web サービス認証情報
  6. Enable mTLS を選択します。
  7. 秘密鍵は、接続しようとしているクライアントの一意の識別子と考えることができます。この値は PKCS8 形式である必要があります。
    ヒント:キーのフォーマットが異なる場合は、別のプログラムを使用してこのフォーマットを変更できます。
    ヒント:クアルトリクスAPIをウェブサービスで使用する予定がある場合は、mTLSに関するAPIドキュメントを参照してください。この文書では、秘密鍵のプル方法について説明します。Qualtricsでこの値を貼り付ける場合、「秘密鍵の開始」と「秘密鍵の終了」を示すダッシュを含める必要があります。
  8. 公開鍵は mTLS 証明書です。この値は X.509 形式である必要があります。
    ヒント:クアルトリクスAPIをウェブサービスで使用する予定がある場合は、mTLSに関するAPIドキュメントを参照してください。この文書では、証明書のプル方法について説明します。Qualtricsでこの値を貼り付ける場合、「証明書の開始」と「証明書の終了」を示すダッシュを含める必要があります。
  9. 終了したら、[アカウントを接続]をクリックします。
  10. Web サービスの設定に進みます
ヒント:Web サービスで API 呼び出しを実行するまで、mTLS キーの有効性をテストできないため、キーを誤って入力しても、このページにエラーメッセージは表示されません。ワークフローをライブにする前に、Web サービスをテストしてください。

Curlコマンドの使用

Curlコマンドは、HTTPリクエストを行うことができる多くの方法の1つであり、URLを通じて情報をやり取りするための貴重なツールです。タスクのセットアップ中にcurlコマンドをインポートして、異なるウェブサービスの設定を自動入力することができます。

多くのAPIドキュメントには、使用できるcurlの例が記載されていることが多い。これらのコマンドをコピーしてインポートすることで、ウェブサービスのセットアップをより迅速かつ簡単に行うことができる。

curlリクエストの例については、それぞれのAPIドキュメントの右側を見てほしい:

GETリクエストの場合、curlコマンドはcurl https://api.example.com/parameters。これほど単純でないcurlコマンドについては、一般的なパラメータをいくつか用意しておこう。

Qtip:既存のウェブサービスタスクを編集している場合、インポートしたcurlコマンドは以前の設定を上書きします。
Qtip:下記で説明する以外のcurlについてもっと知りたい場合は、IBMのドキュメントなどQualtricsサポート以外のリソースを読むことをお勧めします。

サポートされる 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つのタグを置き換える:

&nbsp

;--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でユーザーエージェントを指定する。
Qtip:サポートされていないパラメータを使用してcurlコマンドをインポートしようとすると、使用したサポートされていないパラメータをリストしたエラーメッセージが表示されます。サポートされていないパラメータを削除して、curlコマンドのインポートを続行するオプションが与えられます。

Curlコマンドのインポート

  1. Webサービスタスクのセットアップ中に、[cURLのインポート]をクリックします。
    ボタンをクリックすると、curlコマンドをインポートしてスタートダッシュを切ることができる。
  2. 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
  3. インポート]をクリックします。
  4. ウェブサービスのフィールドは自動的に入力されます。
Qtip:ワークフローを有効にする前に、フィールドを再チェックすることをお勧めします。

FAQ

当サポートサイトの日本語のコンテンツは英語原文より機械翻訳されており、補助的な参照を目的としています。機械翻訳の精度は十分な注意を払っていますが、もし、英語・日本語翻訳が異なる場合は英語版が正となります。英語原文と機械翻訳の間に矛盾があっても、法的拘束力はありません。