Customer Experience
Employee Experience
Brand Experience
Core XM
Design XM

ウェブサービスタスク

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

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

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

ヒント：このページには、アクセスに特別な権限を必要とするクアルトリクスのAPIへの参照が含まれています。この機能へのアクセス権の取得に関心がある場合は、ブランド管理者に連絡して詳細を確認してください。

注意：Web サービスの設定には、高度なプログラミング知識が必要になることがよくあります。サポートチームは、Web サービスに情報を入れるという基本的なサポートを喜んで行っていますが、プログラミングに関するサポートを提供することはできません。

注意: Web サービスタスクでは、URL エンコード、XML、JSON、およびプレーンテキストのコンテンツタイプのみがサポートされます。

Web サービスタスクの設定

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

プロジェクトまたはスタンドアロンのワークフローページで、ワークフローを作成 (または既存のワークフローを選択) します。
ワークフローセクションが表示されていることを確認します。
［ワークフローを作成］をクリックします。
タスクをトリガするスケジュールまたはイベントを決定します。(比較を参照してください。)
[Add task] をクリックし、[WebService] を選択します。
認証方法を選択します。オプションは次のとおりです。
- 認証済み: 認証済み Web サービス要求を実行します。認証オプションには、Basic (パスワードとユーザ名)、API キー、および OAuth が含まれています。
- 非認証: 認証なしで Web サービス要求を実行します。
[次へ] をクリックします。
認証要求を選択した場合は、一覧から権限認証情報を選択するか、ユーザアカウント追加をクリックして新しい認証情報を追加します。詳細については、権限信用証明書の追加を参照してください。

ヒント：以前に追加した認証情報や、ブランド管理者が追加した認証情報は［拡張機能］タブで選択できます。
［次へ］をクリックします。
必要に応じて、タスクの上部に [タスクの概要] を追加します。これは、タスクの目標を説明する説明です。
Web サービスの Request 方法を選択します。各メソッドの詳細については、「Web サービスメソッド」を参照してください。

ヒント：Qualtrics APIを使用している場合は、使用するリクエストの種類がドキュメントに記載されています。

注意: Web サービスタスクでは、非 GET 要求の URL リダイレクトは許可されません。GET 要求に対して許可されるリダイレクトは 1 つのみです。
リクエストの URL を入力します。
ヒント：拡張ドメイン設定でドメインを指定することで、ウェブサービスタスクが接続できるドメインを制限できます。
必要に応じて、ヘッダ Key および Value を入力して、要求にヘッダを追加します。ヘッダには、要求に関連するメタデータが保持されます。[ヘッダーを追加] をクリックして、ヘッダーを追加します。ヘッダーを削除するには、ヘッダーの横にあるごみ箱アイコンをクリックします。
ヒント：テキストの差し込みアイコン {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とキーと値のペアを選択した場合にのみ使用できます。
データ型をキャストできない場合の処理を選択します。
- データ型をキャストせず、エラーとしてフラグを設定します。データ型をキャストできない場合、データ型はキャストされず、タスクは失敗します。これは、実行履歴タブで確認できます。
- データ型をシステムデフォルトにキャストします。データ型をキャストできない場合、データ型はシステムデフォルトに設定されます。
フリーテキストを選択した場合は、選択した書式で本文パラメータを入力します。
Web サービスをテストするには、[テストの実行] をクリックします。

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

ヒント：ウェブサービスタスクのタイムアウトは10秒です。Web サービスの呼び出しに 10 秒以上かかる場合、ワークフローは失敗します。

権限信用証明書の追加

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

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

ベーシック

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

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

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 (権限コードメソッドを使用)
権限コードメソッドを使用してズームします。

ヒント：OAuth接続を作成するときのリダイレクト URL は https://{dataCenter}.qualtrics.com/oauth-client-service/redirect で、{dataCenter}はアカウントに関連付けられた値を表します。アカウントのデータセンターの検索に関する詳細については、こちらのページを参照してください。

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

アカウントに名前を付けます。これは、独自の組織目的でのみ使用されます。
接続タイプとして OAuth を選択します。
Grant タイプ、またはアクセストークンの取得方法を選択します。以下を選択できます。
- 権限コード
- クライアントのログイン認証情報
クライアント ID とクライアントシークレットを入力します。
トークンエンドポイントを入力します。
付与タイプとして権限コードを選択した場合は、Authorization エンドポイントを入力します。
[アカウントの接続] をクリックします。

ヒント：Google OAuth認証情報を設定するユーザーは、トークンエンドポイントの末尾に以下のパラメータを含めます。「？prompt=consent。” 既存のクエリパラメータがある場合は、疑問符は必要ありません。

名前変更、認証情報の削除(&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 サービスの設定に進みます。