記事テンプレート

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

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

また、より詳しい情報や背景を知るために、これらのウェブサービス関連のページをご覧になることをお勧めします：

• クアルトリクス デベロッパーハブ
• ウェブ・サービス・メソッド
• APIドキュメント
• クエリ文字列を使用した情報の受け渡し
• テキストの差し込み

Webサービスタスクの設定

ボディ・パラメーターをどのようにフォーマットするかによって、セットアップは若干異なります。JSONまたはXML形式を使用している場合は、Bodyセクションに本文を入力してください。URLエンコードを希望する場合は、パラメータをクエリ文字列としてURLフィールドに追加することができます。

1. プロジェクトまたはスタンドアロンのワークフローページでワークフローを作成（または既存のものを選択）します。
   
2. ワークフローセクションにいることを確認してください。
3. ［ワークフローを作成］をクリックします。
4. タスクのトリガーとなるスケジュールやイベントを決定する。(比較を参照）。
5. Add taskを クリックし、WebServiceを選択する。
   
6. 自分らしくいられることを認証機能を選択します。オプションは次のとおりです。
   
   • 認証機能：認証されたWebサービスリクエストを実行します。自分らしくいられることの認証機能には、ベーシック（パスワードとユーザー名）、APIキー、OAuthがあります。
   • 非認証機能：認証機能なしでWebサービスリクエストを実行する。
7. ［次へ］をクリックします。
8. 認証機能付きリクエストを選択した場合は、リストから自分らしくいられること認証機能を選択するか、「ユーザーアカウントを追加」をクリックして新しい認証機能を追加します。詳細については、認証クレデンシャルの追加を参照してください。
   
   Qtip:以前に追加した認証情報、またはブランド管理者が追加した認証情報は、[拡張機能]タブで選択できます。
9. ［次へ］をクリックします。
10. curl形式のリクエストがあれば、それをインポートしてウェブサービスを自動的にセットアップすることができます。詳細については、「Curlコマンドの使用」セクションを参照してください。
    
11. 必要であれば、タスクの一番上にタスクサマリーを追加してください。これはタスクのゴールを説明する記述である。
12. ウェブサービスのRequestメソッドを選択します。各メソッドの詳細については、ウェブサービスのメソッドを参照してください。
    
    qtip:クアルトリクスAPIを使用している場合、どのようなリクエストタイプを使用すればよいかはドキュメントに記載されています。
    注意WebServiceタスクはGETリクエスト以外のURLリダイレクトを許可しません。GET リクエストに対して許可されるリダイレクトは一つだけです。
13. リクエストのURLを入力してください。
    Qtip:拡張ドメイン設定でドメインを指定することで、Webサービスタスクが接続できるドメインを制限することができます。
14. 必要であれば、Add headerを クリックしてヘッダーを追加する。キーと 値を指定する。 ヘッダーを削除するには、ヘッダーの次へごみ箱アイコンをクリックします。
    Qtip:テキスト差し込みアイコン{a}を使用して、ワークフロー内のアンケート回答や以前のタスクからテキストを差し込みます。
    注意クアルトリクスAPIを使用する場合は、ヘッダーにAPIトークンを含める必要があります。詳細については、クアルトリクスAPIリクエスト用のヘッダーの追加を参照してください。
15. post、put、patchのいずれかを選択した場合は、ボディのフォーマットを選択する必要があります。オプションには、JSON、 URLエンコード、XML、および プレーンテキスト。
    
    
16. リクエストの本文をどのように指定したいかを決めます。本文はKey-Valueペアまたはフリーテキストで追加できます。
17. Key-Valueペアを選択した場合は、Keyとそれに関連するValueを追加します。Add key-value pair（キーと値のペアを追加 ）」をクリックして、パラメーターを追加する。
    注意POST、PUT、PATCHリクエストでは、各キーと値のペアのデータ型を指定する必要があります。
18. データタイプを選択する。
    • ブール値：データが2つの可能な値のうちの1つを持つ場合、このデータ型を選択します。
    • JSON:データがJSON形式の場合、このデータタイプを選択します。
    • 数値：データが数値の場合、このデータタイプを選択します。
    • 文字列：データがテキスト形式の場合、このデータタイプを選択します。
    • システム・デフォルト：データのネイティブ・データ型を使用する場合は、このデータ型を選択します。データ型が見つからない場合は、String型がデフォルトとなる。
      Qtip:あなたのデータが正しくキャストされるように、他のデータタイプを選択することをお勧めします。
      注意2022年9月16日以前に設定されたKey-Valueペアのデータ型は、System Defaultとなります。
    Qtip:データタイプフィールドは、ステップ13-14でJSONとKey-valueペアを選択した場合のみ使用できます。
19. データ型をキャストできない場合の処理を選択します。
    • データ型をキャストせず、エラーとしてフラグを立てる：データ型をキャストできない場合、データ型はキャストされず、タスクは失敗する。これは実行履歴タブで見ることができる。
    • データ型をシステム・デフォルトにキャスト：データ型をキャストできない場合、データ型はシステム・デフォルトに設定されます。
20. フリーテキストを選択した場合は、選択したフォーマットで本文のパラメータを入力します。
    
    注意このフィールドを空のままにしたり、値のないキーを持たせてはいけません。その代わりに、フィールドをまったく含めないか、空の値を示す “null “を入力する。この分野は除外することをお勧めする。
    Qtip:Webサービスタスクが無効なJSONボディに遭遇しても、タスクは失敗しません。代わりに、無効なJSONは文字列に変換され、新しいJSONオブジェクトの「text」プロパティとして保存される。そうすれば、タスクの処理が終わると、無効なテキストを見ることができる。
    注意現在、Webサービスタスクはコメントをサポートしていません。
21. Webサービスをテストするには、Run testをクリックします。
    
    Qtip:Run testをクリックすると、リクエストの結果が表示され、成功したかどうか、成功した場合は結果のJSONまたはXMLが表示されます。
22. JSONまたはXmlパスを追加するには、カスタムパスを追加をクリックします。これらのパスにより、ウェブサービスの結果をテキストの差し込みで使用し、コードタスクなどワークフロー内の他のタスクで使用することができます。ウェブサービスをテストした場合、クアルトリクスが結果から自動的に値を取り出すので、ここに自動的に値が入るかもしれません。
    Qtip:カスタムパスを追加するにはカスタムパスを追加をクリックし、削除するにはパスの次へごみ箱をクリックします。
23. ワークフローの設定が完了したら、「保存」をクリックします。

認証クレデンシャルの追加

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

基本

ベーシック認証では、アカウントのユーザー名とパスワードでログインする必要があります。

1. 資格に名前をつける。これは組織的な目的のためだけのものです。
2. 接続タイプとしてベーシックを選択する。
3. 認証に必要な自分らしくいられること（Username）を入力します。
4. 認証用のパスワードを入力します。
5. アカウントの接続をクリックします。

APIキー

APIキー認証では、静的なAPIトークンを使って認証することができます。

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

OAuth 2.0

OAuth2.0認証は、サードパーティのプラットフォームと統合するために、静的なAPIトークンや基本的なユーザー名とパスワードを使用する必要性を取り除きます。ウェブサービスタスクは2つの異なるOAuth2.0認可タイプ、認可コードとクライアント認証情報をサポートします。

OAuth 2.0認証を使って、多くのサードパーティプラットフォームとシームレスに統合できます。クアルトリクスのウェブサービスの実装は、公式のOAuth仕様に従っています。しかし、外部システムによっては、WebサービスタスクのOAuth2.0認証との非互換性につながる、わずかに異なる設定を持つ場合があります。

以下の統合は、OAuth2.0で動作することが完全に確認されている例です：

• Salesforceの認証コードメソッドを使用します。
• 認証コードメソッドを使用して Jira。
• 認証コード方式でズーム。

OAuth 2.0を使って認証すること：

1. アカウントに名前を付けます。これは、あなた自身の組織的な目的のためだけのものです。
2. 接続タイプとしてOAuthを選択します。
3. グラントタイプ（アクセストークンの取得方法）を選択します。選択することができる：
   • 権限コード
   • クライアントのログイン認証情報
4. クライアントIDとクライアントシークレットを入力します。
5. トークンのエンドポイントを入力する。
6. 付与タイプとして認証コードを選択した場合は、認証エンドポイントを入力します。
7. アカウントの接続をクリックします。

名前の変更と認証情報の削除

クレデンシャルの名前を編集するには、アカウントの次へ の 3 つの点をクリックします。資格情報を削除するには、アカウントの削除をクリックします。

クアルトリクスAPIリクエスト用ヘッダの追加

クアルトリクスAPIを使用する場合、APIトークンをWebサービスのヘッダーとして含める必要があります。

1. Webサービスタスクを設定し、クレデンシャルを選択し、リクエストを選択します。
   
2. Headersセクションで、KeyにX-APIトークンを 入力する。
3. 値については、テキストの差し込みアイコン{a}をクリックします。
4. リストからクレデンシャルを選択します。
   

相互TLS

相互トランスポートレイヤーセキュリティ（mTLS）は、標準的なAPI認証機能（APIトークンやOAuthなど）の上に追加する、オプションのセキュリティレイヤーです。相互TLSは、API/ウェブサービスに接続する人とAPI/ウェブサービス自体の両方向のトラフィックが安全で暗号化されていることを保証する。mTLSを有効にすると、リクエストに成功するためには、すべてのリクエストで正しいクライアント証明書を提示する必要がある。呼び出し元が無効な、あるいは見つからないクライアント証明書を使用してリクエストを行った場合、呼び出そうとしたAPIはリクエストをブロックする。

要件

mTLSをサポートしているかどうか、どのような形式で鍵情報を提供するかは、サービスごとに異なる。私たちは、私たちの要件に合致するサービスに対してのみ、MTLSをサポートすることを保証します：

• プライベート鍵を提供
• 秘密鍵はPKCS8にフォーマットすることができる。
• 証明書の提供
• 証明書はX.509にフォーマットすることができる。

mTLSは、ワークフローで作成された認証機能付きウェブサービスでのみ
サポートされます。3つの認証機能（Basic、APIキー、OAuth2.0）に対応しています。

mTLSの追加

1. ウェブサービスタスクを作成します。
   
2. 自分らしくいられること認証機能を選ぶ。
   
3. ［次へ］をクリックします。
4. ユーザーアカウントを追加します。
   
   Qtip:ブランド管理者は、Extensionsページを使用してアカウントに接続できます。
   
5. 接続タイプを選択し、認証情報を入力します。
   
6. mTLSを有効にする］を選択します。
7. 秘密鍵は、接続しようとするクライアントの一意な識別子と考えることができる。この値はPKCS8形式である必要がある。
   Qtip:キーのフォーマットが異なる場合は、別のプログラムを使って変更することができます。
   Qtip:ウェブサービスでクアルトリクスAPIを使用する場合は、mTLSに関するAPIドキュメントをご覧ください。このドキュメントでは、秘密鍵を引き出す方法を紹介する。クアルトリクスに値を貼り付ける際には、”begin private key “と “end private key “というダッシュを入れる必要があります。
8. 公開鍵はmTLS証明書である。この値はX.509形式である必要がある。
   Qtip:ウェブサービスでクアルトリクスAPIを使用する場合は、mTLSに関するAPIドキュメントをご覧ください。この文書では、証明書を引き出す方法を説明する。クアルトリクスに値を貼り付ける際、”begin certificate “と “end certificate “というダッシュを入れる必要があります。
9. 完了したら、アカウントの接続をクリックします。
10. ウェブサービスのセットアップを進めます。

Curlコマンドの使用

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

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

curlリクエストの例については、それぞれのAPIドキュメントの右側を見てください：

• メーリングリスト取得
• リマインダー配信の作成
• 連絡先トランザクションの更新
• グループ内ユーザーリスト

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

サポートされているCurlコマンドパラメータ

クアルトリクスのウェブサービスタスクがサポートしているcurlパラメータの一部を紹介します：

共通ヘッダー・パラメーター

上記で、ヘッダーを定義するためにcurlコマンドを使用できると述べた。ヘッダは HTTP コミュニケーションにおいて、リクエストに関する情報の提供や自分らしくいられることの認証制御など、様々な役割を果たします。使用する特定のヘッダーは、使用するアプリケーションやAPIの要件に依存する。

以下はヘッダーパラメータの例である：

サポートされていないパラメータ

上記にリストされていないcurlパラメータはサポートされていません。クアルトリクスWebサービスタスクがサポートしていないcurlコマンドフォーマットの例をいくつかご紹介します：

• -リクエストと一緒にクッキーを送る場合は-cookie。
• —Lまたは--locationで次のリダイレクトを行う。
• –-max-timeは最大リクエスト時間を設定する。
• –-oまたは--outputは、回答をファイルに保存する。
• –-insecureは安全でない接続を許可する。
• –-Aまたは--user-agentでユーザーエージェントを指定する。

Curlコマンドのインポート

1. ウェブサービス・タスクのセットアップ中に、[cURLのインポート]をクリックします。
   
2. 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

3. ［インポート］をクリックします。
4. ウェブサービスのフィールドは自動的に入力されます。

FAQ