データ転送

WebサービスはホストシステムとVocollect VoiceCheckの間でトランザクションデータを送信するのに使用されます。VoiceCheck はSOAPおよびREST Webサービスをサポートしてます。これらのサービスは VoiceCheck システムに対しインポートおよびエクスポート機能を提供します。

サービスおよびメッセージフォーマットについて以下に説明します。またSOAP Web Service Description Language (WSDL) および RESTWeb Application Description Language (WADL) の参考XMLが製品パッケージに含まれています。サービスの説明は従来Webブラウザに http://<host>:<port>/VoiceCheck/services/api/swagger.json と入力することにより表示することができました。このリンクは以前使われていたリンク、 http://<host>:<port>/VoiceCheck/services を置き換えるものです。

Web サービスメッセージフロー

設定とセキュリティ

全ての通信はVoiceCheckの設定に従ってHTTP または HTTPSで行われます。

データインポートに対してはVoiceCheckの提供するすべてのSOAP Webサービスは WS-Security UsernameTokenによる認証を必要とします。インポートに使用するすべてのREST WebサービスはHTTPベーシック認証を使った認証が必要です。

VoiceCheckはユーザインターフェイスで設定可能なアクセス権限があります。これはユーザがWebサービスを実行する権限を設定するものです。ホストシステムのWebサービスクライアントはこの役割を持ったユーザとしてVoiceCheckと認証を行うよう設定する必要があります。

VoiceCheckでは、データのエクスポート用に、ホストシステム上のSOAPまたはREST WebサービスにアクセスするHTTPベーシック認証を使用した認証をサポートしています。認証は任意ですが、使用する場合、これはVoiceCheckで設定され、パスワードは暗号化されVoiceCheckデータベースに保存されます。

VoiceCheckはホストシステムの提供するサービスに対しサービスエンドポイントURLを設定する方法も用意しています。このエンドポイントURLはGUIで必須の設定項目です。

ホストシステムがVoiceCheckに対し提供するすべてのサービスを使用するためのユーザ名とパスワードは1つだけです。現在、VoiceCheckに対して1つだけ提供されているサービスは作業指示の結果をホストシステムに送信するものです。

設定情報（サービスエンドポイント、Webサービスクライアントタイプ、ユーザ名、パスワード）はVoiceCheckのシステムレベルで設定されます。これらの設定は管理 > システム設定ページにあります。設定はVoiceCheckの1つのインスタンスが単一のホストシステムエンドポイントに接続することを前提としています。

XML スキーマと名前空間

VoiceCheckはSOAPおよびRESTサービスで使用するすべてのXML要素に対する名前空間を宣言しますが、例外はfaultInfo要素です（下記のメモ参照）。名前空間は次の通りです：

http://service.web.voicecheck.vocollect.com/

VoiceCheckがデータインポートに提供するSOAP サービスの場合、名前空間とスキーマはWSDLにあります。

VoiceCheckがデータインポートに提供するREST サービスの場合、名前空間とスキーマはWADLにあります。Create Assignment Web Serviceの場合、RESTクライアントは名前空間でXMLを修飾する必要はありませんが、これを行うことを強くお勧めします。

VoiceCheckが作業指示の結果をホストシステムに送る際に使用するRESTサービスの場合、サーバがXMLに期待する名前空間とスキーマは製品パッケージに含まれるサンプルWADLに定義されています。

faultInfo要素は名前空間の一部として定義されません。REST サービスの場合、VoiceCheckはこれをエラー応答の中でホストシステムに送る際この要素を名前空間で修飾しません。同様に、ホストシステムもVoiceCheckへの応答でfaultInfo要素を名前空間で修飾することはできません。

作業指示データの失敗の扱い

RESTのフォルトの扱い

失敗が発生すると、その失敗の種類と処理のどこで発生したかによって様々なHTTPステータスコードを返すことができます。VoiceCheckはApache^® CXF フレームワークを使ってWebサービスリクエストを処理しており、このフレークワークはそれ自身の処理で 406 – Not Acceptable、 415 – Unsupported Media TypeなどVoiceCheckビジネスロジックに到達する前にエラーを返すことができます。

VoiceCheck作業ロジックには2つのステータスコードのいずれかしかありません：

400 – Bad Request: クライアントがビジネスルールまたは制約に違反しました（通常はデータの異常です）。コンテンツに変更を行わずに同じメッセージを送信すると同じエラーが発生します。
500 – Internal Server Error: 要求の処理中に内部サーバエラーが発生しました。メッセージの再試行で成功する場合もあるかもしれません。

VoiceCheckビジネスロジックには発生したエラーの情報を含むfaultInfo XML要素が含まれます。faultInfo要素のプロパティを以下に示します。

SOAPの失敗の扱い

全ての失敗に対して SOAP 1.1 エラーが返されます。全てのエラーには SOAP 1.1 で指定されれるフォルトコードまたはフォルト文字列が含まれます。コアSOAP 1.1 フォルトコードのうちClientとServerの2つはほとんどのエラーに含まれています。 VoiceCheckは一般にこれらのコードをSOAP 1.1仕様で指定されている通りの方法で使用します。

WS-Security （Web Services Security）で指定されたフォルトコードを使用する、認証時に発生するエラーがあります。Java WebサービスAPIならびにその実装は他のフォルトコードを返す場合があります。

発生する可能性のあるフォルトコードをすべてリストすることは不可能ですが、Webサービスクライアントが一貫したエラーの扱いを行うための一般的ルールがあります：

Server以外のフォルトコードは通常、メッセージを自動的に再送信する意味がないことを示しています。これらは認証の失敗またはメッセージの形式が不正であるなど、サーバ上のアプリケーションロジックに到達する前にクライアントが何か間違いを起こしている時に送信されます。
フォルトコードがServeである場合、エラーがアプリケーションサーバロジックから発生している場合にはSOAP 1.1のエラー詳細要素が含まれます。その形式はWSDLで指定されていますが、以下のセクションに示す情報が含まれています。

Fault Info 要素

REST および SOAP Webサービスのどちらにも VoiceCheck アプリケーションサーバロジックからエラーが返されると同じエラー情報が含まれます。

このエラーメッセージをVoiceCheck GUIで表示するにはPost Assignment ResultsウェブサービスのホストサーバREST実装でこのエラーを使用する必要があります。それ以外の場合、ユーザには一般的なメッセージが表示されます。

プロパティ	タイプ	定義
errorCode	long	エラーを表す数値コード有効な値： 3000 = Internal server error （再試行で要求が成功する場合もある） 3001 = Bad request （要求の自動再試行は推奨されない）
message	string	エラーを説明する人間可読メッセージ。

プロパティ

タイプ

定義

errorCode

long

エラーを表す数値コード

有効な値：

3000 = Internal server error （再試行で要求が成功する場合もある）

3001 = Bad request （要求の自動再試行は推奨されない）

message

string

エラーを説明する人間可読メッセージ。